Precedence
By the end of this page you will know, for every setting where more than one configuration surface could apply, exactly which one wins, and the one rule that governs when a change actually takes effect.
The restart rule
ScramDB reads and validates its configuration exactly once, when the process starts. There is no reload signal, no config file watcher, and no partially hot-reloadable subset of settings. Every config file key and every environment variable requires a full process restart to take effect, without exception. This applies equally to a one-line [general] change and a deep [cluster.consensus] tuning value; nothing in this system distinguishes between them.
The one thing that looks like an exception and isn't: SET statement_timeout = ... at the SQL session level overrides the server-wide [resilience] statement_timeout default for that session, live, with no restart. That's a session-level SQL setting, not a config file or environment variable change, so it doesn't reset the rule above, it just doesn't need to.
Where more than one source can set the same thing
Most settings are config-file-only, with no CLI flag or environment variable that touches them at all. A short list of settings really can be set from more than one place; here is exactly how each one resolves, highest-precedence source first.
| Setting | Highest wins | Behavior |
|---|---|---|
pg_address | [general] pg_address in the config file | If the config file sets [general] pg_address, that value is used, provided it parses as a valid address; the --pg-address CLI flag is only used when the config file omits the key entirely (or the configured value fails to parse). |
pg_no_auth | Neither source can force it off | The CLI flag --pg-no-auth and [general] pg_no_auth in the config file are OR'd together: if either one enables it, authentication is disabled, and the other source can't override that back on. |
metrics_port | --metrics-port (CLI flag) | CLI flag, then [general] metrics_port in the config file, then the built-in default of 9090. 0 at any of those levels disables the metrics and health HTTP server entirely. |
license_key | SCRAMDB_LICENSE_KEY (environment variable) | If the environment variable is set, it's used; otherwise [general] license_key in the config file is used; if neither is set, the node runs as Community edition. |
| Config file path | -c / --config (CLI flag) | The flag defaults to scramdb-config.toml, so there's no real "no config file" mode: omitting the flag is equivalent to explicitly passing that literal filename, and ScramDB still tries to read and parse it. There's no parent-directory search. |
[execution] runtime_filters | The config file, when it sets the key | If the config file sets runtime_filters, that value governs, on or off, and the environment is never consulted. Only when the key is absent does SCRAMDB_RUNTIME_FILTERS decide: 0 turns runtime filters off, anything else (or an unset variable) leaves them on. |
[execution] copy_consumers | SCRAMDB_COPY_CONSUMERS (environment variable), when it parses | Read fresh from the environment on every COPY statement rather than cached at startup, so a change here takes effect on the server's very next COPY, with no restart, unlike every other row on this page. When it parses to a number it wins over the config value for that statement; 1 is the kill switch (single consumer) and 0 means auto-size, not "off". An unparsable or absent value falls back to [execution] copy_consumers. |
Settings with only one source
A few settings are worth calling out as config-file-only with no alternate path at all, since it's easy to expect an env var or flag that doesn't exist:
hba_file,tls_cert,tls_keyunder[general]: no CLI flag, no environment variable for any of the three.- Everything under
[storage],[statistics],[oltp],[resilience],[udf],[cluster],[gpu], and[jit], including every sub-table, plus every[execution]and[optimizer]key except the ones called out above and below: config-file-only. There is no generic environment-variable override pattern for these sections; the exceptions above and below are the whole list, not an example of a wider pattern.
A different shape, worth calling out separately: SCRAMDB_T4_SEMI_REVERSE doesn't override [optimizer] semi_reversal_skew_factor's value, it gates whether the optimizer ever acts on it. The config value is always read and validated; the optimizer only considers reversing a semi/anti-join's build and probe sides using it when SCRAMDB_T4_SEMI_REVERSE=1 is explicitly set. Unset, or any other value, and the threshold sits in the config with no effect.
If you need to change one of the config-file-only settings between environments (a staging vs. production buffer_pool_percent, for example), the way to do it is a different config file per environment, not an environment variable override.
Related pages
- Configuration Reference - the three configuration surfaces and how they nest.
- Environment Variables - the canonical list of what can come from the environment.
- Config File - every section and key, and its default when nothing else sets it.