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,306 @@
# Read-Write-Split via Prisma $extends
**Status:** in_progress (code-complete; read-replica deferred by operator; single-DB fallback live)
**Task-ID:** #41
**Phase:** 03
**Estimated Effort:** 1 Woche
**Owner:** unassigned
## Problem
Sämtliche Prisma-Queries (auch reine Read-Loaders für Dashboards, KB-Public-Seiten, Analytics, Listings) gehen heute gegen den Primary-Postgres. Das Primary ist gleichzeitig Write-Target — bei einem Bulk-Write (Import von 10k CRM-Records) verlangsamen sich parallele Reads spürbar. Mit dem PgBouncer-Setup aus #40 ist das Connection-Limit zwar entschärft, aber Disk-I/O und CPU-Last bleiben auf einer Maschine.
Postgres unterstützt Streaming-Replication out of the box. Eine Read-Replica entlastet den Primary für alle Read-Only-Workloads. Voraussetzung: die Application muss bewusst entscheiden, ob eine Query an Replica (eventually consistent, Lag bis ~1s) oder Primary (strikt aktuell) geht.
Aktuelle Hot-Read-Pfade (Stichproben):
- `apps/web/app/modules/crm/db/*.db.server.ts` — List-Queries (Contacts, Companies, Deals)
- `apps/web/app/modules/knowledgeBase/db/*.db.server.ts` — Public KB-Routes (hohe Lese-Last, kein Konsistenz-Bedarf)
- `apps/web/app/modules/analytics/*` — Dashboard-Loaders (aggregierte Reports, oft minutenlang gecached)
- `apps/web/app/routes/app.$tenant/dashboard.tsx` — Loader pro Page-Load
- `apps/web/app/utils/data/.server/appData.ts` — Read-Side (Tenant-Lookups, Member-Listings)
- `apps/web/app/modules/sites/*` und `apps/web/app/modules/portals/*` — Public-Facing Loaders (Marketing-Sites, Customer-Portals)
Klassische Write-Pfade müssen explizit Primary nutzen: Mutations, Session-Writes, Stripe-Webhook-Updates, Outbox-Writes (siehe #42).
## Depends on
- `03-scaling-infrastructure/pgbouncer.md` — `DIRECT_URL`-Konvention und Pool-Setup ist Voraussetzung; Read-Replica läuft optional auch über eigenen PgBouncer
- `02-observability/metrics-grafana.md` — Read/Write-Verteilung wird über Prisma-Middleware-Counter erfasst und in Grafana visualisiert
## Blocks
- `03-scaling-infrastructure/outbox-pattern.md` — Outbox-Writes müssen explizit Primary nutzen, Konvention wird hier etabliert
- `03-scaling-infrastructure/tenant-snapshot.md` — Snapshot-Reads können von Replica kommen, Restore-Writes Primary
- `04-search-rag/embedding-pipeline.md` — Indexer liest große Mengen — gut für Replica
- alle nachfolgenden Read-Heavy-Features
## Approach
**Zwei Prisma-Clients hinter sauberem Interface.**
1. **`packages/db/src/client.ts` zentral umbauen:**
```ts
const writeUrl = env.DATABASE_URL;
const readUrl = env.DATABASE_READ_URL ?? writeUrl; // Fallback
const prismaWrite = new PrismaClient({ datasources: { db: { url: writeUrl } } });
const prismaRead = readUrl === writeUrl
? prismaWrite // Same instance, no double connection
: new PrismaClient({ datasources: { db: { url: readUrl } } });
export const prisma = prismaWrite.$extends({
name: 'rw-split',
client: {
get write() { return prismaWrite; },
get read() { return prismaRead; },
},
});
```
2. **Konvention:** `prisma.write.user.findUnique(...)` für strikte Konsistenz, `prisma.read.user.findUnique(...)` für eventually-consistent.
3. **Migration der Hot-Read-Pfade** (siehe Liste oben) explizit pro Funktion auf `prisma.read` umstellen. **Kein Default-Routing** — wir wollen bewusste Entscheidung pro Call.
4. **Telemetry:** Prisma-Middleware zählt pro Client (write vs read), exposed via OpenTelemetry-Counter `prisma.queries.total{client="read|write"}`. Grafana-Dashboard zeigt Verteilung.
5. **Fallback-Logik:** Wenn `DATABASE_READ_URL` nicht gesetzt ist → Read-Client = Write-Client, keine Replication-Nutzung. So bleibt Code-Konvention auch in Dev ohne Replica funktional.
6. **Test-Setup:**
- In CI gegen Single-DB (read = write Fallback) → kein Replica-Mock nötig, alle Tests grün bleiben
- Optional Integration-Test gegen Replica via testcontainers (Postgres-Primary + Postgres-Standby mit Streaming-Replication)
**Warum dieses Pattern:**
- Prisma `$extends` ist offizieller Mechanismus, type-safe, keine Magic
- Explizite Auswahl pro Call statt Auto-Routing (z.B. nach Operation-Type) — Auto-Routing macht Konsistenz-Bugs schwer auffindbar
- Fallback-Konstruktion: Code bleibt funktional auch ohne Replica (Dev/Self-Hosted-Setups ohne Replica-Setup)
**Warum nicht Alternativen:**
- ❌ Prisma-Middleware mit Auto-Routing nach Operation-Type: Bricht „read-after-write" in einer Request-Lifecycle (z.B. nach `create` direkt `findUnique` auf Replica → Race)
- ❌ Separate Module pro DB-Access (read-models package): zu viel Doppelung, schwer zu maintainen
- ❌ Externe Library wie prisma-replicas: Maintenance unsicher, wir haben nur einen Use-Case
## Implementation Steps
1. **Two-Client-Setup in packages/db**
- Files: `packages/db/src/client.ts`, `packages/db/src/client.test.ts`
- Implementierung wie oben skizziert, mit Fallback wenn READ_URL nicht gesetzt
- Type-Test: `prisma.read.user.findFirst()` und `prisma.write.user.findFirst()` beide typed
- Tests: Fallback-Verhalten, Singleton-Pattern, Beide-Clients-Different bei gesetzter READ_URL
- Commit: `03-scaling/rw-split: add prisma write/read clients with fallback`
2. **Env-Var-Schema erweitern**
- Files: `packages/config/src/env-schema.ts` (oder analog), `.env.example`, `.env.production.example`
- `DATABASE_READ_URL` als optional, Zod-Schema
- Comment: „Optional Postgres Read-Replica URL. Wenn leer, fallen alle Reads auf Primary zurück (DATABASE_URL)."
- Validation: wenn gesetzt, muss valides postgres:// URL sein
- Commit: `03-scaling/rw-split: add DATABASE_READ_URL to env catalogue`
3. **Telemetry-Middleware**
- Files: `packages/db/src/telemetry.ts`, `telemetry.test.ts`
- Prisma-Middleware (`$use`) registriert pro Client-Instance, zählt Queries (counter), Duration (histogram), labels mit `model`, `operation`, `client`
- Integration mit OpenTelemetry-Metrics aus Phase 02
- Tests: Counter incrementiert korrekt, Labels gesetzt
- Commit: `03-scaling/rw-split: add prisma telemetry middleware for read/write split observability`
4. **Migration: apps/web/app/modules/crm/db/*.db.server.ts**
- Files: alle List-Query-Funktionen in `apps/web/app/modules/crm/db/`
- Pro Funktion: wenn Read-Only (z.B. `getContacts`, `getCompanies`, `getDealsForBoard`) → `prisma.read`. Mutations bleiben `prisma.write` (oder default-`prisma` weil das = `prisma.write`)
- Pro Funktion bewusster Choice — Subagent dokumentiert Entscheidung pro Funktion in Commit-Message
- Tests: bestehende Tests laufen weiter; Single-DB-Fallback macht keinen Unterschied
- Commit: `03-scaling/rw-split: route crm list queries to read replica`
5. **Migration: apps/web/app/modules/knowledgeBase/db/*.db.server.ts**
- Files: KB-DB-Files
- Public-KB-Routes haben höchste Read-Last, beste Migration-Candidate
- Mutations (KB-Editor) bleiben Write
- Commit: `03-scaling/rw-split: route knowledge base public reads to replica`
6. **Migration: apps/web/app/modules/analytics/***
- Files: alle Analytics-Loader
- Aggregations + Reports sind Read-Only, oft langsame Queries → ideal für Replica
- Commit: `03-scaling/rw-split: route analytics dashboard queries to read replica`
7. **Migration: apps/web/app/routes/app.$tenant/dashboard.tsx**
- Files: Dashboard-Route + verlinkter Loader-Code
- Dashboard-Loader pure Read → `prisma.read`
- Commit: `03-scaling/rw-split: route tenant dashboard loader to read replica`
8. **Migration: apps/web/app/utils/data/.server/appData.ts**
- Files: `appData.ts` (Read-Side)
- Tenant/Member-Lookups sind Read-Only — Subscription-Cache (#38) cached oben drauf
- **Vorsicht:** wenn nach Login direkt `getUserAndTenants` aufgerufen wird, hat Replica evtl. den frisch erstellten User noch nicht (Replication-Lag). Für Auth-Pfade weiterhin `prisma.write` nutzen, dokumentieren
- Commit: `03-scaling/rw-split: route appdata read side to replica with auth path exception`
9. **Migration: apps/web/app/modules/sites/* + portals/***
- Files: alle Site/Portal-Loaders
- Public-Facing, hohe Last, Read-Only → `prisma.read`
- Commit: `03-scaling/rw-split: route public sites and portals to read replica`
10. **Telemetry-Verifikation + Grafana-Dashboard**
- Files: `infra/monitoring/grafana-dashboards/prisma-rw-split.json`
- Panels: Total Queries pro Client, Latency-P95 pro Client, Queries pro Model+Operation
- Doku-Update: `docs/observability/redis-stores.md` ergänzen um „wir beobachten read/write-split via Grafana"
- Commit: `03-scaling/rw-split: add grafana dashboard for read/write split observability`
11. **Doku**
- Files: `docs/database/read-replicas.md`
- Sections:
- **Setup:** wie Postgres-Streaming-Replication aufgesetzt wird (`primary_conninfo`, `hot_standby = on`)
- **Coolify/Hetzner-Setup:** zwei Postgres-Container, eines als Standby, `pg_basebackup`-Init
- **Fly.io:** managed Postgres-Replicas
- **Konvention:** „Use read for X, write for Y" — Tabelle:
- **Use `prisma.read` für:** Listings, Dashboards, Public-Pages, Reports, Search-Result-Display
- **Use `prisma.write` für:** Mutations, Auth-Pfade (Login/Session), Stripe-Webhook-Reads-die-Writes-vorangehen, Outbox-Reads im Dispatcher
- **Replication-Lag-Considerations:** typisch < 1s, aber Burst-Writes können Lag auf 5-10s pushen. Read-after-write nicht garantiert auf Replica
- **Monitoring:** `pg_stat_replication` auf Primary; `pg_last_xact_replay_timestamp()` auf Replica
- **Failover:** Manuell (Coolify-Restart von Standby zu Primary); automatisch via Patroni/repmgr (out of scope für jetzt)
- Commit: `03-scaling/rw-split: add read replicas documentation with usage guidelines`
12. **Integration-Test (optional, gated)**
- Files: `packages/db/src/__integration__/rw-split.test.ts`
- testcontainers mit Postgres-Primary + Postgres-Standby (Streaming-Replication)
- Tests: Write auf Primary → Read auf Replica nach 100ms (mit kleinem Sleep, lebensnah)
- Gated über `TEST_REPLICA=1`-Env-Var (nicht in default-CI weil Replica-Setup teuer)
- Commit: `03-scaling/rw-split: add optional integration test with replicated postgres`
## Test Requirements
- **Unit-Tests:** `client.ts` Fallback-Logik (READ_URL gesetzt vs nicht); Telemetry-Middleware Counter
- **Integration-Tests:** Bestehende CI-Suite läuft weiter (Single-DB-Fallback macht keinen Unterschied); optionaler Replica-Test gated über Env-Var
- **E2E-Tests:** keine neuen, bestehende E2E müssen grün bleiben
- **Manual-Test:** auf Staging mit Replica: read-Query auf Replica, write-Query auf Primary, verify via `pg_stat_activity`
- **Coverage-Target:** keine Regression; `client.ts` + `telemetry.ts` ≥ 90 %
- **Test-Files:** `packages/db/src/client.test.ts`, `packages/db/src/telemetry.test.ts`, `packages/db/src/__integration__/rw-split.test.ts`
**NICHT als completed markieren bevor:**
- Bestehende Tests alle grün
- Migration-Subagent hat pro Funktion in Commit-Message dokumentiert WARUM read oder write gewählt wurde
- Staging-Test (mit Replica) zeigt: > 60 % der Dashboard-Reads gehen an Replica (Grafana-Panel)
## Acceptance Criteria
- [ ] `packages/db/src/client.ts` exportiert `prisma` mit `.write` und `.read` Accessors via `$extends`
- [ ] Fallback funktioniert: ohne `DATABASE_READ_URL` ist `prisma.read === prisma.write`
- [ ] Env-Schema kennt `DATABASE_READ_URL` als optional, dokumentiert
- [ ] Telemetry-Middleware aktiv auf beiden Clients, OpenTelemetry-Metrics live
- [ ] Alle 6 genannten Hot-Path-Module nutzen `prisma.read` für reine Read-Queries
- [ ] Auth-Pfade in `appData.ts` bleiben bewusst auf `prisma.write` (read-after-write Garantie)
- [ ] Grafana-Dashboard `prisma-rw-split.json` exists und visualisiert die Verteilung
- [ ] Staging-Verifikation: Read-Replica-Container hochgezogen, > 60 % Dashboard-Reads landen auf Replica
- [ ] `docs/database/read-replicas.md` enthält Setup, Konvention, Tabelle „Use read for X, write for Y", Lag-Considerations
- [ ] Bestehende Test-Suite grün (Single-DB-Fallback in CI)
- [ ] Optional: Integration-Test mit replizierten Postgres-Containern (gated, läuft in nightly-Job)
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
- [ ] Detail-MD Progress Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
**Pro Modul-Migration separat rollback-bar:** `git revert <migration-commit>` → Modul fällt zurück auf `prisma.write` (= Primary). Kein Datenverlust, kein DB-Schema-Change.
**Global-Disable:** `DATABASE_READ_URL` unsetzen + App-Restart → Read-Client = Write-Client. Replica wird ignoriert, alles geht an Primary. Keine Code-Änderung nötig.
**Replica-down-Szenario:** Wenn Replica ausfällt:
- Prisma-Read-Client wirft Connection-Error
- Sentry-Alert
- Manuell `DATABASE_READ_URL` auf Primary umstellen + Restart → läuft weiter (degraded Performance)
- Future: Auto-Fallback in `client.ts` (mit Circuit-Breaker) — out of scope für jetzt
**DB-Schema:** keine Migrations in diesem Task.
## Security Notes
- **Read-Replica-Credentials:** separater User mit READ-ONLY-Rechten auf Replica (`GRANT SELECT ON ALL TABLES IN SCHEMA public TO read_user`). Selbst wenn `prisma.read` versehentlich für Write genutzt wird → Postgres rejected
- **Connection-String-Handling:** `DATABASE_READ_URL` darf nie geloggt werden (Passwort)
- **Replication-Slot-Security:** Streaming-Replication-User braucht REPLICATION-Recht, das ist sensibel. Separater `replicator`-User, nur von Replica-IP erlaubt
- **Cross-Tenant-Data-Leak via Replica-Lag:** wenn Tenant-Switch direkt nach Write erfolgt und Loader auf Replica liest, könnte alte Tenant-ID-Daten gelesen werden. Mitigation: Auth-Pfade strikt `prisma.write`. Code-Review check
- **PII-Considerations:** Replica hat full data copy. Backup-/Snapshot-Policy für Replica gleich strikt wie Primary
- **DSGVO:** wenn EU-Customer-Data: Replica im selben Land hosten. Hetzner-Falkenstein für Primary, Hetzner-Helsinki für Replica wäre OK (beide EU)
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit `packages/db/src/client.ts` als Input + Prisma-`$extends`-Docs — soll Type-Safety prüfen
- **Research:** `Explore`-Subagent für „Liste alle Prisma-Aufrufe in `apps/web/app/modules/`, kategorisiere als Read-Only vs Write" — Output ist Migration-Backlog für Steps 4-9
- **Implementation:**
- `general-purpose` für Step 1-3 (Foundation: Client + Env + Telemetry)
- Ein eigener `general-purpose` pro Migration-Step (4-9), weil pro Modul Tradeoffs überlegt werden müssen — der Subagent muss pro Funktion Read/Write begründen
- `general-purpose` für Step 11 (Doku, umfangreich)
- **Tests:** Separater `general-purpose` für Integration-Test mit testcontainers + Streaming-Replication (Step 12)
- **Verification:** `gsd-verifier` für Acceptance-Criteria; Grafana-Panel-Check als manueller Final-Verify
- **Code-Review:** `gsd-code-reviewer` für alle Migration-Commits — Read/Write-Choices reviewen, Auth-Pfad-Ausnahmen prüfen
## Staging-Deployment-Steps
1. Branch `agent/03-rw-split` pushen, schrittweise Commits 1-12
2. Coolify-Setup für Postgres-Replica:
- Neuen Coolify-Service `postgres-replica` mit Image `postgres:16-alpine`
- Custom-Init-Script in `infra/postgres/init-replica.sh`:
```bash
# On replica container start
until pg_basebackup -h postgres -D /var/lib/postgresql/data -U replicator -P -R; do
sleep 5
done
```
- Replica-Postgres-Conf in `infra/postgres/postgresql.replica.conf`:
```
hot_standby = on
primary_conninfo = 'host=postgres port=5432 user=replicator password=...'
```
- Primary-Postgres-Conf in `infra/postgres/postgresql.conf`:
```
wal_level = replica
max_wal_senders = 3
wal_keep_size = 256MB
```
- User auf Primary anlegen: `CREATE USER replicator WITH REPLICATION ENCRYPTED PASSWORD '...';`
3. App-Env-Vars in Coolify setzen: `DATABASE_READ_URL=postgresql://read_user:pass@postgres-replica:5432/toolctrl?connection_limit=10`
4. Deploy via Coolify
5. Smoke-Tests:
- **Replication-Test:** `psql -h postgres-replica -U read_user -c "SELECT pg_last_xact_replay_timestamp()"` → erwarte aktuelle Timestamp
- **Read-Routing-Test:** Login als Test-User, öffne Dashboard, parallel `pg_stat_activity` auf Replica → erwarte aktive Queries
- **Write-Path-Test:** Tenant-Settings ändern, parallel `pg_stat_activity` auf Primary → erwarte aktive Write-Queries (NICHT auf Replica)
- **Grafana-Verifikation:** Dashboard `prisma-rw-split` zeigt Verteilung; Read-Counter steigt schneller als Write-Counter nach 5 min Browsing
6. Last-Test (k6):
```sh
k6 run --vus 100 --duration 10m scripts/k6/dashboard-load.js
```
- Während Test: Primary-CPU vs Replica-CPU vergleichen
- Acceptance: Replica-CPU > 30 %, Primary-CPU spürbar entlastet
7. Replication-Lag-Test:
- `pg_basebackup` parallel zu Last-Test → check ob Lag unter 5s bleibt
- Bei höherem Lag: `wal_buffers` und `synchronous_commit` tunen
8. Failover-Drill (optional):
- Manuell auf Replica `pg_promote()` → wird zu neuem Primary
- Coolify-Env umstellen, App neu deployen
- Doku-Procedure in `docs/database/read-replicas.md` step-by-step
## Deviations from Plan
- 2026-05-17 — Telemetry middleware uses `$extends({ query })` (Prisma 7) instead of the deprecated `$use(...)` API the spec sketched. The injected recorder is metrics-SDK-agnostic so the existing `@toolctrl/metrics` prom-client wiring and a future OTel `Meter` both work without touching `packages/db`.
- 2026-05-17 — `appData.ts` was **not** migrated wholesale. The spec already calls this out as risky (auth-path read-after-write). Only the secondary admin tenant-enumeration helpers it depends on (`adminGetAllActiveTenantSimple`, `adminGetAllTenantsIdsAndNames`) moved to `dbRead`. The user / current-tenant / role resolution remains on the write client by design.
- 2026-05-17 — CRM has no `apps/web/app/modules/crm/db/*.db.server.ts` files (the module lives in `services/`). The single direct `db.user.findMany({})` in `CrmService.loadFromUsers` was migrated; the rest of CRM goes through `~/utils/db/entities/*.db.server` which is shared infrastructure and was left untouched.
- 2026-05-17 — Replica provisioning (`postgres-replica` Coolify service, `wal_level=replica`, `pg_basebackup` init) is operator-owned; the task ships code-complete and stays `in_progress` until staging deploys the replica and Grafana verifies `> 60 %` dashboard reads land on it.
- 2026-05-27 — Status reconciliation against `PROGRESS.md` and
`OPERATOR-CHECKLIST.md`: read-replica provisioning is intentionally
deferred, not an active A-bucket operator item. With `DATABASE_READ_URL`
unset, `dbRead === db` keeps the single-primary path live and correct.
Do not document #41 as completed until a real read replica is provisioned
and the Grafana `> 60 %` dashboard-read verification has evidence.
## Progress Log
- 2026-05-17 — a3eb0722 — refactor prisma client to expose getReadDbClient / getWriteDbClient / getExtendedDbClient with DATABASE_READ_URL fallback (10 tests pass).
- 2026-05-17 — dc2b57dc — add `@toolctrl/db/telemetry.server` (attachPrismaTelemetry + 5 unit tests) wrapping clients via `$extends({ query })` with an injectable recorder.
- 2026-05-17 — 50f47fe1 — env catalog + .env.example + .env.production.example entries for DATABASE_READ_URL with fallback notes.
- 2026-05-17 — e74567cc — apps/web/app/utils/db.server.ts exports `dbRead`; CrmService.loadFromUsers migrated.
- 2026-05-17 — 4da6faf4 — knowledgeBase: 5 db.server files migrated (kbArticles, kbCategories, kbCategorySections, kbAnalytics counts, knowledgeBase) — public reads on replica, mutations + read-then-write analytics helpers on primary.
- 2026-05-17 — a83c30f8 — analytics: groupUniqueVisitorsBy moved to dbRead.
- 2026-05-17 — fc6ed8ae — apps/web/app/utils/db/tenants.db.server.ts: admin tenant-listings on dbRead, auth-path reads stay on db.
- 2026-05-17 — aad650b9 — sites + portals: read-only listings on dbRead, getSiteByTypeAndSiteId stays on db (API auth), portal mutations stay on db.
- 2026-05-17 — f676511f — docs/architecture/rw-split.md (conventions, lag hazard, rollback, replica setup, migration recipe).
## Lessons Learned
- Prisma 7 dropped `$use` middleware; `$extends({ query: { $allModels: { $allOperations } } })` is the new path and works cleanly for query-counter telemetry without losing model/operation metadata.
- The `$extends` return type for `getExtendedDbClient()` is not assignable to plain `PrismaClient`, so keeping `getDbClient()` returning the un-extended write client preserves backwards compatibility with the dozens of existing call-sites that rely on `DbClient` typing (api-keys, queue-failed-jobs, idempotency, etc.).
- Single-DB fallback (`DATABASE_READ_URL` unset → `dbRead === db`) made every migration commit a zero-risk roll-out: CI single-DB tests stay green, replica is purely an optimisation that lights up when the env var flips.