20 KiB
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_URLzeigt auf PgBouncer (für Queries),DIRECT_URLzeigt direkt auf Postgres (für Migrations). Prismaschema.prismadeklariert 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 wird03-scaling-infrastructure/backup-cli.md—pg_dumpmuss 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
-
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
- Files:
-
pgbouncer.ini mit Tuning-Defaults
- Files:
infra/pgbouncer/pgbouncer.ini - Komplette Konfiguration mit Comments:
[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
- Files:
-
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
- Files:
-
Prisma-Migrate URL-Routing — Current shipped implementation routes migrations through
prisma.config.ts, notschema.prisma directUrl; Prisma 7 rejectsurl/directUrlin schema. Runtime PrismaClient readsDATABASE_URL, while migrate/db push/db pull/db seed useDIRECT_URLwith fallback toDATABASE_URL.- Files:
prisma.config.ts,scripts/db/check-direct-url.sh - Commit:
03-scaling/pgbouncer: route Prisma migrate through DIRECT_URL
- Files:
-
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=10reduziert 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
- Files:
-
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
- Files:
-
Application-Update: Prisma-Clients verifizieren
- Files:
packages/db/src/client.ts, alle App-Boot-Files - Sicherstellen dass
DATABASE_URLaus Env genutzt wird (sollte schon sein); kein Hardcoded-Direct-URL irgendwo - Boot-Time-Validation: bei fehlendem
DIRECT_URLin 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
- Files:
-
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_sizeberechnen (Faustregel:max_connections / N_app_instances), wann aufstatement_modewechseln (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
- Files:
-
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=truemussEXECUTEfallback aufEXECUTE_NOWgreifen) - Concurrency-Test: 50 parallele Queries, alle erfolgreich
- Commit:
03-scaling/pgbouncer: add testcontainers integration suite
- Files:
-
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 devgegen 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 unterscripts/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: PgBouncercl_active < 25,cl_waiting = 0, keinetoo many clients-Errors
Acceptance Criteria
- PgBouncer-Container in
docker-compose.yml+docker-compose.staging.ymldefiniert infra/pgbouncer/pgbouncer.inimit dokumentierten Tuning-Defaultsuserlist.txtwird zur Boot-Zeit aus Env-Vars generiert (SCRAM-SHA-256)packages/db/prisma/schema.prismadeklariertdirectUrl.env.example+.env.production.exampleenthalten beide URLs mit Comments- Boot-Time-Validation in allen Apps: fehlende
DIRECT_URLin 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 STATSzeigtcl_active < default_pool_size,cl_waiting = 0unter normaler Last docs/database/connection-pooling.mdenthält alle 4 Sections (Coolify/Fly/Docker/Tuning)pnpm prisma migrate devfunktioniert lokal (gegen DIRECT_URL)pnpm lint,pnpm typecheck,pnpm testgrü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, keinpgbouncer=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_sizerauf,pool_modeaufsession(wenn Prepared-Statement-Probleme),reserve_pool_sizerauf- Bei
transaction-Mode-Crash mit fremden Postgres-Features: temporärsession-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
md5oderplainauth (md5 ist deprecated und unsicher) - Admin-User getrennt:
pgb_adminundpgb_statsseparat von App-User; Stats-User darf nur READ auf virtualpgbouncer-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-Modeignore_startup_parameters: wir whitelist nurextra_float_digitsundsearch_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 +xrahmen) - Audit: PgBouncer-Logs auf
failed login,closed: socket errormonitoren — Anzeichen für Brute-Force oder Misconfig - Postgres
max_connections: auf min.default_pool_size × N_databases × 1.5setzen (für Admin-Zugriff + Headroom)
Subagent Recommendations
- Planning:
Plan-Subagent mit Prisma-Docs-Ausschnitt zu „PgBouncer + connection_limit + pgbouncer=true" + bestehenderdocker-compose.ymlals Input - Research:
Explore-Subagent für „suche nachDATABASE_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-purposefür Steps 1-3 (Container + Config + userlist)general-purposefür Steps 4-5 (Prisma-Schema + Env)general-purposefür Steps 6-7 (Health + App-Validation)general-purposefür Step 8 (Doku, weil umfangreich)
- Tests: Separater
general-purposefür Integration-Test (Step 9) — testcontainers-Setup ist nicht trivial - Verification:
gsd-verifier+ manueller k6-Last-Test auf Staging - Code-Review:
gsd-code-reviewermit Fokus auf Env-Var-Konvention und Security-Notes-Items
Staging-Deployment-Steps
- Branch
agent/03-pgbouncerpushen - Coolify-Setup vorab:
- Postgres-Container hat schon
max_connections=200(defensive für Pool-Setup) - Coolify-Service
pgbouncerneu anlegen mit Imageedoburu/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)
- Postgres-Container hat schon
- App-Env-Vars umstellen (Coolify):
DATABASE_URL=postgresql://app_user:pass@pgbouncer:6432/toolctrl?pgbouncer=true&connection_limit=10DIRECT_URL=postgresql://app_user:pass@postgres:5432/toolctrl?connection_limit=5(neu)
- Coolify-Auto-Deploy triggert Rebuild aller Apps mit neuen Env-Vars
- 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"→ erwartetotal_xact_count > 0 - Pool-Usage:
SHOW POOLS→ erwartecl_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"
- Connection-Test:
- Last-Test (k6):
k6 run --vus 50 --duration 5m scripts/k6/api-me-load.js- Während Test parallel
SHOW STATSalle 30s - Acceptance:
cl_waiting = 0, keinetoo many connections-Fehler in API-Logs
- Während Test parallel
- Grafana-Dashboard live ansehen: Pool-Usage-Graph zeigt Sägezahn (typisches Pool-Pattern),
Server Connection Countstabil unterdefault_pool_size - Bei Issues:
docker logs pgbouncer | grep -E '(WARNING|ERROR|FATAL)'für Misconfig-Hinweise
Deviations from Plan
- Prisma 7 dropped
urlanddirectUrlfromschema.prisma. Thevalidatecommand on Prisma 7.8 rejects both properties (P1012). The plan's step 4 prescribed addingurl = env("DATABASE_URL")anddirectUrl = env("DIRECT_URL")to the datasource block. We instead routeDIRECT_URLthroughprisma.config.ts(datasource.url = env("DIRECT_URL" || "DATABASE_URL")). Migrate now uses the unpooled URL while the PrismaClient at runtime continues to readDATABASE_URLfromprocess.env. Documented indocs/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 ofpg_authid.rolpassword, since Postgres 16 stores the hash in the correct format whenpassword_encryption=scram-sha-256. Avoids duplicating the SCRAM derivation logic in shell. - 2026-05-27 status reconciliation:
docs/improvement-plan/OPERATOR-CHECKLIST.mdA4 verifies web/api/worker now use the PgBouncerDATABASE_URLand keepDIRECT_URLpointed at raw Postgres. This supersedes the stale app-DATABASE_URL-flip-pending caveat and matches #40completedinPROGRESS.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.prismadirectUrlnot 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:latestcontainerboilerplate-pgbouncerbrought up on/opt/pgbouncer/viadocker compose up -d, attached to thecoolifynetwork so apps can resolve it asboilerplate-pgbouncer:6432.pgbouncer.inipointsboilerplate_validation+boilerplatedatabases atrs3pdxczfhmxuqyx3k0uy2co:5432.userlist.txtpopulated frompg_authid.rolpassword(SCRAM-SHA-256). Smoke green:psql -h boilerplate-pgbouncer -p 6432 -U boilerplate -d boilerplate_validation -c "SELECT 1"returned1row from inside thecoolifynetwork. The oldnc-based healthcheck note is superseded by the currentpg_isreadyhealthcheck indocker-compose.ymlanddocs/ops/pgbouncer.md. - 2026-05-27 — docs/status reconciliation — A4 verifies the app env flip is live: web/api/worker
DATABASE_URLgoes through PgBouncer andDIRECT_URLgoes direct to Postgres. The previous pending-operator note is superseded.
Lessons Learned
(Optional, am Ende des Tasks für nachfolgende Tasks)