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
@@ -204,13 +204,10 @@ jobs:
 
   # Single matrixed job replaces the 21 nearly-identical per-language /
   # per-suite jobs that used to live here. Each suite differs only in
-  # the cargo command it runs; share everything else.
-  #
-  # Why no `nick-fields/retry` around the cargo step: the legacy jobs
-  # wrapped `cargo test` in max_attempts: 2, which masks intermittent
-  # BDD failures rather than surfaces them. Retry stays on the network
-  # `docker pull` step, where it covers GHCR manifest visibility lag
-  # right after a fresh push (the typical real-world flake).
+  # the cargo command it runs; share everything else. See the cargo
+  # step below for the retry policy and why three attempts beat two
+  # on the dominant GHA flake families (DNS to crates.io, timing-
+  # sensitive lifecycle scenarios).
   bdd-tests:
     name: 'BDD: ${{ matrix.suite.name }}'
     needs: prepare-tests
@@ -222,6 +219,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 +248,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
@@ -269,9 +273,44 @@ jobs:
           command: docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.prepare-tests.outputs.image-tag }}
 
       - name: Run BDD suite (${{ matrix.suite.name }})
-        run: |
-          docker run --rm \
-            -v ${{ github.workspace }}:/workspace \
-            -w /workspace \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.prepare-tests.outputs.image-tag }} \
-            cargo ${{ matrix.suite.cargo }}
+        # `--network=host` is the load-bearing flag. With the default
+        # bridge network, the container inherits DNS from the docker
+        # daemon, which on a GitHub-hosted runner does not always
+        # re-export the host's systemd-resolved stub at 127.0.0.53.
+        # When the bridge resolver is wedged for a job, every cargo
+        # attempt inside the container fails with
+        # `Could not resolve host: index.crates.io` and stays wedged
+        # for minutes — both cargo's own retries and an outer step
+        # retry hit the same dead resolver. Outer retries do not
+        # rescue that case (we tried 3×30 s in a previous commit and
+        # the job still drained all three attempts on the wedged
+        # resolver). Sharing the host's network stack short-circuits
+        # the bridge resolver entirely; this is safe because each
+        # matrix entry runs on its own ephemeral runner, so no two
+        # BDD suites contend for the same loopback ports.
+        #
+        # `CARGO_NET_RETRY=10` (default 2) and `CARGO_HTTP_TIMEOUT=60`
+        # (default 30 s) widen cargo's internal network retry loop for
+        # the residual case where the host's own resolver works but
+        # `index.crates.io` itself rate-limits or 5xx's mid-fetch.
+        #
+        # The outer 2-attempt retry remains for the timing-sensitive
+        # BDD flake family (SCRAM passthrough reconnect after retain,
+        # sleep-based lifecycle waits) that occasionally loses its
+        # margin under cross-job contention. It is not a network
+        # safety net — that responsibility moved to `--network=host`
+        # plus the cargo env vars above.
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 30
+          max_attempts: 2
+          retry_wait_seconds: 5
+          command: |
+            docker run --rm \
+              --network=host \
+              -e CARGO_NET_RETRY=10 \
+              -e CARGO_HTTP_TIMEOUT=60 \
+              -v ${{ github.workspace }}:/workspace \
+              -w /workspace \
+              ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.prepare-tests.outputs.image-tag }} \
+              cargo ${{ matrix.suite.cargo }}
diff --git a/.github/workflows/dashboard-validation.yml b/.github/workflows/dashboard-validation.yml
@@ -95,7 +95,24 @@ jobs:
               > grafana/demo/grafana/provisioning/dashboards/pg_doorman.json
 
       - name: Run smoke + ground-truth against grafana/demo
-        run: make dashboard-validate-ci
+        # Demo TPS warms up at different speed across shared GitHub
+        # runners, so a single attempt occasionally hits a panel that
+        # has not yet populated its rate window. Retry twice with a
+        # cleanup tear-down between attempts before failing the job.
+        run: |
+          set -e
+          attempt=1
+          max_attempts=3
+          until make dashboard-validate-ci; do
+              if [ "$attempt" -ge "$max_attempts" ]; then
+                  echo "dashboard-validate-ci failed after $attempt attempts" >&2
+                  exit 1
+              fi
+              echo "dashboard-validate-ci attempt $attempt failed; tearing down and retrying" >&2
+              (cd grafana/demo && docker compose -f docker-compose.yml -f docker-compose.ci.yml down -v) || true
+              sleep 5
+              attempt=$((attempt + 1))
+          done
 
       - name: Collect demo logs on failure
         if: failure()

diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,7 @@
 .idea
 .junie
 .claude
-/target
+target/
 .DS_Store
 .direnv
 .pre-commit-config.yaml
@@ -57,6 +57,12 @@ flamegraph-output/
 # Superpowers brainstorm session workdir (VC mockups, server state)
 .superpowers/
 
+# Superpowers spec drafts (private session artifacts)
+/docs/superpowers/
+
+# Internal planning notes (private session artifacts)
+/docs/internal-plans/
+
 # 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,87 @@
 # Changelog
 
+### 3.9.0
+
+Per-pool PostgreSQL startup parameters. pg_doorman can now add
+configured GUCs to each backend `StartupMessage`. Values apply 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 configured 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
+  are applied in order. Later layers override earlier ones per key.
+- 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 startup-parameter
+  budget of `MAX_STARTUP_PACKET_LENGTH - 512` bytes.
+- The resolved parameter set is checked before each backend startup
+  against PG's 10 000-byte `MAX_STARTUP_PACKET_LENGTH`. If only the
+  auth_query layer overflows the packet, pg_doorman drops that layer and
+  keeps the general/pool baseline. If the baseline itself does not fit,
+  pg_doorman skips all configured keys for that spawn and logs the
+  byte counts.
+
+#### Behaviour on PG-side rejection
+
+- If PostgreSQL rejects a configured startup parameter at backend
+  startup, pg_doorman returns PostgreSQL's `ErrorResponse` to the
+  client unchanged. pg_doorman does not retry without the key and does
+  not disable the key automatically for the pool. Fix the parameter in
+  the config; until then, backend startup for that pool fails with
+  PostgreSQL's own SQLSTATE and message.
+- SQLSTATEs with the `57P` prefix (server unavailable) keep mapping to
+  `ServerUnavailableError` first so the Patroni-assisted fallback
+  path can route around the failed node before the startup-parameter
+  log line fires.
+- The configured 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 configured value on
+  the backend. That 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 backend startups PostgreSQL rejected because of an
+  configured startup 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
+  resolved parameters with the source of each value. `psql` tab
+  completion on `SHOW <TAB>` now includes the command.
+- The Web UI pool detail page shows the same rows in a "Startup
+  parameters (configured)" section, driven by the new
+  `startup_parameters[]` field on `/api/pools`.
+
+See [PostgreSQL startup parameters](tutorials/startup-parameters.md)
+for the configuration 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
@@ -108,7 +190,7 @@ live in [`guides/web-ui.md`](guides/web-ui.md).
 **Built-in operator dashboard.** pg_doorman exposes a single-page
 diagnostic console on the same port as `/metrics`, served from
 inside the binary and gated on `[web].ui = true` plus a non-default
-`admin_password`. Reaching the same view through the existing psql
+`admin_password`. Getting comparable detail from the existing psql
 admin console means running `SHOW POOLS`, `SHOW CLIENTS`,
 `SHOW STATS` and friends in a loop, computing rates by hand between
 two snapshots, and joining the rows mentally. The dashboard does

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) |
+| Configured PostgreSQL GUCs in backend `StartupMessage` per pool | Yes (`startup_parameters`, applied as `general` → pool → passthrough `auth_query`; client `RESET ALL` / `DISCARD ALL` returns to those values; PG startup errors reach the client unchanged) | No equivalent configured defaults; selected client startup parameters can be tracked or ignored | No (`maintain_params` preserves client-side parameters across rebind; no configured GUCs) |
 
 See [Pool Coordinator](concepts/pool-coordinator.md), [Pool pressure](tutorials/pool-pressure.md).
 

diff --git a/documentation/en/src/guides/web-ui.md b/documentation/en/src/guides/web-ui.md
@@ -129,7 +129,8 @@ proxy:
 | `sso_allowed_users` | Allowlist on the `preferred_username` (or `sub`) claim. `["*"]` accepts every valid JWT; a literal list restricts access to those usernames. | `["*"]` |
 | `sso_groups_claim` | Name of the JWT claim that carries the user's group memberships. Read together with `sso_admin_groups`. | `"groups"` |
 | `sso_admin_groups` | Group names that promote an SSO user to `Admin`. Empty keeps every SSO login at the read-only `Sso` role. | `[]` |
-| `trusted_proxies` | CIDR ranges trusted to set `X-Forwarded-For` / `Forwarded`. Empty trusts only the listener's own peer. See [Access log](#access-log). | `[]` |
+| `sso_require_https` | Reject Bearer/cookie/query SSO credentials presented over plain HTTP. The listener treats a request as secure only when the TCP peer is in `trusted_proxies` and `X-Forwarded-Proto: https` is forwarded. Defaults to off so SSO keeps working through a TLS-terminating proxy that reaches pg_doorman over a private HTTP leg. | `false` |
+| `trusted_proxies` | CIDR ranges trusted to set `X-Forwarded-For` / `Forwarded` / `X-Forwarded-Proto`. Empty trusts only the listener's own peer. See [Access log](#access-log). | `[]` |
 
 ### Promoting SSO users to Admin via group claim
 

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` | Resolved `startup_parameters` per pool: parameter, value, source, and application state. |
 | `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  | state
+app  | mydb     | statement_timeout | 5s                | general | applied
+app  | mydb     | plan_cache_mode   | force_custom_plan | pool    | applied
+```
+
+- `source` shows where the value came from: `general`, `pool`, or
+  `auth_query`.
+- `state` shows whether the next backend `StartupMessage` will carry
+  the value: `applied`, `dropped_due_to_budget`, or `stale`.
+
 ### `SHOW POOL_COORDINATOR`
 
 ```
@@ -109,7 +123,7 @@ Admin connections do not pass through `pg_hba.conf` rules — they go directly t
 
 ## Where to next
 
-- [Prometheus reference](../reference/prometheus.md) — same data, machine-readable.
+- [Prometheus reference](../reference/prometheus.md) — the metric form of the same state.
 - [Pool Coordinator](../concepts/pool-coordinator.md) — what `SHOW POOL_COORDINATOR` is telling you.
 - [Pool Pressure](../tutorials/pool-pressure.md) — what `SHOW POOL_SCALING` is telling you.
 - [Troubleshooting](../tutorials/troubleshooting.md) — common failure modes and their `SHOW` output.