vadv · May 12, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/.github/workflows/bdd-tests.yml b/.github/workflows/bdd-tests.yml
@@ -222,6 +222,12 @@ jobs:
       packages: read
     strategy:
       fail-fast: false
+      # GitHub-hosted runners share CPU under heavy matrix fan-out, and
+      # the timing-sensitive scenarios (sleep-based retain/lifetime
+      # waits, SCRAM passthrough reconnect) lose their margin when 20+
+      # BDD jobs run in parallel. Cap concurrency so each suite gets a
+      # less contested runner.
+      max-parallel: 4
       matrix:
         suite:
           - { name: "Go",                                cargo: "test --test bdd -- --tags @go" }
@@ -245,6 +251,7 @@ jobs:
           - { name: "Patroni-assisted fallback",         cargo: "test --test bdd -- --tags @patroni_fallback" }
           - { name: "Server TLS",                        cargo: "test --test bdd -- --tags @server-tls" }
           - { name: "TLS migration (vendored OpenSSL)",  cargo: "test --features tls-migration --test bdd -- --tags @tls-migration" }
+          - { name: "Startup parameters",                cargo: "test --test bdd -- --tags @startup-parameters" }
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

diff --git a/.gitignore b/.gitignore
@@ -57,6 +57,9 @@ flamegraph-output/
 # Superpowers brainstorm session workdir (VC mockups, server state)
 .superpowers/
 
+# Superpowers spec drafts (private session artifacts)
+/docs/superpowers/
+
 # Per-session agent handoff scratchpads — not part of public history.
 .local/
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "pg_doorman"
-version = "3.8.5"
+version = "3.9.0"
 edition = "2021"
 rust-version = "1.87.0"
 license = "MIT"

diff --git a/documentation/en/src/SUMMARY.md b/documentation/en/src/SUMMARY.md
@@ -30,6 +30,7 @@
 - [Pool Modes](concepts/pool-modes.md)
 - [Pool Coordinator](concepts/pool-coordinator.md)
 - [Anonymous Parse Caching](tutorials/prepared-statements.md)
+- [PostgreSQL startup parameters](tutorials/startup-parameters.md)
 - [Pool Pressure (advanced)](tutorials/pool-pressure.md)
 
 # High Availability

diff --git a/documentation/en/src/authentication/auth-query.md b/documentation/en/src/authentication/auth-query.md
@@ -28,7 +28,11 @@ pools:
       cache_failure_ttl: "30s"
 ```
 
-The query must return a column named `passwd` or `password` containing the MD5 or SCRAM hash. Extra columns are ignored.
+The query must return a column named `passwd` or `password` containing
+the MD5 or SCRAM hash. Extra columns are ignored except for
+`startup_parameters`. In passthrough mode, pg_doorman reads that column
+as a `text` JSON object with per-user PostgreSQL startup parameters.
+Dedicated mode ignores the column and logs a warning.
 
 `user` and `password` are the credentials PgDoorman uses to run the lookup query. They must have permission to read the credential column. Either grant access to a custom view (recommended) or use a user in `pg_read_server_files` group.
 

diff --git a/documentation/en/src/changelog.md b/documentation/en/src/changelog.md
@@ -1,5 +1,85 @@
 # Changelog
 
+### 3.9.0
+
+Per-pool PostgreSQL startup parameters. pg_doorman can now add
+operator-defined GUCs to each backend `StartupMessage`. Values merge in
+three layers: `general.startup_parameters`, `pools.<name>.startup_parameters`,
+and the optional `startup_parameters` column returned by passthrough
+`auth_query`.
+
+PostgreSQL stores these values as the session reset defaults, so
+client-side `RESET ALL` and `DISCARD ALL` return to the operator value.
+This gives one pool a different `plan_cache_mode`, `statement_timeout`,
+`work_mem`, or `idle_in_transaction_session_timeout` without changing
+`postgresql.conf`, `ALTER ROLE`, or `ALTER DATABASE`.
+
+#### Cascade resolution
+
+- `general.startup_parameters`, `pools.<name>.startup_parameters`, and
+  the optional `startup_parameters` text column on an `auth_query` row
+  merge per key. The later layer wins.
+- Dedicated `auth_query` mode uses a shared `server_user`, so
+  pg_doorman ignores the per-user column there and logs one warning per
+  pool and username.
+- A reload that changes startup parameters recycles the affected pools.
+  Idle backends with the old reset defaults are not reused.
+
+#### Validation and protocol safety
+
+- Reserved protocol keys (`user`, `database`, `replication`,
+  `options`, the `_pq_.*` extension prefix) are refused at config load.
+- Keys must match the PG GUC naming shape `[A-Za-z_][A-Za-z0-9_.]*`,
+  values must not contain null bytes, and each level fits the operator
+  budget of `MAX_STARTUP_PACKET_LENGTH - 512` bytes.
+- The full cascade is checked before each backend startup against PG's 10 000-byte
+  `MAX_STARTUP_PACKET_LENGTH`; if the union would overflow, all
+  operator-supplied keys are dropped for that spawn and the event is
+  logged. That backend starts with PostgreSQL defaults for those keys.
+
+#### Behaviour on PG-side rejection
+
+- If PostgreSQL rejects an operator-supplied startup parameter at
+  backend startup, pg_doorman forwards the `ErrorResponse` to the
+  client unchanged. There is no retry with the key removed and no
+  per-key quarantine. Fix the parameter in the config; until then,
+  backend startup for that pool fails with PostgreSQL's own SQLSTATE and
+  message.
+- SQLSTATE class `57P` (server unavailable) keeps mapping to
+  `ServerUnavailableError` first so the Patroni-assisted fallback
+  path can route around the failed node before the startup-parameter
+  log line fires.
+- The operator-supplied parameter wins over the client sync path:
+  even if the client connect string carries an `application_name`
+  (or another tracked GUC like `TimeZone`), the per-checkout
+  `sync_parameters` call no longer overrides the operator value on
+  the backend. The operator-configured default stands until an
+  explicit `SET` statement on the client session changes it.
+
+#### RELOAD coherence
+
+- A SIGHUP that changes `general.startup_parameters` drains pools that
+  inherit that baseline. The per-pool config hash includes the general
+  startup map, and carried-over dynamic `auth_query` pools are recycled
+  when the baseline changes.
+
+#### Observability
+
+- `pg_doorman_backend_startup_parameter_errors_total{pool, sqlstate}`
+  counts every backend startup rejected by PostgreSQL because of an
+  operator-supplied parameter. The failing parameter name and
+  username are written to the warning log line, not to metric labels.
+- `SHOW STARTUP_PARAMETERS` (admin SQL console) lists the per-pool
+  effective cascade with the layer that supplied each value. `psql` tab
+  completion on `SHOW <TAB>` now includes the command.
+- The Web UI pool detail page shows the same data in a
+  "Startup parameters (operator-injected)" section, driven by the
+  new `startup_parameters[]` field on `/api/pools`.
+
+See [PostgreSQL startup parameters](tutorials/startup-parameters.md)
+for the operator walkthrough, plus [General Settings](reference/general.md)
+and [Pool Settings](reference/pool.md) for the full parameter list.
+
 ### 3.8.5
 
 The web console now accepts JWTs issued by an external SSO proxy

diff --git a/documentation/en/src/comparison.md b/documentation/en/src/comparison.md
@@ -77,6 +77,7 @@ See [Patroni-assisted fallback](tutorials/patroni-assisted-fallback.md), [`patro
 | LISTEN / NOTIFY pinning in transaction mode | No | No | Experimental |
 | Cross-rule connection cap (`shared_pool`) | No | No | Yes (since 1.5.1) |
 | `PAUSE` / `RESUME` / `RECONNECT` admin commands | Yes | Yes | Yes (since 1.4.1) |
+| Operator-defined PostgreSQL GUCs in backend `StartupMessage` per pool | Yes (`startup_parameters`, three-level cascade `general` → pool → `auth_query` passthrough; values survive client `RESET ALL` / `DISCARD ALL`; PG startup errors are forwarded unchanged) | No equivalent operator-defined cascade; selected client startup parameters can be tracked or ignored | No (`maintain_params` preserves client-side parameters across rebind; no operator-defined GUCs) |
 
 See [Pool Coordinator](concepts/pool-coordinator.md), [Pool pressure](tutorials/pool-pressure.md).
 

diff --git a/documentation/en/src/observability/admin-commands.md b/documentation/en/src/observability/admin-commands.md
@@ -34,6 +34,7 @@ Admin commands are read with `SHOW <subcommand>` or executed with bare verbs (`P
 | `SHOW LISTS` | Counts by category (databases, users, pools, clients, servers). |
 | `SHOW USERS` | List of users and their pool modes. |
 | `SHOW AUTH_QUERY` | `auth_query` cache hit/miss/refetch rates, auth success/failure, executor errors, dynamic pool counts. |
+| `SHOW STARTUP_PARAMETERS` | Effective `startup_parameters` cascade per pool: parameter, value, and contributing layer. |
 | `SHOW SOCKETS` | TCP and Unix socket counts by state (Linux only — reads `/proc/net/`). |
 | `SHOW LOG_LEVEL` | Current log level. |
 | `SHOW VERSION` | PgDoorman version. |
@@ -68,6 +69,19 @@ mydb     | app  | 12      | 4         | 0          | 4         | 36      | 0
 - `sv_idle` matches free backends; `sv_active` is in-use; `sv_used` is reserved by the coordinator (see below).
 - `maxwait` is the longest current wait in seconds. If it grows beyond `query_wait_timeout`, clients get errors.
 
+### `SHOW STARTUP_PARAMETERS`
+
+```
+user | database | parameter         | value             | source
+app  | mydb     | statement_timeout | 5s                | general
+app  | mydb     | plan_cache_mode   | force_custom_plan | pool
+```
+
+- `source` shows the layer that supplied the winning value: `general`,
+  `pool`, or `auth_query`.
+- The command reports the same effective cascade used for new backend
+  `StartupMessage` packets.
+
 ### `SHOW POOL_COORDINATOR`
 
 ```

diff --git a/documentation/en/src/tutorials/startup-parameters.md b/documentation/en/src/tutorials/startup-parameters.md
@@ -0,0 +1,172 @@
+# PostgreSQL startup parameters
+
+Use `startup_parameters` when a pool needs PostgreSQL GUC defaults that
+should be set at backend startup, without changing `postgresql.conf`,
+`ALTER ROLE`, or `ALTER DATABASE`.
+
+- A hot OLTP pool is affected by a sticky generic plan after the
+  `plan_cache_mode = auto` heuristic flips. Switching the whole role
+  to `force_custom_plan` would affect every workload using that role;
+  setting it on one pool limits the blast radius.
+- An application that does not set its own `statement_timeout` or
+  `idle_in_transaction_session_timeout` and cannot be patched fast
+  enough. The DBA needs a server-side default that survives the
+  application's own session resets.
+- A single application that should announce a stable
+  `application_name` regardless of what the connecting driver
+  negotiates, so `pg_stat_activity` and audit logs stay legible.
+
+## Configuration
+
+The cascade has three levels; the more specific level wins per key:
+
+```toml
+[general.startup_parameters]
+statement_timeout = "5s"
+
+[pools.checkout.startup_parameters]
+plan_cache_mode = "force_custom_plan"
+work_mem        = "64MB"
+```
+
+After `SIGHUP` (or `RELOAD` on the admin console) every new backend
+for the `checkout` pool starts with `statement_timeout = 5s`,
+`plan_cache_mode = force_custom_plan`, and `work_mem = 64MB`. Other
+pools keep `statement_timeout = 5s` from `general` and the PG default
+for the rest. Already-open backends are not affected; the change takes
+hold as the pool rotates connections.
+
+When `auth_query` runs in passthrough mode (no `server_user`), the
+lookup SQL may return an optional `startup_parameters` text column
+holding a JSON object. Values from that column override both
+`general` and per-pool settings for that user only:
+
+```sql
+SELECT
+  rolpassword AS passwd,
+  CASE rolname
+    WHEN 'vip' THEN '{"work_mem":"256MB"}'::text
+    ELSE NULL::text
+  END AS startup_parameters
+FROM pg_authid
+WHERE rolname = $1;
+```
+
+The column must serialise as `text`. If the SQL returns `json` or
+`jsonb`, add an explicit `::text` cast. pg_doorman reads the column
+as `text` and logs a one-time warning per user when the type does
+not match.
+
+Dedicated `auth_query` mode (`server_user` set) ignores the per-user
+column and logs once per (pool, username): one shared backend serves
+many users, so a per-user override cannot apply.
+
+## What pg_doorman does with the values
+
+The merged map is written into the PostgreSQL `StartupMessage` of
+every backend pg_doorman opens. PG records each entry as the session
+default for that setting (`pg_settings.reset_val` and
+`pg_settings.source = 'client'`), so client-side `RESET ALL` and
+`DISCARD ALL` restore the operator value rather than discarding it.
+Operators get a stable session default without editing
+`postgresql.conf` or running `ALTER ROLE`.
+
+The values can be observed from the client:
+
+```text
+checkout=> SHOW plan_cache_mode;
+ plan_cache_mode
+-------------------
+ force_custom_plan
+
+checkout=> SET plan_cache_mode = 'auto'; RESET ALL; SHOW plan_cache_mode;
+ plan_cache_mode
+-------------------
+ force_custom_plan
+```
+
+## Validation
+
+At config load:
+
+- Keys must match PG GUC naming `^[A-Za-z_][A-Za-z0-9_.]*$`. Namespaced
+  names like `auto_explain.log_min_duration` are accepted; arbitrary
+  punctuation is not.
+- Reserved keys (`user`, `database`, `replication`, `options`, and
+  anything starting with `_pq_.`) are refused. pg_doorman manages
+  them itself or PG treats them specially in the StartupMessage.
+- Values must not contain null bytes.
+- Each level (general or per-pool) must fit within the operator
+  budget: `MAX_STARTUP_PACKET_LENGTH` (10 000 bytes) minus 512 bytes
+  reserved for pg_doorman-managed keys.
+
+At every backend spawn pg_doorman re-checks the merged cascade
+against the same cap. Two levels that fit individually can together
+push past it once `auth_query` adds a third layer; when that happens
+pg_doorman drops every operator-supplied key for that one spawn,
+logs the byte counts, and starts the backend with PostgreSQL defaults
+for those keys.
+
+## What happens when PG rejects a parameter
+
+If PostgreSQL rejects an operator-supplied parameter at backend
+startup, pg_doorman forwards the PG `ErrorResponse` to the client
+unchanged. The client sees the same sqlstate (`22023`,
+`42704`, `42501`, `55P02`, or any other code under the startup family)
+and the same message it would have seen connecting to PG directly.
+
+pg_doorman does not retry with the parameter removed and does not keep a
+per-pool quarantine. The next client connection sends the same
+`StartupMessage`; fix the config before routing traffic back to that
+pool.
+
+## Observability
+
+The admin SQL console exposes the per-pool effective cascade:
+
+```text
+admin> SHOW STARTUP_PARAMETERS;
+ user  | database | parameter        | value             | source
+-------+----------+------------------+-------------------+-----------
+ shop  | checkout | plan_cache_mode  | force_custom_plan | pool
+ shop  | reports  | statement_timeout| 10s               | general
+```
+
+The Web UI's pool detail page shows the same view in the "Startup
+parameters (operator-injected)" section.
+
+Prometheus exports one counter for PG-side rejections:
+
+- `pg_doorman_backend_startup_parameter_errors_total{pool, sqlstate}`
+  counts every backend startup PostgreSQL rejected because of an
+  operator-supplied parameter. The failing parameter name and
+  username are written to the warning log line, not to metric labels.
+
+Alert on a non-zero
+`pg_doorman_backend_startup_parameter_errors_total` rate for the same
+pool over several minutes. That usually means new backend startups for
+the pool are failing on the same operator GUC.
+
+## When not to use this
+
+- The application already sets the parameter on every connection.
+  Duplicating the value in `startup_parameters` adds another config path
+  without changing behavior.
+- Per-transaction tuning (`SET LOCAL`). `startup_parameters` is for
+  session defaults; transaction-scoped tuning belongs in the
+  application.
+- Anything that needs to depend on which query the application is
+  running. Startup parameters apply to every transaction on every
+  backend for the lifetime of that backend; there is no
+  per-statement variant.
+
+## Reference
+
+- [General Settings](../reference/general.md): `startup_parameters`.
+- [Pool Settings](../reference/pool.md):
+  `pools.<name>.startup_parameters`.
+- [auth_query](../authentication/auth-query.md): passthrough vs
+  dedicated modes, where the `startup_parameters` column is read.
+- [Admin Commands](../observability/admin-commands.md):
+  `SHOW STARTUP_PARAMETERS`.
+- [Prometheus](../reference/prometheus.md): full metric list.
diff --git a/documentation/ru/src/SUMMARY.md b/documentation/ru/src/SUMMARY.md
@@ -30,6 +30,7 @@
 - [Режимы пула](concepts/pool-modes.md)
 - [Координатор пулов](concepts/pool-coordinator.md)
 - [Кеш Parse для анонимных prepared statements](tutorials/prepared-statements.md)
+- [Параметры запуска PostgreSQL](tutorials/startup-parameters.md)
 - [Пул под нагрузкой (продвинутое)](tutorials/pool-pressure.md)
 
 # Высокая доступность

diff --git a/documentation/ru/src/authentication/auth-query.md b/documentation/ru/src/authentication/auth-query.md
@@ -28,7 +28,12 @@ pools:
       cache_failure_ttl: "30s"
 ```
 
-Запрос должен возвращать колонку с именем `passwd` или `password`, содержащую хеш MD5 или SCRAM. Дополнительные колонки игнорируются.
+Запрос должен возвращать колонку с именем `passwd` или `password`,
+содержащую хеш MD5 или SCRAM. Дополнительные колонки игнорируются, кроме
+необязательной `startup_parameters`. В passthrough-режиме pg_doorman
+читает её как JSON-объект в `text` с пользовательскими параметрами
+запуска PostgreSQL. Dedicated-режим игнорирует её и пишет
+предупреждение.
 
 `user` и `password` — это учётные данные, под которыми pg_doorman выполняет lookup-запрос. У них должно быть право читать колонку с учётными данными. Либо выдайте доступ к специально созданному представлению (рекомендуется), либо используйте пользователя из группы `pg_read_server_files`.
 

diff --git a/documentation/ru/src/comparison.md b/documentation/ru/src/comparison.md
@@ -77,6 +77,7 @@ PgCat намеренно опущен: у него центр тяжести —
 | LISTEN / NOTIFY pinning в transaction mode | Нет | Нет | Экспериментально |
 | Cross-rule connection cap (`shared_pool`) | Нет | Нет | Да (с 1.5.1) |
 | Команды администратора `PAUSE` / `RESUME` / `RECONNECT` | Да | Да | Да (с 1.4.1) |
+| GUC PostgreSQL, заданные оператором и переданные в `StartupMessage` бэкенда на уровне пула | Да (`startup_parameters`, трёхуровневый каскад `general` → пул → `auth_query` passthrough; значения переживают клиентские `RESET ALL` / `DISCARD ALL`; если PG отвергает параметр, `ErrorResponse` пробрасывается клиенту без изменений — никаких скрытых повторов) | Нет эквивалентного каскада с таким контрактом сброса; отдельные клиентские startup-параметры можно отслеживать или игнорировать, но не задавать оператором на уровне пула | Нет (`maintain_params` сохраняет параметры клиента при rebind, операторского задания GUC нет) |
 
 См. [Координатор пулов](concepts/pool-coordinator.md), [Пул под нагрузкой](tutorials/pool-pressure.md).