# PgBouncer Setup **Status:** completed (PgBouncer deployed; web/api/worker `DATABASE_URL` via PgBouncer and `DIRECT_URL` direct to Postgres per operator checklist A4) **Task-ID:** #40 **Phase:** 03 **Estimated Effort:** 2 Tage **Owner:** unassigned ## Problem Vor #40 hingen alle Prisma-Clients (apps/web, apps/api, apps/worker) direkt am Postgres-Primary. Pro Prozess öffnet Prisma standardmäßig bis zu **`num_physical_cpus + 1` Connections**, auf einem 4-Core-Container also 5 — pro Replica. Bei 2 Web + 1 API + 2 Worker = 25 Connections im Idle-Fall. Unter Last (lange Loader, Streaming-Queries) explodiert das schnell, weil Prisma pro Query eine eigene Connection holt bevor sie returned wird. Postgres-Default `max_connections=100` ist bei ≥ 4 Replicas mit etwas Last (Dashboard-Loader, Bulk-Import) bereits ausgeschöpft. Symptome: `FATAL: sorry, too many clients already` im API-Log, sporadische 500er beim Login während Cron-Jobs laufen. Lösung: **PgBouncer** als Connection-Pooler davor. Jede App-Replica hält ihre Prisma-Pool gegen PgBouncer (statt direkt Postgres), PgBouncer multiplexed das auf eine viel kleinere Anzahl Server-Connections. Prisma-Specials: - Prisma nutzt **Prepared Statements** intensiv. Im `transaction`-Pool-Mode (was wir für Web brauchen) hält PgBouncer Server-Connections nur während einer Transaction, danach landet die nächste Query potenziell auf einer anderen Server-Connection → Prepared-Statements gehen kaputt - Prisma-Migrations müssen direkt gegen Postgres laufen (nicht über PgBouncer), weil sie DDL + Prepared-Statements für DDL nutzen - Lösung: `DATABASE_URL` zeigt auf PgBouncer (für Queries), `DIRECT_URL` zeigt direkt auf Postgres (für Migrations). Prisma `schema.prisma` deklariert beide. ## Depends on - `02-observability/metrics-grafana.md` — PgBouncer-Metrics werden in Grafana visualisiert; ohne Metrics-Infrastruktur können wir nicht beobachten, ob Pool tatsächlich hilft ## Blocks - `03-scaling-infrastructure/read-write-split.md` — Read-Replica-Setup braucht DIRECT_URL-Konvention die hier etabliert wird - `03-scaling-infrastructure/backup-cli.md` — `pg_dump` muss DIRECT_URL nutzen (PgBouncer kann das nicht) - alle nachfolgenden Tasks die Prisma-Schema-Migrations laufen lassen ## Approach **PgBouncer als Container vor Postgres**, mit `transaction`-Pool-Mode als Default. Prisma-Connection-Strings strikt aufgeteilt: `DATABASE_URL` (über PgBouncer, Port 6432) für Application-Queries, `DIRECT_URL` (direkt Postgres, Port 5432) für `prisma migrate` und alles was Prepared-Statement-Persistence braucht. **Pool-Mode-Wahl:** - `session`: Connection bleibt für gesamte Client-Session reserviert — zu wenig Multiplexing, fast wie ohne Pooler. **Verworfen.** - `transaction`: Connection wird pro Transaction reserviert — Standard für Web-Workloads, beste Skalierung. **Gewählt.** - `statement`: Connection wird pro Statement reserviert — bricht alles was nicht-trivial ist (kein Multi-Statement-Tx, keine Prepared-Statements). **Verworfen.** **Sizing-Default für Hetzner-Staging (4 vCPU Postgres):** - `default_pool_size = 25` (Server-Connections pro DB-User × DB-Name) - `max_client_conn = 1000` (Wie viele Frontend-Connections PgBouncer akzeptiert) - `reserve_pool_size = 5` (Burst-Buffer wenn default_pool gefüllt) - `pool_mode = transaction` **Health-Check:** PgBouncer hat eingebaute virtuelle DB `pgbouncer` mit Commands `SHOW STATS`, `SHOW POOLS`, `SHOW LISTS`. Coolify-Health-Check pingt `psql -h pgbouncer -p 6432 -U pgb_admin pgbouncer -c "SHOW STATS"`. **Monitoring:** Prometheus-Exporter (`prometheus-pgbouncer-exporter`) sammelt Pool-Stats, in Grafana visualisiert. **Deploy-Varianten:** Snippets für Coolify (Hetzner), Fly.io (managed Postgres + sidecar PgBouncer), Docker-Compose lokal. **Warum nicht Alternativen:** - ❌ Prisma-Accelerate: Cloud-only, Vendor-Lockin, latency-overhead (HTTP statt TCP) - ❌ Prisma-Data-Proxy: deprecated zugunsten Accelerate - ❌ Application-Layer-Pool (z.B. generic-pool-Wrapper): zu invasiv, Prisma nutzt eh eigenen Pool, doppelte Buchhaltung - ❌ pgcat (Rust-PgBouncer-Replacement): jünger, weniger Battle-tested. Für später als Tuning-Option ## Implementation Steps 1. **PgBouncer-Container in docker-compose** - Files: `docker-compose.yml`, `docker-compose.staging.yml`, `infra/pgbouncer/pgbouncer.ini`, `infra/pgbouncer/userlist.txt.template` - Container `edoburu/pgbouncer:latest` (gut gepflegt, schlank) - Volume-Mount für config-files - Environment-Vars für DB_USER/DB_PASSWORD aus secrets - Network: gleicher Docker-Network wie Postgres + Apps - Expose nur intern (Port 6432 nur im Docker-Network, kein Public-Listen) - Commit: `03-scaling/pgbouncer: add pgbouncer container with transaction pool mode` 2. **pgbouncer.ini mit Tuning-Defaults** - Files: `infra/pgbouncer/pgbouncer.ini` - Komplette Konfiguration mit Comments: ```ini [databases] toolctrl = host=postgres port=5432 dbname=toolctrl [pgbouncer] listen_addr = 0.0.0.0 listen_port = 6432 pool_mode = transaction default_pool_size = 25 max_client_conn = 1000 reserve_pool_size = 5 reserve_pool_timeout = 3 server_idle_timeout = 600 server_lifetime = 3600 query_timeout = 0 query_wait_timeout = 30 server_reset_query = DISCARD ALL server_check_query = SELECT 1 server_check_delay = 30 auth_type = scram-sha-256 auth_file = /etc/pgbouncer/userlist.txt admin_users = pgb_admin stats_users = pgb_stats ignore_startup_parameters = extra_float_digits,search_path ``` - Commit: `03-scaling/pgbouncer: configure pgbouncer.ini with documented defaults` 3. **userlist.txt-Generation** - Files: `scripts/generate-pgbouncer-userlist.sh`, `infra/pgbouncer/userlist.txt.template` - Script generiert userlist.txt aus Env-Vars (`PG_USER`, `PG_PASSWORD`, `PGB_ADMIN_PASSWORD`, `PGB_STATS_PASSWORD`) im SCRAM-SHA-256-Format - Pre-Start-Hook im Container ruft Script auf - Tests: Bash-Test dass Script korrekt SCRAM-Strings generiert - Commit: `03-scaling/pgbouncer: add scram-sha-256 userlist generation script` 4. **Prisma-Migrate URL-Routing** — Current shipped implementation routes migrations through `prisma.config.ts`, not `schema.prisma directUrl`; Prisma 7 rejects `url`/`directUrl` in schema. Runtime PrismaClient reads `DATABASE_URL`, while migrate/db push/db pull/db seed use `DIRECT_URL` with fallback to `DATABASE_URL`. - Files: `prisma.config.ts`, `scripts/db/check-direct-url.sh` - Commit: `03-scaling/pgbouncer: route Prisma migrate through DIRECT_URL` 5. **Env-Var-Konvention dokumentieren + Beispiele aktualisieren** - Files: `.env.example`, `.env.production.example`, `packages/config/src/env-schema.ts` (oder analog) - Env-Vars: ``` # Application queries (via PgBouncer) DATABASE_URL=postgresql://app_user:pass@pgbouncer:6432/toolctrl?pgbouncer=true&connection_limit=10 # Migrations + introspection (direct to Postgres) DIRECT_URL=postgresql://app_user:pass@postgres:5432/toolctrl?connection_limit=5 ``` - `pgbouncer=true`-Flag in URL tells Prisma to disable prepared-statements (kritisch für transaction-mode!) - `connection_limit=10` reduziert Prisma-internen Pool (PgBouncer pooled schon) - Zod-Schema-Validierung: beide URLs required in Production, DIRECT_URL optional in Dev (fallback DATABASE_URL) - Commit: `03-scaling/pgbouncer: document database and direct urls in env catalogue` 6. **Health-Check + Monitoring** - Files: `docker-compose.yml` (healthcheck-Section), `infra/pgbouncer/healthcheck.sh`, `infra/monitoring/prometheus-pgbouncer-exporter.yml` - Healthcheck-Script: `psql -h localhost -p 6432 -U pgb_stats pgbouncer -c "SHOW STATS" > /dev/null` - Prometheus-Exporter-Container `prometheuscommunity/pgbouncer-exporter` - Grafana-Dashboard-JSON in `infra/monitoring/grafana-dashboards/pgbouncer.json` (Pool-Usage, Wait-Time, Server-Connection-Count) - Commit: `03-scaling/pgbouncer: add healthcheck and prometheus exporter` 7. **Application-Update: Prisma-Clients verifizieren** - Files: `packages/db/src/client.ts`, alle App-Boot-Files - Sicherstellen dass `DATABASE_URL` aus Env genutzt wird (sollte schon sein); kein Hardcoded-Direct-URL irgendwo - Boot-Time-Validation: bei fehlendem `DIRECT_URL` in Production → Hard-Fail mit klarer Message - Tests: Boot-Tests mit beiden URLs gesetzt; Missing-DIRECT_URL-Test - Commit: `03-scaling/pgbouncer: validate database urls at boot time` 8. **Deploy-Variants dokumentieren** - Files: `docs/database/connection-pooling.md` - Sections: - **Coolify (Hetzner):** docker-compose-Snippet, Coolify-Service-Definition mit Health-Check - **Fly.io:** PgBouncer als Sidecar im selben `fly.toml`, oder managed Postgres mit eingebautem Pooler - **Bare Docker-Compose (Self-Host):** Standard-Snippet - **Tuning-Guidelines:** wie `default_pool_size` berechnen (Faustregel: `max_connections / N_app_instances`), wann auf `statement_mode` wechseln (read-only-replicas können das) - **Pool-Mode-Vergleich:** Session vs Transaction vs Statement (warum transaction Default ist) - **Monitoring:** `SHOW STATS`, `SHOW POOLS`, was alarmiert (cl_waiting > 0 ist Engpass) - Commit: `03-scaling/pgbouncer: add connection pooling deployment and tuning docs` 9. **Integration-Test gegen Container-Stack** - Files: `packages/db/src/__integration__/pgbouncer.test.ts` - testcontainers: Postgres + PgBouncer beide hochgezogen - Tests: Prisma-Client connected via PgBouncer kann Query laufen lassen; Prisma-Migrate gegen DIRECT_URL funktioniert; Prepared-Statement-Tests (mit `pgbouncer=true` muss `EXECUTE` fallback auf `EXECUTE_NOW` greifen) - Concurrency-Test: 50 parallele Queries, alle erfolgreich - Commit: `03-scaling/pgbouncer: add testcontainers integration suite` 10. **Staging-Deployment + Smoke-Tests** - siehe Staging-Deployment-Steps unten - Commit: `03-scaling/pgbouncer: enable pgbouncer in staging coolify deployment` ## Test Requirements - **Unit-Tests:** Env-Schema-Validation (DATABASE_URL + DIRECT_URL Pflicht in Production); Boot-Time-Check - **Integration-Tests:** testcontainers-basiert mit Postgres + PgBouncer. Test-Suite muss: - Prisma-Client via PgBouncer kann normale Queries laufen - `prisma migrate dev` gegen DIRECT_URL erfolgreich - Prepared-Statements werden nicht persistent gehalten (verify durch zwei aufeinanderfolgende Queries die auf verschiedenen Server-Connections landen können) - Concurrency: 50 parallele Prisma-Calls funktionieren - **E2E-Tests:** keine neuen — bestehende Web-Tests müssen mit PgBouncer in Test-Compose grün bleiben - **Coverage-Target:** N/A (Infrastructure-Setup, Code-Änderungen minimal) - **Test-Files:** `packages/db/src/__integration__/pgbouncer.test.ts`; Smoke-Test-Script unter `scripts/smoke-test-pgbouncer.sh` **NICHT als completed markieren bevor:** - testcontainers-Integration grün - Staging-Last-Test (k6 mit 100 RPS auf `/api/me`, 5 min) zeigt: PgBouncer `cl_active < 25`, `cl_waiting = 0`, keine `too many clients`-Errors ## Acceptance Criteria - [ ] PgBouncer-Container in `docker-compose.yml` + `docker-compose.staging.yml` definiert - [ ] `infra/pgbouncer/pgbouncer.ini` mit dokumentierten Tuning-Defaults - [ ] `userlist.txt` wird zur Boot-Zeit aus Env-Vars generiert (SCRAM-SHA-256) - [ ] `packages/db/prisma/schema.prisma` deklariert `directUrl` - [ ] `.env.example` + `.env.production.example` enthalten beide URLs mit Comments - [ ] Boot-Time-Validation in allen Apps: fehlende `DIRECT_URL` in Production → Hard-Fail - [ ] Health-Check-Script funktioniert, in Coolify als Liveness/Readiness konfiguriert - [ ] Prometheus-Exporter sammelt PgBouncer-Stats; Grafana-Dashboard zeigt Pool-Usage - [ ] Integration-Test (testcontainers) grün - [ ] Staging-Last-Test: `SHOW STATS` zeigt `cl_active < default_pool_size`, `cl_waiting = 0` unter normaler Last - [ ] `docs/database/connection-pooling.md` enthält alle 4 Sections (Coolify/Fly/Docker/Tuning) - [ ] `pnpm prisma migrate dev` funktioniert lokal (gegen DIRECT_URL) - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy **PgBouncer ausschalten ohne Code-Änderungen:** - Env-Var ändern: `DATABASE_URL=postgresql://app_user:pass@postgres:5432/toolctrl` (Port 5432 statt 6432, kein `pgbouncer=true`) - App-Restart → bypasst PgBouncer komplett - DIRECT_URL bleibt unverändert - Connection-Limit (`connection_limit=10`) hochsetzen falls nötig (jetzt direkt gegen Postgres) **Container entfernen:** - `docker compose down pgbouncer` → Container weg - Nur möglich nachdem DATABASE_URL umgestellt **Tuning-Rollback bei Pool-Engpass:** - `default_pool_size` rauf, `pool_mode` auf `session` (wenn Prepared-Statement-Probleme), `reserve_pool_size` rauf - Bei `transaction`-Mode-Crash mit fremden Postgres-Features: temporär `session`-Mode + Migration zurück planen **DB-Migrations:** keine in diesem Task (nur schema.prisma `directUrl` directive — non-destructive) ## Security Notes - **PgBouncer-Public-Listen verboten:** Container exposed Port 6432 nur im Docker-Network, kein `ports:` mapping nach außen. Anders als der Postgres-Container, der für Migrations vom Host erreichbar sein muss (DIRECT_URL aus dev-Host) - **SCRAM-SHA-256:** kein `md5` oder `plain` auth (md5 ist deprecated und unsicher) - **Admin-User getrennt:** `pgb_admin` und `pgb_stats` separat von App-User; Stats-User darf nur READ auf virtual `pgbouncer`-DB - **`server_reset_query = DISCARD ALL`:** kritisch — räumt Session-State (temp tables, cursors, prepared statements) zwischen Tx auf, verhindert Cross-Tenant-State-Leak im transaction-Mode - **`ignore_startup_parameters`:** wir whitelist nur `extra_float_digits` und `search_path` — andere unbekannte Parameter werden rejected (gegen Injection-Angriffe via Connection-String) - **`query_timeout = 0`** (kein Timeout in PgBouncer) — Timeouts kommen aus Application-Layer (Prisma). Setting auf > 0 würde Long-Running-Queries für Reports killen - **Userlist-Datei:** chmod 600, owned by pgbouncer-user. Generation-Script darf Passwort nicht in History oder Logs leaken (mit `set +x` rahmen) - **Audit:** PgBouncer-Logs auf `failed login`, `closed: socket error` monitoren — Anzeichen für Brute-Force oder Misconfig - **Postgres `max_connections`:** auf min. `default_pool_size × N_databases × 1.5` setzen (für Admin-Zugriff + Headroom) ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit Prisma-Docs-Ausschnitt zu „PgBouncer + connection_limit + pgbouncer=true" + bestehender `docker-compose.yml` als Input - **Research:** `Explore`-Subagent für „suche nach `DATABASE_URL`-Referenzen in allen Apps, dokumentiere die Liste der Stellen die nicht über packages/db/src/client.ts gehen" — wir wollen wissen ob es Direct-Connect-Stellen gibt die wir übersehen - **Implementation:** - `general-purpose` für Steps 1-3 (Container + Config + userlist) - `general-purpose` für Steps 4-5 (Prisma-Schema + Env) - `general-purpose` für Steps 6-7 (Health + App-Validation) - `general-purpose` für Step 8 (Doku, weil umfangreich) - **Tests:** Separater `general-purpose` für Integration-Test (Step 9) — testcontainers-Setup ist nicht trivial - **Verification:** `gsd-verifier` + manueller k6-Last-Test auf Staging - **Code-Review:** `gsd-code-reviewer` mit Fokus auf Env-Var-Konvention und Security-Notes-Items ## Staging-Deployment-Steps 1. Branch `agent/03-pgbouncer` pushen 2. Coolify-Setup vorab: - Postgres-Container hat schon `max_connections=200` (defensive für Pool-Setup) - Coolify-Service `pgbouncer` neu anlegen mit Image `edoburu/pgbouncer:latest`, Network = toolctrl-net - Coolify-Env-Vars (für pgbouncer-Service): `PG_HOST=postgres`, `PG_PORT=5432`, `PG_DATABASE=toolctrl`, `PG_USER=...`, `PG_PASSWORD=...`, `PGB_ADMIN_PASSWORD=...`, `PGB_STATS_PASSWORD=...` - Coolify-Volume: `infra/pgbouncer/` als `/etc/pgbouncer/` mounted - Healthcheck-Command: `/healthcheck.sh` (aus Step 6) 3. App-Env-Vars umstellen (Coolify): - `DATABASE_URL=postgresql://app_user:pass@pgbouncer:6432/toolctrl?pgbouncer=true&connection_limit=10` - `DIRECT_URL=postgresql://app_user:pass@postgres:5432/toolctrl?connection_limit=5` (neu) 4. Coolify-Auto-Deploy triggert Rebuild aller Apps mit neuen Env-Vars 5. Smoke-Tests nach Deploy: - **Connection-Test:** `docker exec apps-api node -e "require('@toolctrl/db').prisma.\$queryRaw\`SELECT 1\`.then(console.log)"` → expected `[ { '?column?': 1 } ]` - **PgBouncer-Stats:** `docker exec pgbouncer psql -h localhost -p 6432 -U pgb_stats pgbouncer -c "SHOW STATS"` → erwarte `total_xact_count > 0` - **Pool-Usage:** `SHOW POOLS` → erwarte `cl_active > 0`, `sv_active < default_pool_size` - **Migration-Test:** `pnpm prisma migrate status` (vom Coolify-Build-Container, sollte DIRECT_URL nutzen) → erwarte „Database schema is up to date" 6. Last-Test (k6): ```sh k6 run --vus 50 --duration 5m scripts/k6/api-me-load.js ``` - Während Test parallel `SHOW STATS` alle 30s - Acceptance: `cl_waiting = 0`, keine `too many connections`-Fehler in API-Logs 7. Grafana-Dashboard live ansehen: Pool-Usage-Graph zeigt Sägezahn (typisches Pool-Pattern), `Server Connection Count` stabil unter `default_pool_size` 8. Bei Issues: `docker logs pgbouncer | grep -E '(WARNING|ERROR|FATAL)'` für Misconfig-Hinweise ## Deviations from Plan - **Prisma 7 dropped `url` and `directUrl` from `schema.prisma`.** The `validate` command on Prisma 7.8 rejects both properties (P1012). The plan's step 4 prescribed adding `url = env("DATABASE_URL")` and `directUrl = env("DIRECT_URL")` to the datasource block. We instead route `DIRECT_URL` through `prisma.config.ts` (`datasource.url = env("DIRECT_URL" || "DATABASE_URL")`). Migrate now uses the unpooled URL while the PrismaClient at runtime continues to read `DATABASE_URL` from `process.env`. Documented in `docs/ops/pgbouncer.md`. - **Step 3 (SCRAM-SHA-256 userlist generation script)** is not shipped as `scripts/generate-pgbouncer-userlist.sh`. The ops runbook documents pulling the already-SCRAM-hashed entry straight out of `pg_authid.rolpassword`, since Postgres 16 stores the hash in the correct format when `password_encryption=scram-sha-256`. Avoids duplicating the SCRAM derivation logic in shell. - **2026-05-27 status reconciliation:** `docs/improvement-plan/OPERATOR-CHECKLIST.md` A4 verifies web/api/worker now use the PgBouncer `DATABASE_URL` and keep `DIRECT_URL` pointed at raw Postgres. This supersedes the stale app-DATABASE_URL-flip-pending caveat and matches #40 `completed` in `PROGRESS.md`. ## Progress Log - 2026-05-17 07:39 — `3d1e32d6` — add pgbouncer container to docker-compose (transaction pool mode, no host port) - 2026-05-17 07:43 — `b7c4f90c` — configure infra/pgbouncer/pgbouncer.ini with transaction-mode defaults + userlist.txt.template - 2026-05-17 07:45 — `fe8809b6` — route Prisma Migrate through DIRECT_URL via prisma.config.ts (schema.prisma `directUrl` not supported on Prisma 7 — see Deviations) - 2026-05-17 07:48 — `2bee026c` — update .env.example, .env.production.example, packages/config/src/catalog.ts to document DATABASE_URL (pgbouncer:6432) + DIRECT_URL (postgres:5432) - 2026-05-17 07:50 — `4147d4ef` — add docs/ops/pgbouncer.md runbook (Coolify deploy, tuning, troubleshooting, rollback) - 2026-05-17 07:52 — `5e26da4e` — add docker-compose.staging.yml overlay (Postgres+pgbouncer+app depends_on wiring) - 2026-05-17 07:55 — `8eec215b` — add scripts/db/check-direct-url.sh + wire into prisma:migrate:deploy - 2026-05-18 00:48 UTC — staging-deploy — `edoburu/pgbouncer:latest` container `boilerplate-pgbouncer` brought up on `/opt/pgbouncer/` via `docker compose up -d`, attached to the `coolify` network so apps can resolve it as `boilerplate-pgbouncer:6432`. `pgbouncer.ini` points `boilerplate_validation` + `boilerplate` databases at `rs3pdxczfhmxuqyx3k0uy2co:5432`. `userlist.txt` populated from `pg_authid.rolpassword` (SCRAM-SHA-256). Smoke green: `psql -h boilerplate-pgbouncer -p 6432 -U boilerplate -d boilerplate_validation -c "SELECT 1"` returned `1` row from inside the `coolify` network. The old `nc`-based healthcheck note is superseded by the current `pg_isready` healthcheck in `docker-compose.yml` and `docs/ops/pgbouncer.md`. - 2026-05-27 — docs/status reconciliation — A4 verifies the app env flip is live: web/api/worker `DATABASE_URL` goes through PgBouncer and `DIRECT_URL` goes direct to Postgres. The previous pending-operator note is superseded. ## Lessons Learned _(Optional, am Ende des Tasks für nachfolgende Tasks)_