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. |
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],[execution],[aqe],[statistics],[optimizer],[oltp],[resilience],[udf],[cluster],[gpu], and[jit], including every sub-table: config-file-only. There is no generic environment-variable override pattern for these sections. See the canonical Environment Variables reference: nothing there names a setting under any of these sections.
If you need to change one of these 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.