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
@@ -245,6 +245,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/changelog.md b/documentation/en/src/changelog.md
@@ -1,5 +1,90 @@
 # Changelog
 
+### 3.9.0
+
+Per-pool injection of arbitrary PostgreSQL configuration parameters
+(GUCs) into the backend `StartupMessage`. The map cascades over three
+levels — `general.startup_parameters`, per-pool overrides, and an
+optional `auth_query` JSON column for per-user values in passthrough
+mode — and the resulting values are written to `pg_settings.reset_val`,
+so they survive client-side `RESET ALL` and `DISCARD ALL`. Among
+mainstream poolers this is unique to pg_doorman: PgBouncer only carries
+`client_encoding` / `datestyle` / `timezone` per database via the
+connection string, Odyssey's `maintain_params` preserves client-side
+parameters but offers no operator-side injection, and PgCat exposes no
+equivalent.
+
+The most common use case is forcing `plan_cache_mode = "force_custom_plan"`
+on a hot OLTP pool that keeps getting bitten by a sticky generic plan;
+the same mechanism pins `statement_timeout`, `work_mem`,
+`idle_in_transaction_session_timeout`, or any other GUC that a single
+application needs without touching `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, with the more specific level winning. Auth_query in
+  dedicated mode (a shared `server_user`) intentionally ignores the
+  per-user column and logs a one-time warning per pool and username.
+- The merged cascade is resolved lazily on every backend spawn from
+  the live config snapshot, so a `RELOAD` that only changes
+  `general.startup_parameters` takes effect on the next backend
+  without recycling the pool.
+
+#### 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 rechecked at every spawn 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, so the connection still completes with PG defaults instead
+  of failing every client request.
+
+#### Quarantine for keys PG keeps rejecting
+
+- After
+  `general.startup_parameter_quarantine_threshold` consecutive
+  rejections of the same key (default `3`), pg_doorman parks the key
+  for `general.startup_parameter_quarantine_ttl` (default 5 minutes)
+  and stops sending it on subsequent backend startups.
+- Both knobs are hot-reloadable: a SIGHUP that touches only the
+  threshold or TTL takes effect on every pool without rebuild.
+- A successful backend startup resets partial-rejection counters for
+  every key it accepted, keeping the threshold model "N consecutive
+  rejections" rather than "N rejections ever".
+- The quarantine record is keyed on the failing parameter name parsed
+  from PG's error message and cross-checked against the map pg_doorman
+  actually sent, so a server-side `ALTER ROLE SET` rejection for an
+  unrelated key cannot poison the operator's quarantine.
+- SQLSTATE class `57P` keeps mapping to `ServerUnavailableError` and
+  drives the Patroni-assisted fallback path; the quarantine
+  observability runs alongside that mapping, not in place of it.
+
+#### Observability
+
+- `pg_doorman_backend_startup_parameter_errors_total{pool,parameter,sqlstate}`
+  counts every rejection. The failing username is in the corresponding
+  warn log line; it is deliberately not a label, so a dynamic
+  `auth_query` pool that mints many roles cannot blow up the series
+  count.
+- `pg_doorman_backend_startup_parameter_quarantined{pool,parameter}`
+  goes to 1 the moment a key is parked and back to 0 when the TTL
+  expires, including on idle pools where the metrics collector
+  reconciles the gauge without waiting for the next backend spawn.
+- `SHOW POOLS` exposes a `quarantined_params` text column so operators
+  can see at a glance which keys a pool is currently dropping.
+
+See [PostgreSQL startup parameters](tutorials/startup-parameters.md)
+for the operator walkthrough and the
+[reference entry](reference/configuration.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-supplied PostgreSQL GUCs injected into backend `StartupMessage` per pool | Yes (`startup_parameters`, three-level cascade `general` → pool → `auth_query` passthrough, survives client `RESET ALL` / `DISCARD ALL`, with per-pool quarantine for keys PG keeps rejecting) | No (only `client_encoding` / `datestyle` / `timezone` per-database in the connection string) | No (`maintain_params` preserves client-side parameters across rebind; no operator-side injection) |
 
 See [Pool Coordinator](concepts/pool-coordinator.md), [Pool pressure](tutorials/pool-pressure.md).
 

diff --git a/documentation/en/src/tutorials/startup-parameters.md b/documentation/en/src/tutorials/startup-parameters.md
@@ -0,0 +1,186 @@
+# PostgreSQL startup parameters
+
+Some operators need a few PostgreSQL configuration parameters to apply
+to every backend pg_doorman opens, without touching `postgresql.conf`,
+`ALTER ROLE`, or `ALTER DATABASE`. Three cases recur in practice:
+
+- A hot OLTP pool gets bitten 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;
+  scoping the change to one pool is what you want.
+- 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.
+
+`startup_parameters` lets pg_doorman do this from its own config.
+
+## 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 = 'session'`), 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 lets the backend connect with PG's own
+defaults rather than failing every connection attempt.
+
+## Quarantine
+
+PG can reject an operator-supplied parameter at backend startup with
+sqlstate `22023` (invalid value), `42704` (undefined object: typo
+in the parameter name), or `42501` (insufficient privilege: the
+parameter requires a higher role than the backend has). pg_doorman
+counts consecutive rejections per `(pool, parameter)`; once the
+count reaches `general.startup_parameter_quarantine_threshold`
+(default 3), pg_doorman stops sending that key for
+`general.startup_parameter_quarantine_ttl` (default 5 minutes).
+
+A successful backend startup resets the counter for every key it
+just sent. Three transient rejections do not trigger quarantine if a
+successful spawn lands between them; "consecutive" really means
+consecutive.
+
+Both knobs are hot-reloaded on `SIGHUP`. Releasing a quarantined
+parameter is **TTL-only**: pg_doorman cannot tell whether the
+operator has fixed the underlying problem until the TTL expires and
+the next backend spawn tries the parameter again.
+
+## Observability
+
+`SHOW POOLS` carries a `quarantined_params` column listing the
+currently parked parameters per pool, comma-separated:
+
+```text
+ database | user  | ... | quarantined_params
+----------+-------+-----+--------------------
+ checkout | shop  | ... | work_mem,search_path
+ reports  | shop  | ... |
+```
+
+The same state is on the Prometheus surface:
+
+- `pg_doorman_backend_startup_parameter_errors_total{pool, parameter, sqlstate}`
+  counts every rejection from PG. Increments once per failed
+  StartupMessage; the failing username is on the corresponding warn
+  log line so dynamic `auth_query` pools cannot blow up the series
+  count.
+- `pg_doorman_backend_startup_parameter_quarantined{pool, parameter}`
+  is `1` while a parameter is parked and flips back to `0` exactly
+  once when its TTL expires. The gauge does not clear on its own
+  even after the operator fixes the underlying issue; the next
+  spawn after TTL expiry is what re-arms it.
+
+A reasonable starting alert is "any non-zero quarantine gauge for
+longer than the TTL". If the gauge is set for `2 × ttl`, the
+operator-supplied value is still wrong after one retry window and
+deserves a look.
+
+## When not to use this
+
+- The application already sets the parameter on every connection.
+  Putting the same value in `startup_parameters` adds a bookkeeping
+  surface for no behavioural change.
+- 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`,
+  `startup_parameter_quarantine_threshold`,
+  `startup_parameter_quarantine_ttl`.
+- [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 POOLS`.
+- [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)
+- [Startup-параметры PostgreSQL](tutorials/startup-parameters.md)
 - [Пул под нагрузкой (продвинутое)](tutorials/pool-pressure.md)
 
 # Высокая доступность

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 раз за разом отклоняет) | Нет (только `client_encoding` / `datestyle` / `timezone` в строке подключения на уровне базы) | Нет (`maintain_params` сохраняет параметры клиента при rebind, операторской инжекции нет) |
 
 См. [Координатор пулов](concepts/pool-coordinator.md), [Пул под нагрузкой](tutorials/pool-pressure.md).