Environment variables
Configuration for the datahashi engine, Query Runner, live cache, and rollups.
Updated
This page lists environment variables for hashi-engine and query-runner.
Engine core
| Variable | Default | Description |
|---|---|---|
ENGINE_ADDR |
:8081 |
HTTP query and MCP listen address. |
ENGINE_MODEL_DIR |
(Required in headless) | Directory with model.yaml, warehouse.yaml, and related files. |
ENGINE_API_KEY |
(Required if no auth.yaml) | Static Bearer token for /v1/* and /mcp. |
ENGINE_ALLOW_SQL |
false |
When true, clients may request compiled SQL in the response body. |
ENGINE_MAX_ROWS |
10000 |
Hard cap on returned rows per query. Overrides client limit. Set 0 for unlimited. |
ENGINE_MAX_BYTES |
0 |
Per-query warehouse scanned-byte ceiling. 0 disables the cap. |
ENGINE_DIMENSION_VALUES_CAP |
1000 |
Maximum distinct values from POST /v1/dimension-values. |
MAX_CONCURRENT_QUERIES |
16 |
Per-process concurrent query limit. 0 disables the limit. |
WAREHOUSE_TTL |
5m |
Cached Query Runner connection reuse TTL. |
ENGINE_RUNNER_ALLOW_PRIVATE_EGRESS |
false |
Set true to let the engine dial runners on private, loopback, or RFC1918 addresses. Include mode implies true. |
SQL wire protocol (PostgreSQL listener)
| Variable | Default | Description |
|---|---|---|
ENGINE_SQL_ADDR |
(Unset / off) | Port for the PostgreSQL wire listener (for example :5432). |
ENGINE_SQL_TLS_CERT_FILE |
(Unset) | Path to the PEM certificate for TLS. |
ENGINE_SQL_TLS_KEY_FILE |
(Unset) | Path to the PEM private key for TLS. |
MCP OAuth discovery (RFC 9728)
| Variable | Default | Description |
|---|---|---|
ENGINE_OAUTH_RESOURCE |
(Unset) | Public MCP resource URL (for example https://engine.example.com/mcp). Enables discovery. |
ENGINE_OAUTH_AUTHZ_SERVERS |
(Unset) | Comma-separated list of trusted authorization server issuer URLs. |
Query budget
| Variable | Default | Description |
|---|---|---|
ENGINE_BUDGET_WINDOW |
1h |
Rolling window for budget accounting. |
ENGINE_BUDGET_MAX_BYTES |
0 |
Scanned-byte ceiling per tenant over the window. 0 disables the cap. |
ENGINE_BUDGET_MAX_QUERIES |
0 |
Maximum query count per tenant over the window. 0 disables the cap. |
ENGINE_LANES |
false |
Admit by lane: interactive, then MCP, then CSV and batch. |
ENGINE_LANE_LLM_MAX |
half of MAX_CONCURRENT_QUERIES |
Running queries the MCP lane may hold. 0 means no cap. Needs ENGINE_LANES. |
ENGINE_LANE_BATCH_MAX |
a quarter of MAX_CONCURRENT_QUERIES |
Running queries the batch lane may hold. Rollup builds and cache warming are batch. |
ENGINE_LANE_MAX_QUEUE |
64 |
Waiters per lane. The next request gets 503 overloaded. |
ENGINE_LANE_MAX_WAIT |
30s |
A waiter not admitted in this time gets 503 overloaded and Retry-After. |
Live cache and warming
| Variable | Default | Description |
|---|---|---|
LIVE_CACHE_TTL |
0 (off) |
In-flight and short-lived duplicate query cache window (for example 10s). |
LIVE_CACHE_MAX_ENTRIES |
1000 |
Maximum cache entries in process memory. |
LIVE_CACHE_WARM_ENABLED |
false |
Refresh proven-hot queries before expiry. |
LIVE_CACHE_WARM_HIT_THRESHOLD |
3 |
Repeat hits required before an entry is warm-eligible. |
LIVE_CACHE_WARM_MAX_CONCURRENT |
4 |
Maximum background goroutines for cache warming. |
LIVE_CACHE_WARM_TIMEOUT |
30s, or LIVE_CACHE_TTL |
Maximum execution deadline per warming query. |
Shared Redis cache (multi-node)
| Variable | Default | Description |
|---|---|---|
REDIS_ADDR |
(Unset / off) | Redis host:port for a cross-node result cache. |
REDIS_PASSWORD |
(Unset) | Optional Redis password. |
REDIS_RESULT_TTL |
LIVE_CACHE_TTL, or 5s |
Shared cache result TTL. |
REDIS_KEY_PREFIX |
engine:qr |
Redis key namespace prefix. |
Rollup storage
| Variable | Default | Description |
|---|---|---|
ENGINE_ROLLUP_STORE_DIR |
(Unset / off) | Directory for Parquet files and catalog. Enables rollups. |
ENGINE_ROLLUP_REFRESH_INTERVAL |
0 |
Maximum age of rollups with no declared refresh:. |
ENGINE_ROLLUP_REFRESH_POLL |
1m |
How often to poll for rollups due for rebuild. |
Community loopback runner
| Variable | Default | Description |
|---|---|---|
ENGINE_INCLUDE_RUNNER |
true when QUERY_RUNNER_WAREHOUSE_DSN is set, otherwise false |
Start query-runner as a loopback child process. |
QUERY_RUNNER_WAREHOUSE_DSN |
(Unset) | DSN handed to the child runner in include mode. |
QUERY_RUNNER_CONFIG |
/etc/query-runner/config.yaml |
Configuration file for the bundled child runner. |
ENGINE_RUNNER_BIN |
query-runner on PATH, else /usr/local/bin/query-runner |
Path to the query-runner executable. |
Query Runner as its own process
| Variable | Default | Description |
|---|---|---|
QUERY_RUNNER_LISTEN |
replaces file listen (:8443) |
Public listener. There is no env var for admin_listen. That file key defaults to 127.0.0.1:9090. |
QUERY_RUNNER_ENABLED |
replaces policy.enabled |
true or false. false pauses the runner. |
QUERY_RUNNER_WAREHOUSE_DSN |
(Unset) | DSN when a warehouse sets dsn_env to this name. It is not a fallback for every warehouse. |
Next: REST API · Install Query Runner.