Skip to content
HeliosDB HeliosDB Lite

Query Timeout Protection - Quick Reference

What is it?

Query timeout protection prevents resource exhaustion by automatically terminating queries that run longer than a configured time limit.

Quick Start

Enable Timeout

config.toml
[storage]
query_timeout_ms = 30000  # 30 seconds (recommended for production)
Terminal window
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --config config.toml

The timeout applies to every query on the server. The default is 300000 ms (5 minutes); set a larger value for long-running batch work. 0 does not mean “no limit”: it times out every scanning query at once.

Handle Timeout Errors

A query that exceeds the limit fails with an error your client receives like any other SQL error:

Query timeout: Query exceeded timeout limit of 5000ms (elapsed: 5124ms)
import psycopg2


try:
    cur.execute("SELECT * FROM large_table")
except psycopg2.Error as e:
    if "Query timeout" in str(e):
        # fall back to a cheaper query, or retry later
        cur.connection.rollback()
    else:
        raise
EnvironmentTimeoutNotes
Development60000 or more60s or longer for debugging
Production3000030 seconds is a good default
Public API1000010 seconds for user-facing queries
Background Jobs3000005 minutes for batch processing (the default)
Admin Tools3600000One hour for maintenance operations

Different environments use different configuration files, for example config.dev.toml with a longer timeout and config.prod.toml with 30000.

Key Features

  • On by default: 300000 ms (5 minutes) when the setting is left out
  • Minimal overhead: <0.1% performance impact
  • Thread-safe: Works with parallel execution
  • Granular control: Configurable per database instance

Performance Impact

Check FrequencyOverhead
Every 1000 rows<0.1%

Figures from internal tests (HeliosDB Lite, timeout check every 1000 rows); reproduce on your own hardware. The server checks the clock more often than in that test: every 100 rows for timeouts of 100 ms or more, every 50 rows below 100 ms and every 10 rows below 10 ms.

Limitations

  1. Granularity: Checked every 100 rows (every 50 or 10 rows for timeouts under 100 ms or 10 ms), not every row
  2. DDL Operations: Not protected (CREATE TABLE, etc.)
  3. Blocking I/O: Timeout suspended during I/O operations

Troubleshooting

Query Always Timing Out

Problem: Legitimate queries are timing out

Solution:

  1. Increase timeout: query_timeout_ms = 60000 (60s)
  2. Optimize query (add indexes, reduce data scanned)
  3. Use LIMIT to reduce result set size

No Timeout Protection

Problem: Long queries still running

Solution:

  1. Check that query_timeout_ms is in the [storage] section
  2. Check that the server was started with --config pointing at that file
  3. Restart the server after changing the file

Timeout Too Strict

Problem: Complex analytical queries failing

Solution:

  1. Increase timeout for specific workloads
  2. Use batch processing for large operations
  3. Run maintenance on a separate instance with a larger timeout

Security Best Practices

  • Enable timeout in production
  • Set conservative limits for public APIs
  • Monitor timeout frequency
  • Log timeout events

Further Reading

Summary

Query timeout protection provides:

  • Protection against resource exhaustion
  • Minimal performance overhead (<0.1%)
  • Easy configuration (one line)
  • A 5-minute default that you can raise or lower

Recommended Action: Lower the timeout to 30 seconds for production deployments.