From e87fdd82046a116e7ec1d6fe84ee191e68ad2410 Mon Sep 17 00:00:00 2001 From: Lev Kokotov Date: Sat, 19 Sep 2026 13:15:23 -0700 Subject: [PATCH 1/4] feat: update general.md --- docs/configuration/pgdog.toml/general.md | 142 +++++++++++++++++++---- 1 file changed, 122 insertions(+), 20 deletions(-) diff --git a/docs/configuration/pgdog.toml/general.md b/docs/configuration/pgdog.toml/general.md index 175f9ba1..6f63c31c 100644 --- a/docs/configuration/pgdog.toml/general.md +++ b/docs/configuration/pgdog.toml/general.md @@ -24,6 +24,15 @@ Default: **`6432`** !!! note "Requires restart" This setting cannot be changed at runtime. +### `listen_backlog` + +Maximum number of pending client connections waiting to be accepted on the TCP socket. Increase this to accommodate many clients reconnecting at once. On Linux, the effective value is capped by `net.core.somaxconn`, so increase that limit as well. + +!!! note "Requires restart" + This setting cannot be changed at runtime. + +Default: **`1_024`** + ### `workers` Number of Tokio threads to spawn at pooler startup. In multi-core systems, the recommended setting is two (2) per @@ -34,12 +43,21 @@ Default: **`2`** !!! note "Requires restart" This setting cannot be changed at runtime. +### `background_workers` + +Maximum number of background threads used to offload blocking or CPU-intensive tasks, like SCRAM authentication. Set to `0` (default) to run this on the runtime workers instead. + +!!! note "Requires restart" + The background thread limit is set at startup. + +Default: **`0`** (offloading disabled) + ### `default_pool_size` Default maximum number of server connections per database pool. The pooler will not open more than this many PostgreSQL database connections when serving clients. !!! note "Recommendation" - We strongly recommend keeping this value well below the supported connections of the backend database(s) to allow connections for maintenance in high load scenarios. + It's recommended to keep this value below the supported connections of the backend database(s) to allow connections for maintenance in high load scenarios. Default: **`10`** @@ -50,7 +68,6 @@ open minimizes cold start time when clients connect to the pooler for the first Default: **`1`** - ### `pooler_mode` Default pooler mode to use for database pools. @@ -61,10 +78,9 @@ Available options: - `transaction` (default) - `statement` - See [transaction mode](../../features/connection-pooler/transaction-mode.md) and [session mode](../../features/connection-pooler/session-mode.md) for more details on each mode. -Default: **`transaction`** +Default: **`transaction`** ## TLS @@ -100,15 +116,28 @@ Default: **`prefer`** Available options are: -* `none` (disable TLS) -* `prefer` (no certificate validation) -* `verify_ca` (validate certificate only) -* `verify_full` (validate certificate _and_ matching hostname) +- `none` (disable TLS) +- `prefer` (no certificate validation) +- `verify_ca` (validate certificate only) +- `verify_full` (validate certificate _and_ matching hostname) ### `tls_server_ca_certificate` Path to a certificate bundle used to validate the server certificate on TLS connection creation. Used in conjunction with `verify_ca` or `verify_full` in [`tls_verify`](#tls_verify). +### `tls_server_certificate` + +Path to the PEM client certificate PgDog presents when connecting to PostgreSQL servers that require mutual TLS (mTLS). Set [`tls_server_private_key`](#tls_server_private_key) as well. + +Individual `[[databases]]` entries can override the certificate and private key. + +Default: **none** (no client certificate presented to PostgreSQL) + +### `tls_server_private_key` + +Path to the PEM private key for [`tls_server_certificate`](#tls_server_certificate). Both this and `tls_server_certificate` settings must be provided together. + +Default: **none** ## Healthchecks @@ -141,6 +170,14 @@ Maximum amount of time to wait for a healthcheck query to complete. Default: **`5_000`** (5s) +### `require_healthcheck_on_discovery` + +Require newly added load balancer targets to pass a healthcheck before they can serve queries. This prevents traffic from reaching a newly discovered server before PgDog has checked its health. + +This setting should be enabled when using the [autodiscovery](../../enterprise_edition/autodiscovery.md) feature. + +Default: **`false`** (disabled) + ### `connection_recovery` Controls if server connections are recovered or dropped if a client abruptly disconnects. @@ -162,7 +199,6 @@ Available options: - `recover` - `drop` (default) - ## Timeouts These settings control how long PgDog waits for maintenance tasks to complete. These timeouts make sure PgDog can recover @@ -279,9 +315,9 @@ Default: **`0`** (no jitter) Which strategy to use for load balancing read queries. See [load balancer](../../features/load-balancer/index.md) for more details. Available options are: -* `random` -* `least_active_connections` -* `round_robin` +- `random` +- `least_active_connections` +- `round_robin` Default: **`random`** @@ -321,9 +357,17 @@ Enable load balancer [HTTP health checks](../../features/load-balancer/healthche Default: **none** (disabled) - ## Monitoring +### `openmetrics_host` + +IP address of the local interface on which the OpenMetrics HTTP endpoint listens. The endpoint is enabled by setting [`openmetrics_port`](#openmetrics_port). + +!!! note "Requires restart" + This setting cannot be changed at runtime. + +Default: **`0.0.0.0`** (all interfaces) + ### `openmetrics_port` The port used for the OpenMetrics HTTP endpoint. @@ -370,12 +414,12 @@ Default: **`disabled`** Controls which prepared statement protocols PgDog rewrites for its global cache. -| Setting | Extended named | Extended anonymous | Simple `PREPARE`/`EXECUTE` | Notes | -|---|---|---|---|---| -| `disabled` | no | no | no | Statements are forwarded as-is with no rewriting. | -| `extended` | yes | no | no | Default. Rewrites named extended-protocol statements (`Parse`/`Bind`/`Execute`). | -| `extended_anonymous` | yes | yes | no | Also rewrites unnamed (anonymous) extended-protocol statements. | -| `full` | yes | no | yes | Superset of `extended`. Also rewrites simple-protocol `PREPARE`/`EXECUTE`. Requires parsing every query; higher CPU cost. | +| Setting | Extended named | Extended anonymous | Simple `PREPARE`/`EXECUTE` | Notes | +| -------------------- | -------------- | ------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `disabled` | no | no | no | Statements are forwarded as-is with no rewriting. | +| `extended` | yes | no | no | Default. Rewrites named extended-protocol statements (`Parse`/`Bind`/`Execute`). | +| `extended_anonymous` | yes | yes | no | Also rewrites unnamed (anonymous) extended-protocol statements. | +| `full` | yes | no | yes | Superset of `extended`. Also rewrites simple-protocol `PREPARE`/`EXECUTE`. Requires parsing every query; higher CPU cost. | Default: **`extended`** @@ -387,6 +431,28 @@ limit will be removed. Default: **`none`** (unlimited) +### `prepared_statements_ttl` + +Maximum time, in milliseconds, a prepared statement may remain prepared on a server connection. + +Expired statements are closed and prepared again when used, allowing PostgreSQL to replace stale execution plans. + +Omit this setting or set it to `0` to disable expiration. + +Expiration times are spread out by [`prepared_statements_ttl_jitter`](#prepared_statements_ttl_jitter). + +Default: **none** (disabled) + +### `prepared_statements_ttl_jitter` + +Maximum random adjustment, in milliseconds, to [`prepared_statements_ttl`](#prepared_statements_ttl). + +Each statement receives an expiration time between `ttl - jitter` and `ttl + jitter` when it is prepared. + +The effective jitter is capped at `ttl - 1` millisecond. Set to `0` to disable jitter. This setting has no effect when statement expiration is disabled. + +Default: **`30_000`** (30 seconds) + ## Pub/sub ### `pub_sub_channel_size` @@ -528,6 +594,20 @@ If turned on, queries touching [omnisharded](../../features/sharding/omnishards. Default: **`false`** +### `sharding_lookup_cache_size` + +Maximum size, in bytes, of the sharding key lookup cache per database cluster. The cache stores results of `lookup_query` configured in `[[sharded_tables]]`. + +When the cache fills, the least recently used entries are evicted. Configuration reloads clear the cache. + +Default: **`67_108_864`** (64 MiB) + +### `sharding_lookup_timeout` + +Maximum time, in milliseconds, a sharding key `lookup_query` may run. If it times out, the statement waiting for that lookup fails. + +Default: **`5_000`** (5 seconds) + ### `resharding_copy_format` Which format to use for `COPY` statements during [resharding](../../features/sharding/resharding/index.md). @@ -586,7 +666,7 @@ Controls whether PgDog loads the database schema at startup for query routing. Available options: - `on`: always load schema on startup -- `off`: disable loading schema +- `off`: disable loading schema - `auto` (default): load schema if number of database shards is greater than 1 Default: **`auto`** @@ -693,6 +773,28 @@ Number of identical log messages allowed within [`log_dedup_window`](#log_dedup_ Default: **`0`** (disabled) +### `query_log_stdout` + +Log client SQL at `INFO` level. Query text is limited by [`log_query_sample_length`](#log_query_sample_length), and control characters are sanitized to keep each entry on one line. + +Default: **`false`** (disabled) + +### `log_min_duration_parse` + +Minimum query parsing duration, in milliseconds, that triggers a `WARN` log with a sample of the query text. + +This measures PgDog SQL parser speed, not PostgreSQL execution time. + +A value of `0` logs every query parser event. + +Default: **none** (disabled) + +### `log_query_sample_length` + +Maximum number of query-text characters included in query log samples, including slow-parse and oversized-query messages. + +Default: **`1_000`** characters + ### `query_size_limit` Maximum size, in bytes, of a query message (`Query` or `Parse`) received from a client. When a message exceeds this size, the action taken depends on [`query_size_limit_action`](#query_size_limit_action). Other protocol messages (e.g. `Bind`, `CopyData`) are not affected. From 98768a719ca260284ac16d9c2e6fef7ee7fab4a9 Mon Sep 17 00:00:00 2001 From: Lev Kokotov Date: Sat, 19 Sep 2026 13:38:32 -0700 Subject: [PATCH 2/4] rewrite --- docs/configuration/pgdog.toml/rewrite.md | 106 +++++++++++++++++------ 1 file changed, 81 insertions(+), 25 deletions(-) diff --git a/docs/configuration/pgdog.toml/rewrite.md b/docs/configuration/pgdog.toml/rewrite.md index 45352c76..f773db58 100644 --- a/docs/configuration/pgdog.toml/rewrite.md +++ b/docs/configuration/pgdog.toml/rewrite.md @@ -4,55 +4,111 @@ icon: material/alpha-r-box-outline # Rewrite engine -The `rewrite` section controls PgDog's automatic SQL rewrites for sharded databases. It affects sharding key updates and multi-tuple inserts. Either one can be toggled separately: +The `[rewrite]` section configures SQL query rewrites performed by PgDog to make sure queries work correctly with sharded databases. + +For example: === "pgdog.toml" + ```toml [rewrite] - enabled = false shard_key = "error" - split_inserts = "error" - primary_key = "ignore" - omni_non_deterministic_functions = "ignore" + split_inserts = "rewrite" + primary_key = "rewrite_omni" + non_deterministic_functions = "rewrite" ``` + === "Helm chart" + ```yaml rewrite: - enabled: false - shardKey: "error" - splitInserts: "error" - primaryKey: "ignore" - omniNonDeterministicFunctions: "ignore" + shardKey: error + splitInserts: rewrite + primaryKey: rewrite_omni + nonDeterministicFunctions: rewrite ``` -| Setting | Description | Default | -| --- | --- | --- | -| `enabled` | Enables/disables the query rewrite engine. | `false` | -| `shard_key` | Behavior when an `UPDATE` changes a sharding key: `error` rejects the statement,
`rewrite` migrates the row between shards,
`ignore` forwards it unchanged. | `"error"` | -| `split_inserts` | Behavior when a sharded table receives a multi-row `INSERT`: `error` rejects the statement, `rewrite` fans the rows out to their shards, `ignore` forwards it unchanged. | `"error"` | -| `primary_key` | Behavior when an `INSERT` is missing a `BIGINT` primary key: `error` rejects the statement,
`rewrite` auto-injects `pgdog.unique_id()` for missing keys,
`ignore` allows the INSERT without modification. | `"ignore"` | -| `omni_non_deterministic_functions` | Behavior when an `INSERT` is headed to an omnisharded table using a function (such as date-time functions) that will not be consistent when performing the functions separately on each shard. Thus, it re-writes all such functions before performing the `INSERT` with constant values to maintain consistency. Example: `NOW()` is re-written to `2026-09-15 18:14:09.123456-05` (or whatever the current time is) before performing the individual `INSERT` operations. This applies to both `DEFAULT` table schema and functions called within a VALUES list of an `INSERT`. `ignore` allows the `INSERT` without modification. | `"ignore"` | +### `shard_key` + +Behavior when an UPDATE statement changes the sharding key, requiring PgDog to move the row between shards. + +| Value | Behavior | +| --------- | ----------------------------------------------------- | +| `error` | Reject the statement. | +| `rewrite` | Move the affected rows between shards. | +| `ignore` | Forward the statement without a sharding key rewrite. | + +Default: **`error`** + +### `split_inserts` + +Behavior for INSERT statements with multiple tuples executed on sharded tables. + +| Value | Behavior | +| --------- | ------------------------------------------------------------------------ | +| `error` | Reject inserts that require splitting across shards. | +| `rewrite` | Split the INSERT and send each group of rows to its corresponding shard. | +| `ignore` | Forward the statement without splitting it. | + +Default: **`error`** !!! note "Two-phase commit" - Consider enabling [two-phase commit](../../features/sharding/2pc/index.md) when either feature is set to `rewrite`. Without it, rewrites are committed shard-by-shard and can leave partial changes if a transaction fails. + + Enable [two-phase commit](../../features/sharding/2pc/index.md) when `shard_key` or `split_inserts` is set to `rewrite`. Without it, changes can commit on some shards while a failure on another shard can leave the operation partially applied. + +### `primary_key` + +Behavior when an INSERT omits a `BIGINT` primary key. The rewrite modes also replace explicit `DEFAULT` values for those columns. + +PgDog uses its [schema cache](../../features/sharding/schema_management/cache.md) to identify primary keys. + +| Value | Behavior | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ignore` | Leave primary key generation to PostgreSQL. | +| `error` | Reject an insert that omits a `BIGINT` primary key column. | +| `rewrite` | Inject `pgdog.unique_id()` for sharded and omnisharded tables. | +| `rewrite_omni` | Inject `pgdog.unique_id()` only for omnisharded tables. Sharded tables rely on database key generation. | +| `rewrite_omni_global` | Inject `pgdog.nextval()` only for omnisharded tables, using a global sequence instead of a generated unique ID. Sharded tables rely on database key generation. | + +!!! note "Enterprise edition" + + `rewrite_omni_global` requires a connection to the [Enterprise Edition control plane](../../enterprise_edition/control_plane/index.md), which provides the global sequence values. + +Default: **`ignore`** + +### `non_deterministic_functions` + +Configuring `non_deterministic_functions` to `rewrite` will add or mutate INSERT statements that use date/time and UUID columns, to ensure the generated values are consistent on all shards. + +The intent is to replicate behavior expected from regular, non-sharded Postgres databases, in a sharded context. + +| Data type / function | Behavior | +| --------------------- | ------------------------------------------------------------------------------------------------ | +| `TIMESTAMP` | Set to transaction time as observed by PgDog, using the connected client's `timezone` parameter. | +| `TIMESTAMPTZ` | Set to transaction time observed by PgDog, in UTC time. | +| `now()` | Same as `TIMESTAMPTZ`. | +| `current_timestamp()` | Same as `now()` except using statement time, not transaction time. | + +Default: **`ignore`** ## Runtime overrides -The admin database exposes these toggles via the `SET` command: +The [admin database](../../administration/index.md) exposes all of these settings through `SET`, e.g.: ```postgresql -SET rewrite_enabled TO true; -- enable/disable rewrite engine -SET rewrite_shard_key_updates TO rewrite; -- error | rewrite | ignore -SET rewrite_split_inserts TO rewrite; -- error | rewrite | ignore -SET rewrite_omni_non_deterministic_functions TO rewrite; -- error | rewrite | ignore +SET rewrite_enabled TO true; +SET rewrite_shard_key_updates TO rewrite; +SET rewrite_split_inserts TO rewrite; +SET rewrite_primary_key TO rewrite_omni; +SET rewrite_omni_non_deterministic_functions TO rewrite; ``` -The setting changes are applied immediately. These overrides allow canary testing before persisting them in `pgdog.toml`. - +Changes take effect immediately and are discarded by configuration reloads. ### Read more {{ next_steps_links([ ("Cross-shard INSERT", "../../features/sharding/cross-shard-queries/insert.md#multiple-tuples", "Insert rows with multiple tuples across shards."), ("Cross-shard UPDATE", "../../features/sharding/cross-shard-queries/update.md#sharding-key-updates", "Update rows that require sharding key changes."), + ("Sharded sequences", "../../features/sharding/sequences.md", "Generate primary keys while keeping omnisharded copies consistent."), ]) }} From 8f636166902351f418f94514a680c88761fa694f Mon Sep 17 00:00:00 2001 From: Lev Kokotov Date: Sat, 19 Sep 2026 13:45:54 -0700 Subject: [PATCH 3/4] databases.md --- docs/configuration/pgdog.toml/databases.md | 124 ++++++++++++++++++++- 1 file changed, 120 insertions(+), 4 deletions(-) diff --git a/docs/configuration/pgdog.toml/databases.md b/docs/configuration/pgdog.toml/databases.md index 30f7ad8b..331a6f8b 100644 --- a/docs/configuration/pgdog.toml/databases.md +++ b/docs/configuration/pgdog.toml/databases.md @@ -1,6 +1,7 @@ --- icon: material/database-settings --- + # Database settings Database settings configure which databases PgDog is managing. This is a TOML list of hosts, ports, and other settings like database roles (primary or replica). @@ -8,6 +9,7 @@ Database settings configure which databases PgDog is managing. This is a TOML li For each database instance, add a `[[databases]]` entry to `pgdog.toml`. For example: === "pgdog.toml" + ```toml [[databases]] name = "prod" @@ -22,7 +24,9 @@ For each database instance, add a `[[databases]]` entry to `pgdog.toml`. For exa role = "replica" shard = 0 ``` + === "Helm chart" + ```yaml databases: - name: prod @@ -43,7 +47,6 @@ the same cluster, use the same value. Default: **none** (required) - ### `host` IP address or DNS name of the machine where the PostgreSQL server is running. For example: @@ -90,15 +93,33 @@ The shard number for this database. Only required if your database contains more Default: **`0`** +### `lb_weight` + +Relative weight used when [`load_balancing_strategy`](general.md#load_balancing_strategy) is `weighted_round_robin`. Higher weights receive a larger share of read traffic among eligible servers. + +For example, weights of `200` and `100` give the first server approximately twice as much traffic as the second. + +Accepts integers from `0` to `255`. This setting has no effect with other load balancing strategies. + +Default: **`255`** + +### `resharding_only` + +Reserve this server for [resharding](../../features/sharding/resharding/index.md) table copying only. They are excluded it from normal read load balancing. + +Default: **`false`** + !!! note "Settings priority" - All settings below take priority over values in [`[general]`](general.md). + + Database pool settings override the corresponding defaults in [`[general]`](general.md). Per-user pool settings in [`users.toml`](../users.toml/users.md) take priority over the corresponding database settings. ### `pool_size` Overrides the [`default_pool_size`](general.md#default_pool_size) setting. All connection pools for this database will open at most this many connections to Postgres. !!! note "Recommendation" - We strongly recommend keeping this value well below the supported connections of the backend database(s) to allow connections for maintenance in high load scenarios. + + It's recommended to keep this value below the supported connections of the backend database(s) to allow connections for maintenance in high load scenarios. ### `pooler_mode` @@ -112,7 +133,6 @@ Overrides the [`min_pool_size`](general.md#min_pool_size) setting. The connectio This setting configures the `statement_timeout` connection parameter on all connections to Postgres for this database. - ### `lock_timeout` Configures the `lock_timeout` connection parameter on all connections to Postgres for this database. Aborts any statement that waits longer than the specified duration to acquire a lock. Unlike `statement_timeout`, this only counts time spent waiting for locks, not total execution time. @@ -130,3 +150,99 @@ Sets the `default_transaction_read_only` connection parameter to `on` on all ser ### `server_lifetime` Overrides the [`server_lifetime`](general.md#server_lifetime) setting. Server connections older than this will be closed when returned to the pool. + +### `server_lifetime_jitter` + +Overrides [`server_lifetime_jitter`](general.md#server_lifetime_jitter) for this database, in milliseconds. + +Default: **none** + +## Pool settings by role + +These settings apply according to the server's current role, e.g., `primary` or `replica`. + +They are useful with `role = "auto"`, since the applicable limits change when PgDog detects a role change. + +### `pool_size_primary` + +Maximum number of connections per pool when this server is a primary. Overrides the ordinary [`pool_size`](#pool_size) limit for that role. + +Default: **none** + +### `pool_size_replica` + +Maximum number of connections per pool when this server is a replica. Overrides the ordinary [`pool_size`](#pool_size) limit for that role. + +Default: **none** + +### `min_pool_size_primary` + +Minimum number of connections to keep open per pool when this server is a primary. Overrides the ordinary [`min_pool_size`](#min_pool_size) for that role. + +Default: **none** + +### `min_pool_size_replica` + +Minimum number of connections to keep open per pool when this server is a replica. Overrides the ordinary [`min_pool_size`](#min_pool_size) for that role. + +Default: **none** + +### `idle_timeout_primary` + +Idle connection timeout, in milliseconds, when this server is a primary. Overrides the ordinary [`idle_timeout`](#idle_timeout) for that role. + +Default: **none** + +### `idle_timeout_replica` + +Idle connection timeout, in milliseconds, when this server is a replica. Overrides the ordinary [`idle_timeout`](#idle_timeout) for that role. + +Default: **none** + +For example: + +```toml +[[databases]] +name = "prod" +host = "10.0.0.1" +role = "auto" +pool_size_primary = 20 +pool_size_replica = 10 +min_pool_size_primary = 2 +min_pool_size_replica = 1 +idle_timeout_primary = 60_000 +idle_timeout_replica = 30_000 +``` + +## TLS + +These settings control TLS connections from PgDog to this PostgreSQL server. Add them directly to the `[[databases]]` entry. Unset settings inherit the corresponding values from `[general]`. + +### `tls_verify` + +Overrides [`tls_verify`](general.md#tls_verify) for this server. Available options are: + +- `disabled`: disable TLS. +- `prefer`: use TLS if available, without verifying the server certificate. +- `verify_ca`: validate the server certificate against a CA bundle. +- `verify_full`: validate the server certificate and its hostname. + +Default: **none** + +### `tls_server_ca_certificate` + +Path to the CA certificate bundle used to validate this server's certificate. Overrides [`tls_server_ca_certificate`](general.md#tls_server_ca_certificate); use with `verify_ca` or `verify_full`. + +Default: **none** + +### `tls_server_certificate` + +Path to the PEM client certificate PgDog presents to this server for mutual TLS (mTLS). Set [`tls_server_private_key`](#tls_server_private_key) in the same database entry. Together, these replace the certificate and key configured in `[general]`. + +Default: **none** + +### `tls_server_private_key` + +Path to the PEM private key for [`tls_server_certificate`](#tls_server_certificate). Both settings must be provided together on the database. + +Default: **none** From c6c346415955de9ffa4c2d3fcf80a7a9d4befe6d Mon Sep 17 00:00:00 2001 From: Lev Kokotov Date: Sat, 19 Sep 2026 13:54:22 -0700 Subject: [PATCH 4/4] sharded tables --- .../pgdog.toml/sharded_tables.md | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/configuration/pgdog.toml/sharded_tables.md b/docs/configuration/pgdog.toml/sharded_tables.md index 28d96874..2dcf8906 100644 --- a/docs/configuration/pgdog.toml/sharded_tables.md +++ b/docs/configuration/pgdog.toml/sharded_tables.md @@ -158,28 +158,33 @@ By default, PgDog uses hash-based sharding, with data evenly split between shard To configure either one, add a `mapping` to the table's `[[sharded_tables]]` entry. Each rule assigns an explicit set of values (list), a bounded range (range), or everything else (default) to a shard. PgDog infers the rule type from the fields you set. -A mapping is a list of rules attached to a `[[sharded_tables]]` entry. TOML gives you two equivalent ways to write that list: +A mapping is a list of rules attached to a `[[sharded_tables]]` entry. TOML gives you two equivalent ways to write that list. Both forms produce exactly the same configuration, so use whichever is easier to read. -- One `[[sharded_tables.mapping]]` block per rule. The double square brackets are TOML's syntax for an array, so repeating the block simply appends another rule (this is the style used in the examples below). Each block attaches to the most recently defined `[[sharded_tables]]`, so place a table's mapping blocks directly after its entry and before the next `[[sharded_tables]]`. -- A single inline array, e.g. `mapping = [ { values = [1, 2], shard = 0 }, { shard = 1 } ]`, where each `{ ... }` is one rule. +### Mapping blocks -Both forms produce exactly the same configuration, so use whichever is easier to read. +Use one `[[sharded_tables.mapping]]` block per rule. The double square brackets are TOML's syntax for an array, so repeating the block simply appends another rule (this is the style used in the examples below). Each block attaches to the most recently defined `[[sharded_tables]]`, so place a table's mapping blocks directly after its entry and before the next `[[sharded_tables]]`. + +### Inline array + +Use a single inline array, e.g. `mapping = [ { values = [1, 2], shard = 0 }, { shard = 1 } ]`, where each `{ ... }` is one rule. + +### Rule fields Each rule has a target `shard` plus the fields that define which values it matches: -### `values` +#### `values` A set of values that route to this shard. Setting `values` makes the rule a **list** rule (`PARTITION BY LIST`). -### `start` +#### `start` The starting value of a range, inclusive. Setting `start` and/or `end` makes the rule a **range** rule (`PARTITION BY RANGE`). Omit `start` for a range that is unbounded below. -### `end` +#### `end` The ending value of a range, exclusive. Omit `end` for a range that is unbounded above. -### `shard` +#### `shard` The target shard number for matched values. A rule with only `shard` set (no `values`, `start`, or `end`) is the **default** rule: a catch-all for any value not matched by a list or range rule.