Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/03-scaling-infrastructure/pgbouncer.md
T

20 KiB
Raw Blame History

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:
      [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):
    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)