Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,303 @@
# 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)_