304 lines
20 KiB
Markdown
304 lines
20 KiB
Markdown
# 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)_
|