Configuration reference

By the end of this page you will know the three surfaces that configure a ScramDB node, how they combine, and where to go for the exhaustive detail on each.

This section is a deep, exhaustive reference. If you just want a working config file fast, start with Configuration instead; come here when you need the complete picture of a specific env var, config key, or precedence rule.

Three surfaces, nested in order

ScramDB has exactly three configuration surfaces, and they nest in a fixed order:

1. Built-in defaults. Every setting ships with a real default. An absent config file, or an absent section within one, behaves exactly like that section written out at its defaults, byte-for-byte.
2. The TOML config file. Passed with -c / --config, default path scramdb-config.toml in the working directory. Every key lives under a [section] table; there is no flat top-level key. The file format is deliberately strict: an unrecognized top-level key is a hard parse error naming the field, not a silently ignored typo.
3. A small, fixed set of environment variables and CLI flags. This is not a generic per-field override mechanism. Four environment variables exist in total, and a handful of CLI flags interact with specific config-file keys. Everything else in the config file is config-file-only.

See Environment Variables for the canonical list of env vars, Config File for every section and key, and Precedence for exactly how the config file, CLI flags, and env vars combine when more than one of them touches the same setting.

Config is read once, at startup

ScramDB reads and validates its configuration once, when the process starts, and never again. There is no reload signal, no file-watcher, and no partially hot-reloadable subset. Changing any config file key or any environment variable requires a full restart of the process for the change to take effect. This is true for every setting in the system, without exception.

The one thing that looks like an exception and is not: SET statement_timeout = ... at the SQL session level overrides the server-wide [resilience] statement_timeout default for that session, live, with no restart. That is a session-level SQL setting (a Postgres GUC), not a config file or environment variable change, and it's out of scope for this reference. See Precedence for the full restart rule.

Where the config file lives

Pass the path explicitly:

scramdb --config /etc/scramdb/config.toml

Omit -c / --config and ScramDB looks for scramdb-config.toml in the working directory. There is no parent-directory search and no other fallback location: if that exact file isn't there, ScramDB fails to start rather than guessing at a location.

Every section, at a glance

Every top-level [section] name ScramDB recognizes, and where it's documented in this reference:

Section	Purpose	Covered in
[general]	Listen address, authentication, TLS, metrics port, license key, shutdown timing	Config File
[storage] and its sub-tables	Data directory, buffer pool, memory budgets, I/O backend, WAL, garbage collection, compaction, cold storage	Config File
[execution]	Query execution: workers, morsel size, join and spill tuning	Config File
[aqe]	Adaptive query execution for distributed shuffle joins	Config File
[statistics]	Automatic statistics collection for the planner	Config File
[optimizer]	Join-ordering search limits	Config File
[oltp]	Point-query fast path for single-row statements	Config File
[resilience]	Client liveness checks, statement/session timeouts, pool watchdog	Config File
[udf] and its sub-tables	The afterburner UDF runtime, invocation pool, and package registry policy	Config File
[gpu]	GPU acceleration	Config File
[jit]	Compiled-artifact cache sizing	Config File
[cluster] and its sub-tables	Multi-node clustering	Config File

Every field in every section has a default. Every one of those sections is optional; omit a section entirely and it behaves exactly as if you'd written it out with every field at its default value.

Licensing touches configuration in two places

Two settings you'll meet in this reference are gated by your license, not by the config parser itself:

• The Community edition has a 64 GiB data ceiling. Crossing it flips the node read-only for writes (reads keep working) until you drop back under the cap or upgrade; it auto-recovers with no restart needed. This isn't a config key you set, it's a property of the edition your license_key resolves to.
• A [cluster] section requires an Enterprise or Trial license. A Community-edition node with [cluster] present in its config refuses to start rather than running single-node with the section ignored. Your license also sets a ceiling on the number of nodes you're entitled to run.

See Editions and Clustering for the full licensing and cluster deployment story; this reference only covers the config keys and env vars themselves.

Backup and restore CLI

scramdb backup and scramdb restore are separate subcommands, not config-file settings, for taking a full backup and replaying the write-ahead log to a point in time. If you're looking for where the backup destination or WAL archive location is configured, that's [storage.wal.backup] and [storage.wal.archive] on the Config File page; the CLI subcommands themselves are covered on Configuration.

Where to go next

• Environment Variables - the canonical reference for every environment variable ScramDB reads, and which container-only variables are read by the Docker entrypoint instead of the engine.
• Config File - every section, every key, its type, its real default, and its effect, grouped the way a real config file reads top to bottom.
• Precedence - exactly which source wins when the config file, a CLI flag, and an environment variable all touch the same setting, and the one restart rule that applies to everything.