> ## Documentation Index
> Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Reference for the YAML configuration file that configures a Firebolt engine.

# Engine configuration reference

<Info>
  These parameter descriptions are auto-generated first drafts and are still under review.
</Info>

A Firebolt engine reads its settings from a single YAML configuration file. This page documents
every supported parameter, grouped by the top-level block it belongs to, along with its type,
whether it's required, and its default value.

The file is a nested YAML document. Top-level blocks — such as `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:

```yaml theme={null}
schema_version: "1.0"

auth:
  mode: native
engine:
  id: my-engine
storage:
  type: s3
  bucket_name: my-bucket
```

## Value types

Each scalar parameter has one of the following types. The **Type** column in the reference below
uses these names.

| Type        | Description                                                                  | Example                      |
| :---------- | :--------------------------------------------------------------------------- | :--------------------------- |
| `string`    | Free-form text.                                                              | `my-engine`                  |
| `integer`   | A whole number.                                                              | `8123`                       |
| `float`     | A decimal number.                                                            | `0.9`                        |
| `boolean`   | `true` or `false`.                                                           | `true`                       |
| `duration`  | A time span written as a number with a unit suffix (`s`, `m`, `h`, `d`).     | `30s`, `1h`, `1d`            |
| `byte size` | A size in bytes, optionally with a unit suffix (`KB`, `MB`, `GB`, `GiB`, …). | `8GiB`, `100MB`              |
| `ulid`      | A [ULID](https://github.com/ulid/spec) identifier.                           | `01KP98J0000000000000000000` |
| `enum`      | One of a fixed set of values, listed in the parameter's description.         | `s3`                         |

## 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 `string` or `duration`).
* 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.

Each parameter is also marked as either required or optional:

* <Badge color="red" size="sm" className="font-mono">required</Badge> parameters must be set — the engine won't start without them.
* <Badge color="blue" size="sm" className="font-mono">optional</Badge> parameters fall back to the listed **Default Value** when you omit them.

## Overview

### auth

| Path                                                                                                               | Type       | Required                                                             | Default Value       | Description                                                                                                                      |
| :----------------------------------------------------------------------------------------------------------------- | :--------- | :------------------------------------------------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------- |
| [`auth`](#param-auth)                                                                                              | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | Authentication settings for the database.                                                                                        |
| [`auth.instance_id`](#param-auth-instance-id)                                                                      | `string`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `https://localhost` | Identifier for this instance.                                                                                                    |
| [`auth.mode`](#param-auth-mode)                                                                                    | `enum`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `disabled`          | Selects how clients authenticate.                                                                                                |
| [`auth.native`](#param-auth-native)                                                                                | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Settings for native authentication, used when `auth.mode` is `native`.                                                           |
| [`auth.native.initial_user`](#param-auth-native-initial-user)                                                      | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Bootstrap user created on startup so you can connect to a fresh instance.                                                        |
| [`auth.native.initial_user.name`](#param-auth-native-initial-user-name)                                            | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Username for the bootstrap user created at startup in native authentication mode.                                                |
| [`auth.native.initial_user.password`](#param-auth-native-initial-user-password)                                    | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Password for the bootstrap user created at startup in native authentication mode.                                                |
| [`auth.native.jwt`](#param-auth-native-jwt)                                                                        | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | JWT settings for native mode.                                                                                                    |
| [`auth.native.jwt.clock_skew_tolerance`](#param-auth-native-jwt-clock-skew-tolerance)                              | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `30s`               | Allowed clock skew when validating time-based JWT claims such as `exp`, `nbf`, and `iat`.                                        |
| [`auth.native.jwt.max_token_age`](#param-auth-native-jwt-max-token-age)                                            | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1d`                | Maximum age of a token, measured from its `iat` (issued-at) claim.                                                               |
| [`auth.native.jwt.token_expiry`](#param-auth-native-jwt-token-expiry)                                              | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1h`                | Lifetime of the access tokens that PackDB issues.                                                                                |
| [`auth.native.signing_algorithm`](#param-auth-native-signing-algorithm)                                            | `enum`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `RS256`             | Algorithm used to sign issued tokens.                                                                                            |
| [`auth.native.signing_keys`](#param-auth-native-signing-keys)                                                      | `object[]` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `[]`                | Keys used to sign issued tokens.                                                                                                 |
| [`auth.native.signing_keys[*].id`](#param-auth-native-signing-keys-id)                                             | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Identifier for this signing key.                                                                                                 |
| [`auth.native.signing_keys[*].private_key_path`](#param-auth-native-signing-keys-private-key-path)                 | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Filesystem path to the PEM-encoded private key used for signing.                                                                 |
| [`auth.oidc`](#param-auth-oidc)                                                                                    | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Settings for OIDC authentication, used when `auth.mode` is `oidc`.                                                               |
| [`auth.oidc.jwt`](#param-auth-oidc-jwt)                                                                            | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | JWT validation settings for OIDC mode.                                                                                           |
| [`auth.oidc.jwt.clock_skew_tolerance`](#param-auth-oidc-jwt-clock-skew-tolerance)                                  | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `30s`               | Allowed clock skew when validating time-based JWT claims such as `exp`, `nbf`, and `iat`.                                        |
| [`auth.oidc.jwt.max_token_age`](#param-auth-oidc-jwt-max-token-age)                                                | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1d`                | Maximum age of a token, measured from its `iat` (issued-at) claim.                                                               |
| [`auth.oidc.postgres_password_fallback_enabled`](#param-auth-oidc-postgres-password-fallback-enabled)              | `boolean`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `false`             | When enabled, connections over the Postgres wire protocol can fall back to password-based authentication instead of OIDC tokens. |
| [`auth.oidc.providers`](#param-auth-oidc-providers)                                                                | `object[]` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `[]`                | Trusted OIDC identity providers.                                                                                                 |
| [`auth.oidc.providers[*].discovery`](#param-auth-oidc-providers-discovery)                                         | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | Controls how PackDB refreshes the provider's discovery document.                                                                 |
| [`auth.oidc.providers[*].discovery.refresh_interval`](#param-auth-oidc-providers-discovery-refresh-interval)       | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1d`                | How often PackDB re-fetches the provider's OpenID configuration (discovery) document.                                            |
| [`auth.oidc.providers[*].discovery_url`](#param-auth-oidc-providers-discovery-url)                                 | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | URL of the provider's OpenID Connect discovery document — the `.../.well-known/openid-configuration` endpoint.                   |
| [`auth.oidc.providers[*].jit_provisioning`](#param-auth-oidc-providers-jit-provisioning)                           | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | Just-in-time (JIT) provisioning settings.                                                                                        |
| [`auth.oidc.providers[*].jit_provisioning.default_role`](#param-auth-oidc-providers-jit-provisioning-default-role) | `string`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `public`            | Role granted to users created through just-in-time provisioning.                                                                 |
| [`auth.oidc.providers[*].jit_provisioning.enabled`](#param-auth-oidc-providers-jit-provisioning-enabled)           | `boolean`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `false`             | Whether to create users automatically on first login through this provider.                                                      |
| [`auth.oidc.providers[*].jwks`](#param-auth-oidc-providers-jwks)                                                   | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | Controls how PackDB caches the provider's JSON Web Key Set (JWKS), which it uses to verify token signatures.                     |
| [`auth.oidc.providers[*].jwks.cache_ttl`](#param-auth-oidc-providers-jwks-cache-ttl)                               | `duration` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1h`                | How long PackDB caches the provider's JWKS document before re-fetching it.                                                       |
| [`auth.oidc.providers[*].name`](#param-auth-oidc-providers-name)                                                   | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Name or alias for this provider.                                                                                                 |
| [`auth.oidc.providers[*].username_mapping`](#param-auth-oidc-providers-username-mapping)                           | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Template that maps OIDC token claims to a PackDB username.                                                                       |

### endpoints

| Path                                                                               | Type       | Required                                                             | Default Value | Description                                                                                                               |
| :--------------------------------------------------------------------------------- | :--------- | :------------------------------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------ |
| [`endpoints`](#param-endpoints)                                                    | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol. |
| [`endpoints.http`](#param-endpoints-http)                                          | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | HTTP listener configuration for the query API.                                                                            |
| [`endpoints.http.listeners`](#param-endpoints-http-listeners)                      | `object[]` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `[]`          | List of HTTP listener bindings.                                                                                           |
| [`endpoints.http.listeners[*].path`](#param-endpoints-http-listeners-path)         | `string`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Filesystem path for a Unix-domain-socket HTTP listener.                                                                   |
| [`endpoints.http.listeners[*].port`](#param-endpoints-http-listeners-port)         | `integer`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | TCP port for an HTTP listener (for example, `8123`).                                                                      |
| [`endpoints.http.listeners[*].type`](#param-endpoints-http-listeners-type)         | `enum`     | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | Listener transport: `tcp` (network socket) or `unix` (Unix-domain socket).                                                |
| [`endpoints.postgres`](#param-endpoints-postgres)                                  | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | PostgreSQL wire-protocol listener configuration.                                                                          |
| [`endpoints.postgres.listeners`](#param-endpoints-postgres-listeners)              | `object[]` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `[]`          | List of PostgreSQL listener bindings.                                                                                     |
| [`endpoints.postgres.listeners[*].path`](#param-endpoints-postgres-listeners-path) | `string`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Not used for PostgreSQL listeners; Unix-domain sockets aren't supported for the Postgres protocol.                        |
| [`endpoints.postgres.listeners[*].port`](#param-endpoints-postgres-listeners-port) | `integer`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | TCP port for PostgreSQL connections (for example, `5432`).                                                                |
| [`endpoints.postgres.listeners[*].type`](#param-endpoints-postgres-listeners-type) | `enum`     | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | Listener transport for PostgreSQL.                                                                                        |

### engine

| Path                                                                                                                                    | Type        | Required                                                             | Default Value       | Description                                                                                                                                      |
| :-------------------------------------------------------------------------------------------------------------------------------------- | :---------- | :------------------------------------------------------------------- | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| [`engine`](#param-engine)                                                                                                               | `object`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting. |
| [`engine.auto_vacuum`](#param-engine-auto-vacuum)                                                                                       | `object`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Background auto-vacuum tuning.                                                                                                                   |
| [`engine.auto_vacuum.assessment_frequency`](#param-engine-auto-vacuum-assessment-frequency)                                             | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | How frequently the engine assesses tablets to decide whether an auto-vacuum job is needed.                                                       |
| [`engine.auto_vacuum.debug_sleep_before_commit_ms`](#param-engine-auto-vacuum-debug-sleep-before-commit-ms)                             | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Debugging knob: artificial delay, in milliseconds, inserted before an auto-vacuum job commits.                                                   |
| [`engine.auto_vacuum.enabled`](#param-engine-auto-vacuum-enabled)                                                                       | `boolean`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Whether background auto-vacuum runs.                                                                                                             |
| [`engine.auto_vacuum.max_concurrency`](#param-engine-auto-vacuum-max-concurrency)                                                       | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Maximum number of auto-vacuum jobs allowed to run concurrently.                                                                                  |
| [`engine.auto_vacuum.max_tablets_in_job`](#param-engine-auto-vacuum-max-tablets-in-job)                                                 | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Maximum number of tablets processed in a single auto-vacuum job.                                                                                 |
| [`engine.auto_vacuum.memory_allowance`](#param-engine-auto-vacuum-memory-allowance)                                                     | `float`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Fraction of engine memory that auto-vacuum may use while running.                                                                                |
| [`engine.auto_vacuum.min_bad_tablets_threshold`](#param-engine-auto-vacuum-min-bad-tablets-threshold)                                   | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Minimum number of tablets needing cleanup before an auto-vacuum job is triggered.                                                                |
| [`engine.auto_vacuum.run_on_first_dml`](#param-engine-auto-vacuum-run-on-first-dml)                                                     | `boolean`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Whether to trigger an auto-vacuum assessment on the first DML statement after startup.                                                           |
| [`engine.cluster_id`](#param-engine-cluster-id)                                                                                         | `string`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Unique identifier for this engine cluster.                                                                                                       |
| [`engine.cluster_ordinal`](#param-engine-cluster-ordinal)                                                                               | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Zero-based ordinal of this cluster within a multi-cluster deployment.                                                                            |
| [`engine.eviction`](#param-engine-eviction)                                                                                             | `object`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                | Tablet memory-eviction policy, controlling when tablets are evicted from in-memory caches to disk as memory fills.                               |
| [`engine.eviction.max_tablets_per_mb_of_total_memory`](#param-engine-eviction-max-tablets-per-mb-of-total-memory)                       | `float`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1.5`               | Upper bound on how many tablets the node keeps resident, expressed as tablets per MB of total memory.                                            |
| [`engine.eviction.tablet_eviction_soft_threshold`](#param-engine-eviction-tablet-eviction-soft-threshold)                               | `float`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0.4`               | Memory-usage fraction (0.0–1.0, default `0.4`) that governs soft eviction of least-recently-used tablets.                                        |
| [`engine.eviction.tablet_eviction_threshold`](#param-engine-eviction-tablet-eviction-threshold)                                         | `float`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0.2`               | Memory-usage fraction (0.0–1.0, default `0.2`) that governs hard eviction of tablets from memory to reclaim space.                               |
| [`engine.eviction.tablet_min_ttl_before_memory_eviction_seconds`](#param-engine-eviction-tablet-min-ttl-before-memory-eviction-seconds) | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1800`              | Minimum age in seconds a tablet must reach before it becomes eligible for eviction from memory.                                                  |
| [`engine.eviction.tablet_ttl_before_full_eviction_seconds`](#param-engine-eviction-tablet-ttl-before-full-eviction-seconds)             | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `21600`             | Age in seconds after which an unused tablet is fully evicted from the node — dropped from the local disk cache to reclaim space.                 |
| [`engine.id`](#param-engine-id)                                                                                                         | `string`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `default-engine-id` | Human-readable identifier for this engine, shown in logs, metrics, and system views.                                                             |
| [`engine.max_server_memory_usage`](#param-engine-max-server-memory-usage)                                                               | `byte size` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0B`                | Maximum memory the server may use (bytes, or a size such as `8GiB`).                                                                             |
| [`engine.max_server_memory_usage_headroom_bytes`](#param-engine-max-server-memory-usage-headroom-bytes)                                 | `byte size` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0B`                | Amount of host memory to keep free (bytes, or a size).                                                                                           |
| [`engine.max_server_memory_usage_to_ram_ratio`](#param-engine-max-server-memory-usage-to-ram-ratio)                                     | `float`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `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.                            |
| [`engine.metrics_collection_frequency_per_minute`](#param-engine-metrics-collection-frequency-per-minute)                               | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `12`                | How many times per minute the engine collects and emits metrics.                                                                                 |
| [`engine.multi_cluster`](#param-engine-multi-cluster)                                                                                   | `object`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | Multi-cluster broadcast configuration for query execution across engine clusters.                                                                |
| [`engine.multi_cluster.broadcast_endpoint`](#param-engine-multi-cluster-broadcast-endpoint)                                             | `string`    | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Address (`host:port`) of the multi-cluster broadcast service.                                                                                    |
| [`engine.multi_cluster.broadcast_ssl_enabled`](#param-engine-multi-cluster-broadcast-ssl-enabled)                                       | `boolean`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `false`             | Whether to use TLS when connecting to the broadcast endpoint.                                                                                    |
| [`engine.multi_cluster.broadcast_tuple_limit_per_engine_cluster`](#param-engine-multi-cluster-broadcast-tuple-limit-per-engine-cluster) | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0`                 | Soft limit on rows broadcast per execution stage across the cluster.                                                                             |
| [`engine.nodes`](#param-engine-nodes)                                                                                                   | `object[]`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`              | List of engine nodes in this instance.                                                                                                           |
| [`engine.nodes[*].aragog_port`](#param-engine-nodes-aragog-port)                                                                        | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `5678`              | TCP port for this node's Aragog distributed-execution service.                                                                                   |
| [`engine.nodes[*].host`](#param-engine-nodes-host)                                                                                      | `string`    | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                     | Hostname or IP address of this node, used by other nodes and services to reach it.                                                               |
| [`engine.nodes[*].shufflepuff_port`](#param-engine-nodes-shufflepuff-port)                                                              | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `16000`             | TCP port for this node's Shufflepuff data-shuffle service.                                                                                       |
| [`engine.nodes[*].storage_agent_port`](#param-engine-nodes-storage-agent-port)                                                          | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `3434`              | TCP port for this node's Storage Agent (local tablet I/O).                                                                                       |
| [`engine.nodes[*].storage_manager_port`](#param-engine-nodes-storage-manager-port)                                                      | `integer`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1717`              | TCP port for this node's Storage Manager (tablet lifecycle and metadata).                                                                        |
| [`engine.termination_grace_period`](#param-engine-termination-grace-period)                                                             | `duration`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `1m`                | How long to wait for in-flight queries to finish during graceful shutdown before forcing termination.                                            |

### execution

| Path                                                                                                                                                                                    | Type      | Required                                                             | Default Value | Description                                                                                                                                                  |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------------------------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`execution`](#param-execution)                                                                                                                                                         | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.                               |
| [`execution.admission_controller`](#param-execution-admission-controller)                                                                                                               | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Admission control settings that govern how many queries run concurrently and how memory is shared, to avoid out-of-memory conditions and improve throughput. |
| [`execution.admission_controller.enabled`](#param-execution-admission-controller-enabled)                                                                                               | `boolean` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `false`       | Enable admission control.                                                                                                                                    |
| [`execution.admission_controller.max_concurrent_admitted_queries`](#param-execution-admission-controller-max-concurrent-admitted-queries)                                               | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `100`         | Maximum number of concurrently admitted queries; the per-node limit scales with cluster size.                                                                |
| [`execution.admission_controller.max_required_relative_memory_for_retry`](#param-execution-admission-controller-max-required-relative-memory-for-retry)                                 | `float`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0.75`        | Cap on the extra memory an out-of-memory retry may request, as a fraction of available memory.                                                               |
| [`execution.admission_controller.max_retries_per_query`](#param-execution-admission-controller-max-retries-per-query)                                                                   | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `3`           | Maximum number of automatic retries when a query fails with an out-of-memory error.                                                                          |
| [`execution.admission_controller.reduce_required_memory_after_seconds_at_front_of_queue`](#param-execution-admission-controller-reduce-required-memory-after-seconds-at-front-of-queue) | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `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.   |
| [`execution.admission_controller.seconds_between_no_admission_warnings`](#param-execution-admission-controller-seconds-between-no-admission-warnings)                                   | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `3600`        | Minimum interval, in seconds, between warnings logged when no query can be admitted.                                                                         |
| [`execution.admission_controller.seconds_until_no_admission_warning`](#param-execution-admission-controller-seconds-until-no-admission-warning)                                         | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `300`         | Log a warning when no query has been admitted for this many seconds.                                                                                         |
| [`execution.admission_controller.total_memory_tracker_hard_limit_ratio`](#param-execution-admission-controller-total-memory-tracker-hard-limit-ratio)                                   | `float`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0.9`         | Fraction of the memory tracker's hard limit that admission control may allocate per node.                                                                    |
| [`execution.ai_mutations_mode`](#param-execution-ai-mutations-mode)                                                                                                                     | `enum`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `reevaluate`  | Execution mode for AI mutation queries: `native_only`, `reevaluate` (default), or `hybrid`.                                                                  |
| [`execution.enable_shufflepuff`](#param-execution-enable-shufflepuff)                                                                                                                   | `boolean` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `true`        | Enable the Shufflepuff shuffle subsystem used for distributed (multi-node) query execution.                                                                  |
| [`execution.hybrid_headers_format_version`](#param-execution-hybrid-headers-format-version)                                                                                             | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `3`           | On-disk format version for Hybrid Headers tablet storage.                                                                                                    |
| [`execution.hybrid_headers_primary_index_compression_level`](#param-execution-hybrid-headers-primary-index-compression-level)                                                           | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `2`           | Compression level for the Hybrid Headers primary index.                                                                                                      |
| [`execution.hybrid_headers_primary_index_compression_method`](#param-execution-hybrid-headers-primary-index-compression-method)                                                         | `enum`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `BROTLI`      | Compression algorithm for the Hybrid Headers primary index: one of `none`, `gzip`, `zlib`, `xz`, `zstd`, `brotli`, `lz4`, or `snappy`.                       |
| [`execution.max_threads`](#param-execution-max-threads)                                                                                                                                 | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0`           | Maximum number of threads used to execute a single query.                                                                                                    |
| [`execution.merge_committed_tablets`](#param-execution-merge-committed-tablets)                                                                                                         | `boolean` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `true`        | Allow background merging of committed tablets during maintenance.                                                                                            |
| [`execution.min_bytes_for_wide_part`](#param-execution-min-bytes-for-wide-part)                                                                                                         | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `104857600`   | Minimum uncompressed size, in bytes, for a tablet to use the wide format instead of the compact format.                                                      |
| [`execution.regexp_cache_max_keys`](#param-execution-regexp-cache-max-keys)                                                                                                             | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `10000`       | Maximum number of compiled regular expressions to cache.                                                                                                     |
| [`execution.storage_manager_cache_tablets_on_proxy`](#param-execution-storage-manager-cache-tablets-on-proxy)                                                                           | `boolean` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `true`        | Cache tablet-assignment information on the storage-manager proxy to reduce metadata lookups.                                                                 |

### instance

| Path                                                                                        | Type     | Required                                                             | Default Value                | Description                                                                                                                       |
| :------------------------------------------------------------------------------------------ | :------- | :------------------------------------------------------------------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| [`instance`](#param-instance)                                                               | `object` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`                         | Instance identity and deployment topology — the instance ID and whether this is a single-engine or multi-engine deployment.       |
| [`instance.id`](#param-instance-id)                                                         | `ulid`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `01KP98J0000000000000000000` | Unique instance identifier in ULID format.                                                                                        |
| [`instance.multi_engine`](#param-instance-multi-engine)                                     | `object` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`                       | Multi-engine settings.                                                                                                            |
| [`instance.multi_engine.metadata_endpoint`](#param-instance-multi-engine-metadata-endpoint) | `string` | <Badge color="red" size="sm" className="font-mono">required</Badge>  |                              | Address (`host:port`) of the external Pensieve metadata service.                                                                  |
| [`instance.type`](#param-instance-type)                                                     | `enum`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `single_engine`              | Deployment topology: `single_engine` (metadata runs locally) or `multi_engine` (metadata served by an external Pensieve service). |

### logging

| Path                                                             | Type       | Required                                                             | Default Value | Description                                                                                          |
| :--------------------------------------------------------------- | :--------- | :------------------------------------------------------------------- | :------------ | :--------------------------------------------------------------------------------------------------- |
| [`logging`](#param-logging)                                      | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Logging configuration — the default level, output format, per-component overrides, and output sinks. |
| [`logging.components`](#param-logging-components)                | `object[]` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `[]`          | Per-component log-level overrides.                                                                   |
| [`logging.components[*].level`](#param-logging-components-level) | `enum`     | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | Log level for this component, overriding `logging.level`.                                            |
| [`logging.components[*].name`](#param-logging-components-name)   | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | Name of the logger component this override applies to.                                               |
| [`logging.format`](#param-logging-format)                        | `enum`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `json`        | Log output format: `text` (human-readable) or `json` (structured).                                   |
| [`logging.level`](#param-logging-level)                          | `enum`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `info`        | Default log level for all messages: one of `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.    |
| [`logging.sinks`](#param-logging-sinks)                          | `object[]` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Log output targets.                                                                                  |
| [`logging.sinks[*].file`](#param-logging-sinks-file)             | `object`   | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | File-sink settings.                                                                                  |
| [`logging.sinks[*].file.path`](#param-logging-sinks-file-path)   | `string`   | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | Filesystem path the file sink writes to.                                                             |
| [`logging.sinks[*].level`](#param-logging-sinks-level)           | `enum`     | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Log level for this sink.                                                                             |
| [`logging.sinks[*].type`](#param-logging-sinks-type)             | `enum`     | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | Sink destination: `stderr` or `file`.                                                                |

### planner

| Path                                                                                                                          | Type      | Required                                                             | Default Value | Description                                                               |
| :---------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------------------------------------------------------------- | :------------ | :------------------------------------------------------------------------ |
| [`planner`](#param-planner)                                                                                                   | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Query planner configuration.                                              |
| [`planner.automated_column_statistics`](#param-planner-automated-column-statistics)                                           | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Settings for the automated column-statistics cache used by the optimizer. |
| [`planner.automated_column_statistics.cache_max_size_bytes`](#param-planner-automated-column-statistics-cache-max-size-bytes) | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `104857600`   | Maximum size, in bytes, of the automated column-statistics cache.         |

### schema\_version

| Path                                      | Type     | Required                                                            | Default Value | Description                          |
| :---------------------------------------- | :------- | :------------------------------------------------------------------ | :------------ | :----------------------------------- |
| [`schema_version`](#param-schema-version) | `string` | <Badge color="red" size="sm" className="font-mono">required</Badge> |               | Version of the configuration schema. |

### storage

| Path                                                                                                                      | Type      | Required                                                             | Default Value | Description                                                                                                             |
| :------------------------------------------------------------------------------------------------------------------------ | :-------- | :------------------------------------------------------------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------- |
| [`storage`](#param-storage)                                                                                               | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `{}`          | Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior. |
| [`storage.allow_collect_garbage`](#param-storage-allow-collect-garbage)                                                   | `boolean` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `false`       | Allow manual garbage collection of orphaned tablets via `CALL collect_garbage()`.                                       |
| [`storage.api_scheme`](#param-storage-api-scheme)                                                                         | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Storage URI scheme (for example, `s3://`, `gs://`, or `azure://`).                                                      |
| [`storage.aws`](#param-storage-aws)                                                                                       | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | AWS settings for S3-backed managed tables.                                                                              |
| [`storage.aws.intermediary_access_role`](#param-storage-aws-intermediary-access-role)                                     | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | AWS IAM role assumed for federated, cross-account or cross-tenant S3 access.                                            |
| [`storage.azure`](#param-storage-azure)                                                                                   | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Azure settings for Blob-Storage-backed managed tables.                                                                  |
| [`storage.azure.intermediary_service_principal_client_id`](#param-storage-azure-intermediary-service-principal-client-id) | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Client ID of a federated Azure service principal for cross-tenant access.                                               |
| [`storage.azure.storage_account_name`](#param-storage-azure-storage-account-name)                                         | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Azure Blob Storage account name for managed tables, accessed via workload identity.                                     |
| [`storage.bucket_name`](#param-storage-bucket-name)                                                                       | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Bucket used for managed-table objects.                                                                                  |
| [`storage.collect_garbage_limit_per_query`](#param-storage-collect-garbage-limit-per-query)                               | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `0`           | Maximum tablets cleaned per `collect_garbage()` call.                                                                   |
| [`storage.default_s3_endpoint_override`](#param-storage-default-s3-endpoint-override)                                     | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.                  |
| [`storage.enable_managed_location`](#param-storage-enable-managed-location)                                               | `boolean` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `false`       | Allow `CREATE TABLE` to specify a `LOCATION` for managed tables.                                                        |
| [`storage.gc_ttl_seconds`](#param-storage-gc-ttl-seconds)                                                                 | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `604800`      | Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage.     |
| [`storage.gcp`](#param-storage-gcp)                                                                                       | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Google Cloud settings for GCS-backed managed tables.                                                                    |
| [`storage.gcp.intermediary_service_account_id`](#param-storage-gcp-intermediary-service-account-id)                       | `string`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | GCP service account used for federated, cross-project or cross-tenant GCS access.                                       |
| [`storage.minio`](#param-storage-minio)                                                                                   | `object`  | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | MinIO settings for local or self-hosted S3-compatible storage.                                                          |
| [`storage.minio.endpoint`](#param-storage-minio-endpoint)                                                                 | `string`  | <Badge color="red" size="sm" className="font-mono">required</Badge>  |               | MinIO server endpoint URL (for example, `http://localhost:9000`).                                                       |
| [`storage.type`](#param-storage-type)                                                                                     | `enum`    | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `s3`          | Object-storage provider for managed tables: `s3`, `gcs`, `abs`, `azurite`, or `minio`.                                  |
| [`storage.upload_max_tries`](#param-storage-upload-max-tries)                                                             | `integer` | <Badge color="blue" size="sm" className="font-mono">optional</Badge> | `null`        | Maximum number of retries for object-storage uploads.                                                                   |

## Details

### auth

<ParamField path="auth" type="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.
</ParamField>

<ParamField path="auth.instance_id" type="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`.
</ParamField>

<ParamField path="auth.mode" type="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.
</ParamField>

<ParamField path="auth.native" type="object" default="null">
  Settings for native authentication, used when `auth.mode` is `native`. In this mode PackDB issues and validates its own JWTs.
</ParamField>

<ParamField path="auth.native.initial_user" type="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.
</ParamField>

<ParamField path="auth.native.initial_user.name" type="string" required>
  Username for the bootstrap user created at startup in native authentication mode.
</ParamField>

<ParamField path="auth.native.initial_user.password" type="string" required>
  Password for the bootstrap user created at startup in native authentication mode.
</ParamField>

<ParamField path="auth.native.jwt" type="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.
</ParamField>

<ParamField path="auth.native.jwt.clock_skew_tolerance" type="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`.
</ParamField>

<ParamField path="auth.native.jwt.max_token_age" type="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`.
</ParamField>

<ParamField path="auth.native.jwt.token_expiry" type="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`.
</ParamField>

<ParamField path="auth.native.signing_algorithm" type="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`.
</ParamField>

<ParamField path="auth.native.signing_keys" type="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.
</ParamField>

<ParamField path="auth.native.signing_keys[*].id" type="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.
</ParamField>

<ParamField path="auth.native.signing_keys[*].private_key_path" type="string" required>
  Filesystem path to the PEM-encoded private key used for signing.
</ParamField>

<ParamField path="auth.oidc" type="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.
</ParamField>

<ParamField path="auth.oidc.jwt" type="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.
</ParamField>

<ParamField path="auth.oidc.jwt.clock_skew_tolerance" type="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`.
</ParamField>

<ParamField path="auth.oidc.jwt.max_token_age" type="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`.
</ParamField>

<ParamField path="auth.oidc.postgres_password_fallback_enabled" type="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.
</ParamField>

<ParamField path="auth.oidc.providers" type="object[]" default="[]">
  Trusted OIDC identity providers. A single provider is supported at launch; the list form leaves room for multiple providers in the future.
</ParamField>

<ParamField path="auth.oidc.providers[*].discovery" type="object" default="{}">
  Controls how PackDB refreshes the provider's discovery document.
</ParamField>

<ParamField path="auth.oidc.providers[*].discovery.refresh_interval" type="duration" default="1d">
  How often PackDB re-fetches the provider's OpenID configuration (discovery) document. Defaults to `1d`.
</ParamField>

<ParamField path="auth.oidc.providers[*].discovery_url" type="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.
</ParamField>

<ParamField path="auth.oidc.providers[*].jit_provisioning" type="object" default="{}">
  Just-in-time (JIT) provisioning settings. When enabled, PackDB creates a user automatically the first time someone authenticates through this provider.
</ParamField>

<ParamField path="auth.oidc.providers[*].jit_provisioning.default_role" type="string" default="public">
  Role granted to users created through just-in-time provisioning. Defaults to `public`.
</ParamField>

<ParamField path="auth.oidc.providers[*].jit_provisioning.enabled" type="boolean" default="false">
  Whether to create users automatically on first login through this provider. Disabled by default.
</ParamField>

<ParamField path="auth.oidc.providers[*].jwks" type="object" default="{}">
  Controls how PackDB caches the provider's JSON Web Key Set (JWKS), which it uses to verify token signatures.
</ParamField>

<ParamField path="auth.oidc.providers[*].jwks.cache_ttl" type="duration" default="1h">
  How long PackDB caches the provider's JWKS document before re-fetching it. Defaults to `1h`.
</ParamField>

<ParamField path="auth.oidc.providers[*].name" type="string" required>
  Name or alias for this provider. PackDB uses it to identify the provider in logs and configuration.
</ParamField>

<ParamField path="auth.oidc.providers[*].username_mapping" type="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.
</ParamField>

### endpoints

<ParamField path="endpoints" type="object" default="{}">
  Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol.
</ParamField>

<ParamField path="endpoints.http" type="object" default="{}">
  HTTP listener configuration for the query API.
</ParamField>

<ParamField path="endpoints.http.listeners" type="object[]" default="[]">
  List of HTTP listener bindings. You can define a TCP listener and a Unix-socket listener, each at most once.
</ParamField>

<ParamField path="endpoints.http.listeners[*].path" type="string" default="null">
  Filesystem path for a Unix-domain-socket HTTP listener. Required for `unix` listeners; omit it for `tcp` listeners.
</ParamField>

<ParamField path="endpoints.http.listeners[*].port" type="integer" default="null">
  TCP port for an HTTP listener (for example, `8123`). Required for `tcp` listeners; omit it for `unix` listeners.
</ParamField>

<ParamField path="endpoints.http.listeners[*].type" type="enum" required>
  Listener transport: `tcp` (network socket) or `unix` (Unix-domain socket).
</ParamField>

<ParamField path="endpoints.postgres" type="object" default="{}">
  PostgreSQL wire-protocol listener configuration. Clients connect using standard Postgres drivers and `psql`.
</ParamField>

<ParamField path="endpoints.postgres.listeners" type="object[]" default="[]">
  List of PostgreSQL listener bindings. TCP only — Unix sockets aren't supported for the Postgres protocol.
</ParamField>

<ParamField path="endpoints.postgres.listeners[*].path" type="string" default="null">
  Not used for PostgreSQL listeners; Unix-domain sockets aren't supported for the Postgres protocol.
</ParamField>

<ParamField path="endpoints.postgres.listeners[*].port" type="integer" default="null">
  TCP port for PostgreSQL connections (for example, `5432`). Required for every Postgres listener.
</ParamField>

<ParamField path="endpoints.postgres.listeners[*].type" type="enum" required>
  Listener transport for PostgreSQL. Only `tcp` is supported.
</ParamField>

### engine

<ParamField path="engine" type="object" default="{}">
  Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting.
</ParamField>

<ParamField path="engine.auto_vacuum" type="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.
</ParamField>

<ParamField path="engine.auto_vacuum.assessment_frequency" type="integer" default="null">
  How frequently the engine assesses tablets to decide whether an auto-vacuum job is needed.
</ParamField>

<ParamField path="engine.auto_vacuum.debug_sleep_before_commit_ms" type="integer" default="null">
  Debugging knob: artificial delay, in milliseconds, inserted before an auto-vacuum job commits. Intended for testing only.
</ParamField>

<ParamField path="engine.auto_vacuum.enabled" type="boolean" default="null">
  Whether background auto-vacuum runs. Disabled by default.
</ParamField>

<ParamField path="engine.auto_vacuum.max_concurrency" type="integer" default="null">
  Maximum number of auto-vacuum jobs allowed to run concurrently.
</ParamField>

<ParamField path="engine.auto_vacuum.max_tablets_in_job" type="integer" default="null">
  Maximum number of tablets processed in a single auto-vacuum job.
</ParamField>

<ParamField path="engine.auto_vacuum.memory_allowance" type="float" default="null">
  Fraction of engine memory that auto-vacuum may use while running.
</ParamField>

<ParamField path="engine.auto_vacuum.min_bad_tablets_threshold" type="integer" default="null">
  Minimum number of tablets needing cleanup before an auto-vacuum job is triggered.
</ParamField>

<ParamField path="engine.auto_vacuum.run_on_first_dml" type="boolean" default="null">
  Whether to trigger an auto-vacuum assessment on the first DML statement after startup.
</ParamField>

<ParamField path="engine.cluster_id" type="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.
</ParamField>

<ParamField path="engine.cluster_ordinal" type="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.
</ParamField>

<ParamField path="engine.eviction" type="object" default="{}">
  Tablet memory-eviction policy, controlling when tablets are evicted from in-memory caches to disk as memory fills.
</ParamField>

<ParamField path="engine.eviction.max_tablets_per_mb_of_total_memory" type="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.
</ParamField>

<ParamField path="engine.eviction.tablet_eviction_soft_threshold" type="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.
</ParamField>

<ParamField path="engine.eviction.tablet_eviction_threshold" type="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.
</ParamField>

<ParamField path="engine.eviction.tablet_min_ttl_before_memory_eviction_seconds" type="integer" default="1800">
  Minimum age in seconds a tablet must reach before it becomes eligible for eviction from memory. Defaults to `1800` (30 minutes).
</ParamField>

<ParamField path="engine.eviction.tablet_ttl_before_full_eviction_seconds" type="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).
</ParamField>

<ParamField path="engine.id" type="string" default="default-engine-id">
  Human-readable identifier for this engine, shown in logs, metrics, and system views. Defaults to `default-engine-id`.
</ParamField>

<ParamField path="engine.max_server_memory_usage" type="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`.
</ParamField>

<ParamField path="engine.max_server_memory_usage_headroom_bytes" type="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`.
</ParamField>

<ParamField path="engine.max_server_memory_usage_to_ram_ratio" type="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.
</ParamField>

<ParamField path="engine.metrics_collection_frequency_per_minute" type="integer" default="12">
  How many times per minute the engine collects and emits metrics. Default `12` (every five seconds).
</ParamField>

<ParamField path="engine.multi_cluster" type="object" default="null">
  Multi-cluster broadcast configuration for query execution across engine clusters. Omit this block for a standalone or single-cluster engine.
</ParamField>

<ParamField path="engine.multi_cluster.broadcast_endpoint" type="string" required>
  Address (`host:port`) of the multi-cluster broadcast service. Required and non-empty when multi-cluster broadcasting is enabled.
</ParamField>

<ParamField path="engine.multi_cluster.broadcast_ssl_enabled" type="boolean" default="false">
  Whether to use TLS when connecting to the broadcast endpoint. Default `false`.
</ParamField>

<ParamField path="engine.multi_cluster.broadcast_tuple_limit_per_engine_cluster" type="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.
</ParamField>

<ParamField path="engine.nodes" type="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.
</ParamField>

<ParamField path="engine.nodes[*].aragog_port" type="integer" default="5678">
  TCP port for this node's Aragog distributed-execution service. Default `5678`.
</ParamField>

<ParamField path="engine.nodes[*].host" type="string" required>
  Hostname or IP address of this node, used by other nodes and services to reach it.
</ParamField>

<ParamField path="engine.nodes[*].shufflepuff_port" type="integer" default="16000">
  TCP port for this node's Shufflepuff data-shuffle service. Default `16000`.
</ParamField>

<ParamField path="engine.nodes[*].storage_agent_port" type="integer" default="3434">
  TCP port for this node's Storage Agent (local tablet I/O). Default `3434`.
</ParamField>

<ParamField path="engine.nodes[*].storage_manager_port" type="integer" default="1717">
  TCP port for this node's Storage Manager (tablet lifecycle and metadata). Default `1717`.
</ParamField>

<ParamField path="engine.termination_grace_period" type="duration" default="1m">
  How long to wait for in-flight queries to finish during graceful shutdown before forcing termination. Default `1m`.
</ParamField>

### execution

<ParamField path="execution" type="object" default="{}">
  Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.
</ParamField>

<ParamField path="execution.admission_controller" type="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.
</ParamField>

<ParamField path="execution.admission_controller.enabled" type="boolean" default="false">
  Enable admission control. When enabled, queries are queued and prioritized based on available memory and concurrency limits. Default `false`.
</ParamField>

<ParamField path="execution.admission_controller.max_concurrent_admitted_queries" type="integer" default="100">
  Maximum number of concurrently admitted queries; the per-node limit scales with cluster size. Default `100`.
</ParamField>

<ParamField path="execution.admission_controller.max_required_relative_memory_for_retry" type="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`.
</ParamField>

<ParamField path="execution.admission_controller.max_retries_per_query" type="integer" default="3">
  Maximum number of automatic retries when a query fails with an out-of-memory error. Default `3`.
</ParamField>

<ParamField path="execution.admission_controller.reduce_required_memory_after_seconds_at_front_of_queue" type="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`.
</ParamField>

<ParamField path="execution.admission_controller.seconds_between_no_admission_warnings" type="integer" default="3600">
  Minimum interval, in seconds, between warnings logged when no query can be admitted. Default `3600`.
</ParamField>

<ParamField path="execution.admission_controller.seconds_until_no_admission_warning" type="integer" default="300">
  Log a warning when no query has been admitted for this many seconds. Default `300`.
</ParamField>

<ParamField path="execution.admission_controller.total_memory_tracker_hard_limit_ratio" type="float" default="0.9">
  Fraction of the memory tracker's hard limit that admission control may allocate per node. Default `0.9`.
</ParamField>

<ParamField path="execution.ai_mutations_mode" type="enum" default="reevaluate">
  Execution mode for AI mutation queries: `native_only`, `reevaluate` (default), or `hybrid`.
</ParamField>

<ParamField path="execution.enable_shufflepuff" type="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`.
</ParamField>

<ParamField path="execution.hybrid_headers_format_version" type="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.
</ParamField>

<ParamField path="execution.hybrid_headers_primary_index_compression_level" type="integer" default="2">
  Compression level for the Hybrid Headers primary index. Default `2`; the valid range depends on the chosen method.
</ParamField>

<ParamField path="execution.hybrid_headers_primary_index_compression_method" type="enum" default="BROTLI">
  Compression algorithm for the Hybrid Headers primary index: one of `none`, `gzip`, `zlib`, `xz`, `zstd`, `brotli`, `lz4`, or `snappy`. Default `brotli`.
</ParamField>

<ParamField path="execution.max_threads" type="integer" default="0">
  Maximum number of threads used to execute a single query. `0` (default) lets the engine choose automatically.
</ParamField>

<ParamField path="execution.merge_committed_tablets" type="boolean" default="true">
  Allow background merging of committed tablets during maintenance. Default `true`.
</ParamField>

<ParamField path="execution.min_bytes_for_wide_part" type="integer" default="104857600">
  Minimum uncompressed size, in bytes, for a tablet to use the wide format instead of the compact format.
</ParamField>

<ParamField path="execution.regexp_cache_max_keys" type="integer" default="10000">
  Maximum number of compiled regular expressions to cache. Default `10000`.
</ParamField>

<ParamField path="execution.storage_manager_cache_tablets_on_proxy" type="boolean" default="true">
  Cache tablet-assignment information on the storage-manager proxy to reduce metadata lookups. Default `true`.
</ParamField>

### instance

<ParamField path="instance" type="object" default="{}">
  Instance identity and deployment topology — the instance ID and whether this is a single-engine or multi-engine deployment.
</ParamField>

<ParamField path="instance.id" type="ulid" default="01KP98J0000000000000000000">
  Unique instance identifier in ULID format. Set automatically in cloud-managed deployments; override it for custom Firebolt Core setups.
</ParamField>

<ParamField path="instance.multi_engine" type="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.
</ParamField>

<ParamField path="instance.multi_engine.metadata_endpoint" type="string" required>
  Address (`host:port`) of the external Pensieve metadata service. Required when `instance.type` is `multi_engine`.
</ParamField>

<ParamField path="instance.type" type="enum" default="single_engine">
  Deployment topology: `single_engine` (metadata runs locally) or `multi_engine` (metadata served by an external Pensieve service). Default `single_engine`.
</ParamField>

### logging

<ParamField path="logging" type="object" default="{}">
  Logging configuration — the default level, output format, per-component overrides, and output sinks.
</ParamField>

<ParamField path="logging.components" type="object[]" default="[]">
  Per-component log-level overrides. Each entry sets a level for one logger component, independent of the global default.
</ParamField>

<ParamField path="logging.components[*].level" type="enum" required>
  Log level for this component, overriding `logging.level`. One of `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.
</ParamField>

<ParamField path="logging.components[*].name" type="string" required>
  Name of the logger component this override applies to.
</ParamField>

<ParamField path="logging.format" type="enum" default="json">
  Log output format: `text` (human-readable) or `json` (structured). Default `json`.
</ParamField>

<ParamField path="logging.level" type="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.
</ParamField>

<ParamField path="logging.sinks" type="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.
</ParamField>

<ParamField path="logging.sinks[*].file" type="object" default="null">
  File-sink settings. Required when the sink `type` is `file`; must be absent when the type is `stderr`.
</ParamField>

<ParamField path="logging.sinks[*].file.path" type="string" required>
  Filesystem path the file sink writes to. Required when the sink type is `file`.
</ParamField>

<ParamField path="logging.sinks[*].level" type="enum" default="null">
  Log level for this sink. Inherits `logging.level` when omitted. One of `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.
</ParamField>

<ParamField path="logging.sinks[*].type" type="enum" required>
  Sink destination: `stderr` or `file`. Required for each sink.
</ParamField>

### planner

<ParamField path="planner" type="object" default="{}">
  Query planner configuration.
</ParamField>

<ParamField path="planner.automated_column_statistics" type="object" default="{}">
  Settings for the automated column-statistics cache used by the optimizer.
</ParamField>

<ParamField path="planner.automated_column_statistics.cache_max_size_bytes" type="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.
</ParamField>

### schema\_version

<ParamField path="schema_version" type="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.
</ParamField>

### storage

<ParamField path="storage" type="object" default="{}">
  Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior.
</ParamField>

<ParamField path="storage.allow_collect_garbage" type="boolean" default="false">
  Allow manual garbage collection of orphaned tablets via `CALL collect_garbage()`. Default `false`.
</ParamField>

<ParamField path="storage.api_scheme" type="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.
</ParamField>

<ParamField path="storage.aws" type="object" default="null">
  AWS settings for S3-backed managed tables. Set this block only when `storage.type` is `s3`.
</ParamField>

<ParamField path="storage.aws.intermediary_access_role" type="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.
</ParamField>

<ParamField path="storage.azure" type="object" default="null">
  Azure settings for Blob-Storage-backed managed tables. Set this block only when `storage.type` is `abs` or `azurite`.
</ParamField>

<ParamField path="storage.azure.intermediary_service_principal_client_id" type="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.
</ParamField>

<ParamField path="storage.azure.storage_account_name" type="string" default="null">
  Azure Blob Storage account name for managed tables, accessed via workload identity. Required when `storage.type` is `abs`.
</ParamField>

<ParamField path="storage.bucket_name" type="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.
</ParamField>

<ParamField path="storage.collect_garbage_limit_per_query" type="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.
</ParamField>

<ParamField path="storage.default_s3_endpoint_override" type="string" default="null">
  Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.
</ParamField>

<ParamField path="storage.enable_managed_location" type="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.
</ParamField>

<ParamField path="storage.gc_ttl_seconds" type="integer" default="604800">
  Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage. Default `604800` (7 days).
</ParamField>

<ParamField path="storage.gcp" type="object" default="null">
  Google Cloud settings for GCS-backed managed tables. Set this block only when `storage.type` is `gcs`.
</ParamField>

<ParamField path="storage.gcp.intermediary_service_account_id" type="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.
</ParamField>

<ParamField path="storage.minio" type="object" default="null">
  MinIO settings for local or self-hosted S3-compatible storage. Set this block only when `storage.type` is `minio`.
</ParamField>

<ParamField path="storage.minio.endpoint" type="string" required>
  MinIO server endpoint URL (for example, `http://localhost:9000`). Required when `storage.type` is `minio`.
</ParamField>

<ParamField path="storage.type" type="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`).
</ParamField>

<ParamField path="storage.upload_max_tries" type="integer" default="null">
  Maximum number of retries for object-storage uploads. Leave unset to use the cloud SDK default.
</ParamField>