These parameter descriptions are auto-generated first drafts and are still under review.
auth, engine, execution, and
storage — group related settings, and each block contains scalar values or further nested blocks.
Every file must declare the schema version it targets:
Value types
Each scalar parameter has one of the following types. The Type column in the reference below uses these names.Parameter kinds
The Type column also tells you an entry’s kind:- A scalar holds a single value of one of the types above (for example
stringorduration). - An object (shown as
object) is a nested block of named parameters. - A list (shown as
object[]) is a sequence of objects; every element repeats the same structure.
- required parameters must be set — the engine won’t start without them.
- optional parameters fall back to the listed Default Value when you omit them.
Overview
auth
endpoints
engine
execution
instance
logging
planner
schema_version
storage
Details
auth
object
default:"{}"
Authentication settings for the database. Authentication is disabled by default; set
auth.mode to enable native or OIDC authentication, then configure the matching block below.string
default:"https://localhost"
Identifier for this instance. In native mode it’s used as the JWT
iss (issuer) claim; in both native and OIDC modes it’s used as the expected aud (audience) claim. Defaults to https://localhost.enum
default:"disabled"
Selects how clients authenticate. Use
disabled for no authentication (the default), native to have PackDB issue and validate its own tokens, or oidc to validate tokens issued by an external identity provider. When you choose native or oidc, configure the matching block below.object
default:"null"
Settings for native authentication, used when
auth.mode is native. In this mode PackDB issues and validates its own JWTs.object
default:"null"
Bootstrap user created on startup so you can connect to a fresh instance. Provide a
name and a password. This is required when you run a single-engine instance with native authentication.string
required
Username for the bootstrap user created at startup in native authentication mode.
string
required
Password for the bootstrap user created at startup in native authentication mode.
object
default:"{}"
JWT settings for native mode. Because PackDB issues tokens itself in this mode, these settings control the lifetime and temporal validation of the tokens it generates.
duration
default:"30s"
Allowed clock skew when validating time-based JWT claims such as
exp, nbf, and iat. Tokens within this tolerance of the current time are still accepted. Defaults to 30s.duration
default:"1d"
Maximum age of a token, measured from its
iat (issued-at) claim. PackDB rejects tokens older than this even if they haven’t expired. Defaults to 1d.duration
default:"1h"
Lifetime of the access tokens that PackDB issues. After this duration a token expires and the client must obtain a new one. Defaults to
1h.enum
default:"RS256"
Algorithm used to sign issued tokens. Choose one of the RSA algorithms (
RS256, RS384, RS512) or ECDSA algorithms (ES256, ES384, ES512). Defaults to RS256.object[]
default:"[]"
Keys used to sign issued tokens. Each entry points to a private key on disk. Leave the list empty to run in development mode, where PackDB generates an ephemeral signing key on startup.
string
required
Identifier for this signing key. PackDB publishes it as the JWT
kid (key ID) header so clients can select the correct key when verifying a token.string
required
Filesystem path to the PEM-encoded private key used for signing.
object
default:"null"
Settings for OIDC authentication, used when
auth.mode is oidc. In this mode PackDB validates tokens issued by one or more external identity providers and doesn’t issue tokens itself.object
default:"{}"
JWT validation settings for OIDC mode. Because the upstream identity provider issues the tokens, only validation settings apply here — there are no token-issuance options.
duration
default:"30s"
Allowed clock skew when validating time-based JWT claims such as
exp, nbf, and iat. Tokens within this tolerance of the current time are still accepted. Defaults to 30s.duration
default:"1d"
Maximum age of a token, measured from its
iat (issued-at) claim. PackDB rejects tokens older than this even if they haven’t expired. Defaults to 1d.boolean
default:"false"
When enabled, connections over the Postgres wire protocol can fall back to password-based authentication instead of OIDC tokens. Disabled by default.
object[]
default:"[]"
Trusted OIDC identity providers. A single provider is supported at launch; the list form leaves room for multiple providers in the future.
object
default:"{}"
Controls how PackDB refreshes the provider’s discovery document.
duration
default:"1d"
How often PackDB re-fetches the provider’s OpenID configuration (discovery) document. Defaults to
1d.string
required
URL of the provider’s OpenID Connect discovery document — the
.../.well-known/openid-configuration endpoint. PackDB reads the provider’s metadata, including its JWKS URL, from this document.object
default:"{}"
Just-in-time (JIT) provisioning settings. When enabled, PackDB creates a user automatically the first time someone authenticates through this provider.
string
default:"public"
Role granted to users created through just-in-time provisioning. Defaults to
public.boolean
default:"false"
Whether to create users automatically on first login through this provider. Disabled by default.
object
default:"{}"
Controls how PackDB caches the provider’s JSON Web Key Set (JWKS), which it uses to verify token signatures.
duration
default:"1h"
How long PackDB caches the provider’s JWKS document before re-fetching it. Defaults to
1h.string
required
Name or alias for this provider. PackDB uses it to identify the provider in logs and configuration.
string
required
Template that maps OIDC token claims to a PackDB username. Reference claims with
{{ claim }} syntax — for example {{ email }}, {{ sub }}, or {{ iss }}|{{ sub }} to namespace usernames by issuer.endpoints
object
default:"{}"
Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol.
object
default:"{}"
HTTP listener configuration for the query API.
object[]
default:"[]"
List of HTTP listener bindings. You can define a TCP listener and a Unix-socket listener, each at most once.
string
default:"null"
Filesystem path for a Unix-domain-socket HTTP listener. Required for
unix listeners; omit it for tcp listeners.integer
default:"null"
TCP port for an HTTP listener (for example,
8123). Required for tcp listeners; omit it for unix listeners.enum
required
Listener transport:
tcp (network socket) or unix (Unix-domain socket).object
default:"{}"
PostgreSQL wire-protocol listener configuration. Clients connect using standard Postgres drivers and
psql.object[]
default:"[]"
List of PostgreSQL listener bindings. TCP only — Unix sockets aren’t supported for the Postgres protocol.
string
default:"null"
Not used for PostgreSQL listeners; Unix-domain sockets aren’t supported for the Postgres protocol.
integer
default:"null"
TCP port for PostgreSQL connections (for example,
5432). Required for every Postgres listener.enum
required
Listener transport for PostgreSQL. Only
tcp is supported.engine
object
default:"{}"
Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting.
object
default:"null"
Background auto-vacuum tuning. Auto-vacuum compacts and cleans up tablets in the background. It’s disabled by default; every field is optional and overrides the built-in default only when you set it.
integer
default:"null"
How frequently the engine assesses tablets to decide whether an auto-vacuum job is needed.
integer
default:"null"
Debugging knob: artificial delay, in milliseconds, inserted before an auto-vacuum job commits. Intended for testing only.
boolean
default:"null"
Whether background auto-vacuum runs. Disabled by default.
integer
default:"null"
Maximum number of auto-vacuum jobs allowed to run concurrently.
integer
default:"null"
Maximum number of tablets processed in a single auto-vacuum job.
float
default:"null"
Fraction of engine memory that auto-vacuum may use while running.
integer
default:"null"
Minimum number of tablets needing cleanup before an auto-vacuum job is triggered.
boolean
default:"null"
Whether to trigger an auto-vacuum assessment on the first DML statement after startup.
string
default:"null"
Unique identifier for this engine cluster. Required when multi-cluster broadcasting is enabled, where it tags outbound requests for cross-cluster coordination.
integer
default:"null"
Zero-based ordinal of this cluster within a multi-cluster deployment. Required when multi-cluster broadcasting is enabled, to distinguish cluster instances.
object
default:"{}"
Tablet memory-eviction policy, controlling when tablets are evicted from in-memory caches to disk as memory fills.
float
default:"1.5"
Upper bound on how many tablets the node keeps resident, expressed as tablets per MB of total memory. Defaults to
1.5. Caps tablet residency relative to available memory.float
default:"0.4"
Memory-usage fraction (0.0–1.0, default
0.4) that governs soft eviction of least-recently-used tablets. Soft-evicted tablets remain available on disk and are re-cached on access.float
default:"0.2"
Memory-usage fraction (0.0–1.0, default
0.2) that governs hard eviction of tablets from memory to reclaim space.integer
default:"1800"
Minimum age in seconds a tablet must reach before it becomes eligible for eviction from memory. Defaults to
1800 (30 minutes).integer
default:"21600"
Age in seconds after which an unused tablet is fully evicted from the node — dropped from the local disk cache to reclaim space. Defaults to
21600 (6 hours).string
default:"default-engine-id"
Human-readable identifier for this engine, shown in logs, metrics, and system views. Defaults to
default-engine-id.byte size
default:"0B"
Maximum memory the server may use (bytes, or a size such as
8GiB). When 0 (the default), the limit is derived from host RAM using max_server_memory_usage_to_ram_ratio and max_server_memory_usage_headroom_bytes.byte size
default:"0B"
Amount of host memory to keep free (bytes, or a size). Used with the ratio to cap server memory when
max_server_memory_usage isn’t set explicitly. Default 0.float
default:"0.9"
Fraction of host RAM (0.0–1.0, default
0.9) the engine may use when max_server_memory_usage isn’t set explicitly.integer
default:"12"
How many times per minute the engine collects and emits metrics. Default
12 (every five seconds).object
default:"null"
Multi-cluster broadcast configuration for query execution across engine clusters. Omit this block for a standalone or single-cluster engine.
string
required
Address (
host:port) of the multi-cluster broadcast service. Required and non-empty when multi-cluster broadcasting is enabled.boolean
default:"false"
Whether to use TLS when connecting to the broadcast endpoint. Default
false.integer
default:"0"
Soft limit on rows broadcast per execution stage across the cluster. Default
0 (unlimited); set a positive value to cap intermediate result sizes.object[]
default:"null"
List of engine nodes in this instance. When omitted, a single node on
127.0.0.1 with default ports is used.integer
default:"5678"
TCP port for this node’s Aragog distributed-execution service. Default
5678.string
required
Hostname or IP address of this node, used by other nodes and services to reach it.
integer
default:"16000"
TCP port for this node’s Shufflepuff data-shuffle service. Default
16000.integer
default:"3434"
TCP port for this node’s Storage Agent (local tablet I/O). Default
3434.integer
default:"1717"
TCP port for this node’s Storage Manager (tablet lifecycle and metadata). Default
1717.duration
default:"1m"
How long to wait for in-flight queries to finish during graceful shutdown before forcing termination. Default
1m.execution
object
default:"{}"
Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.
object
default:"{}"
Admission control settings that govern how many queries run concurrently and how memory is shared, to avoid out-of-memory conditions and improve throughput.
boolean
default:"false"
Enable admission control. When enabled, queries are queued and prioritized based on available memory and concurrency limits. Default
false.integer
default:"100"
Maximum number of concurrently admitted queries; the per-node limit scales with cluster size. Default
100.float
default:"0.75"
Cap on the extra memory an out-of-memory retry may request, as a fraction of available memory. Default
0.75.integer
default:"3"
Maximum number of automatic retries when a query fails with an out-of-memory error. Default
3.integer
default:"10"
After a query waits this many seconds at the front of the admission queue, its estimated memory requirement is reduced to improve its chance of admission. Default
10.integer
default:"3600"
Minimum interval, in seconds, between warnings logged when no query can be admitted. Default
3600.integer
default:"300"
Log a warning when no query has been admitted for this many seconds. Default
300.float
default:"0.9"
Fraction of the memory tracker’s hard limit that admission control may allocate per node. Default
0.9.enum
default:"reevaluate"
Execution mode for AI mutation queries:
native_only, reevaluate (default), or hybrid.boolean
default:"true"
Enable the Shufflepuff shuffle subsystem used for distributed (multi-node) query execution. When enabled, the engine registers io_uring buffers at startup, which requires sufficient locked memory (
RLIMIT_MEMLOCK). Default true.integer
default:"3"
On-disk format version for Hybrid Headers tablet storage. Default
3: version 1 is the original format, 2 adds primary-index compression, and 3 adds compact/subcompact tablets.integer
default:"2"
Compression level for the Hybrid Headers primary index. Default
2; the valid range depends on the chosen method.enum
default:"BROTLI"
Compression algorithm for the Hybrid Headers primary index: one of
none, gzip, zlib, xz, zstd, brotli, lz4, or snappy. Default brotli.integer
default:"0"
Maximum number of threads used to execute a single query.
0 (default) lets the engine choose automatically.boolean
default:"true"
Allow background merging of committed tablets during maintenance. Default
true.integer
default:"104857600"
Minimum uncompressed size, in bytes, for a tablet to use the wide format instead of the compact format.
integer
default:"10000"
Maximum number of compiled regular expressions to cache. Default
10000.boolean
default:"true"
Cache tablet-assignment information on the storage-manager proxy to reduce metadata lookups. Default
true.instance
object
default:"{}"
Instance identity and deployment topology — the instance ID and whether this is a single-engine or multi-engine deployment.
ulid
default:"01KP98J0000000000000000000"
Unique instance identifier in ULID format. Set automatically in cloud-managed deployments; override it for custom Firebolt Core setups.
object
default:"null"
Multi-engine settings. Required when
instance.type is multi_engine and ignored for single_engine. Configures the connection to a shared, remote metadata service.string
required
Address (
host:port) of the external Pensieve metadata service. Required when instance.type is multi_engine.enum
default:"single_engine"
Deployment topology:
single_engine (metadata runs locally) or multi_engine (metadata served by an external Pensieve service). Default single_engine.logging
object
default:"{}"
Logging configuration — the default level, output format, per-component overrides, and output sinks.
object[]
default:"[]"
Per-component log-level overrides. Each entry sets a level for one logger component, independent of the global default.
enum
required
Log level for this component, overriding
logging.level. One of trace, debug, info, warn, error, or fatal.string
required
Name of the logger component this override applies to.
enum
default:"json"
Log output format:
text (human-readable) or json (structured). Default json.enum
default:"info"
Default log level for all messages: one of
trace, debug, info, warn, error, or fatal. Default info. Components and sinks can override it.object[]
default:"null"
Log output targets. Each sink writes to stderr or a file. When omitted, a single stderr sink at the global level is installed.
object
default:"null"
File-sink settings. Required when the sink
type is file; must be absent when the type is stderr.string
required
Filesystem path the file sink writes to. Required when the sink type is
file.enum
default:"null"
Log level for this sink. Inherits
logging.level when omitted. One of trace, debug, info, warn, error, or fatal.enum
required
Sink destination:
stderr or file. Required for each sink.planner
object
default:"{}"
Query planner configuration.
object
default:"{}"
Settings for the automated column-statistics cache used by the optimizer.
integer
default:"104857600"
Maximum size, in bytes, of the automated column-statistics cache. Default 100 MiB (
104857600). Raise it to cache more statistics, lower it to reduce memory use.schema_version
string
required
Version of the configuration schema. Required at the root and must be
"1.0". It lets the configuration format evolve through future migrations.storage
object
default:"{}"
Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior.
boolean
default:"false"
Allow manual garbage collection of orphaned tablets via
CALL collect_garbage(). Default false.string
default:"null"
Storage URI scheme (for example,
s3://, gs://, or azure://). Defaults to the scheme for the configured storage.type; set it only to override that default.object
default:"null"
AWS settings for S3-backed managed tables. Set this block only when
storage.type is s3.string
default:"null"
AWS IAM role assumed for federated, cross-account or cross-tenant S3 access. Leave unset to use the engine’s own AWS identity.
object
default:"null"
Azure settings for Blob-Storage-backed managed tables. Set this block only when
storage.type is abs or azurite.string
default:"null"
Client ID of a federated Azure service principal for cross-tenant access. Leave unset to use the engine’s own workload identity.
string
default:"null"
Azure Blob Storage account name for managed tables, accessed via workload identity. Required when
storage.type is abs.string
default:"null"
Bucket used for managed-table objects. When set, it overrides the default bucket — useful for Firebolt Core to point at a custom location.
integer
default:"0"
Maximum tablets cleaned per
collect_garbage() call. 0 (default) means no per-query limit; set a positive value to process large cleanups in batches.string
default:"null"
Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.
boolean
default:"false"
Allow
CREATE TABLE to specify a LOCATION for managed tables. When false (default), managed tables live only in the system-managed bucket.integer
default:"604800"
Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage. Default
604800 (7 days).object
default:"null"
Google Cloud settings for GCS-backed managed tables. Set this block only when
storage.type is gcs.string
default:"null"
GCP service account used for federated, cross-project or cross-tenant GCS access. Leave unset to use the engine’s own workload identity.
object
default:"null"
MinIO settings for local or self-hosted S3-compatible storage. Set this block only when
storage.type is minio.string
required
MinIO server endpoint URL (for example,
http://localhost:9000). Required when storage.type is minio.enum
default:"s3"
Object-storage provider for managed tables:
s3, gcs, abs, azurite, or minio. Default s3. Set exactly one matching provider block (aws, gcp, azure, or minio).integer
default:"null"
Maximum number of retries for object-storage uploads. Leave unset to use the cloud SDK default.