# DB-BASELINE · Prisma-Migrationshistorie konsolidieren | | | |---|---| | **Typ** | Dev/Infra | | **Owner** | Raffael | | **Phase** | Querschnitt / Datenbankbetrieb | | **Cycle/Fenster** | Sofortiger Wartungsschnitt | | **Status** | Done | ## Abhängigkeiten & Parallelität - **Blocked by:** keine. Der vollständige Main-Migrationsstand muss vor dem Schnitt reproduzierbar und schema-paritätisch sein. - **Blocks:** keine fachlichen Tickets. Während des PRs gilt jedoch ein operativer Schema-Freeze; parallele Schema-Branches müssen nach dem Merge auf die Baseline rebasen und ihre Merge-Migration neu erzeugen. - **Plane-Prüfung:** Beide Richtungen wurden am 2026-07-22 gelesen. Es gibt keine bestehende `blocked-by`-/`blocks`-Relation für diesen Wartungsschnitt. - **Auswirkung auf Abhängige:** Keine Prisma-Modelle und keine Fachverträge ändern sich. Geändert werden ausschließlich die aktive Migrationshistorie, ihr Deploy-Cutover und die zugehörigen Verifikationsverträge. ## Was wir bauen Die historische Prisma-Migrationskette wird in eine einzelne, aus einer leeren PostgreSQL-Datenbank reproduzierbare HiveGrid-Baseline überführt. Die Baseline bildet nicht nur das deklarative Prisma-Schema ab, sondern auch alle PostgreSQL-spezifischen Laufzeitverträge wie RLS-Policies, Security-Definer-Funktionen, Rollen-Grants, Extensions, partielle Indizes und Constraints. Bestehende Datenbanken übernehmen die neue Baseline genau einmal über `prisma migrate resolve --applied`, nachdem ein fail-closed Check die vollständig angewendete Legacy-Historie einschließlich Checksums bestätigt hat. Frische Datenbanken dürfen die Baseline nicht überspringen und wenden sie regulär mit `prisma migrate deploy` an. ## Benötigte Screens Keine UI-Arbeit. ## Definition of Done - [x] Eine einzelne Baseline-Migration stellt den aktuellen Main-Datenbankzustand aus einer leeren PostgreSQL-16-Datenbank her. - [x] Prisma-Schema, RLS-Policies, Security-Definer-Funktionen, Grants, Extensions, Constraints und Indizes entsprechen katalogseitig dem Endzustand der bisherigen vollständigen Migrationskette. - [x] Ein versioniertes Legacy-Manifest erfasst alle ersetzten Migrationen mit SHA-256-Checksum; die aktive Legacy-Kette ist aus `prisma/migrations/` entfernt und bleibt über ein checksum-verifiziertes Audit-Archiv sowie Git rekonstruierbar. - [x] Der One-shot-Migrator übernimmt die Baseline nur bei einer vollständig erfolgreichen kanonischen Legacy-Historie oder bei Git-belegten historischen Checksums mit zusätzlicher Live-Schema-/Katalogparität; frische, bereits baselinierte, partielle oder unbekannt abweichende Datenbanken werden korrekt behandelt beziehungsweise fail-closed abgewiesen. - [x] Der bestehende Migrator-Rollen-, Secret- und Runtime-Env-Vertrag bleibt unverändert scharf; Staging und Produktion verwenden weiterhin den kurzlebigen `DIRECT_URL`-Migrator vor jedem Rollout. - [x] Automatisierte Tests decken Fresh-DB, Legacy-Adoption, wiederholten No-op, partielle/abweichende Historie und den vollständigen Alt-vs.-Baseline-Katalogvergleich ab. - [x] `prisma validate`, Migrations-Parity, Tenant-Policy-Contract, RLS-Release-Readiness, strikter RLS-Live-Test, Docker-/Deploy-Verträge sowie die allgemeine Commit-/Push-Checkliste sind grün. - [x] Rollback, Merge-Reihenfolge und der einmalige Staging-/Produktions-Cutover sind dokumentiert; PRs #215 und #218 sind nach gemeinsamem Sign-off mit grüner CI gemergt und die Staging-Adoption ist grün. **Fortschritt:** `DB-BASELINE`: 8/8 DoD = 100 % done. Offen: 0 Punkte. ## Technische Bausteine - `prisma/migrations/00000000000000_hivegrid_baseline/migration.sql` - Legacy-Migrationsmanifest unter `prisma/` - Fail-closed Adoption vor `prisma migrate deploy` im bestehenden One-shot-Migrator - Unit-Tests für die History-Klassifikation und den Prisma-CLI-Aufruf - Docker-basierter Alt-vs.-Baseline-Replay mit normalisiertem PostgreSQL-Katalogvergleich - Anpassung der RLS-Generator-/Freeze-Verträge auf die neue Baseline ## Rollback-Pfad - **Vor Merge:** Branch/PR verwerfen; produktive Datenbanken bleiben unverändert. - **Nach Merge, vor Baseline-Adoption:** Merge-Commit revertieren und die Legacy-Migrationsordner aus Git wiederherstellen. - **Nach erfolgreicher Adoption:** Keine DDL wird durch die Adoption ausgeführt. Bei einem Code-Rollback werden die Legacy-Migrationsordner wiederhergestellt; der zusätzliche erfolgreiche Baseline-Eintrag kann bestehen bleiben, solange kein Legacy-Image erneut `migrate deploy` ausführt. Der konkrete Rollback wird zuerst in Staging geprobt. - **Nach Anwendung auf einer frischen Datenbank:** Datenbank verwerfen und aus Backup/Seed neu aufbauen. Die Baseline ist forward-only; ein produktives `DROP SCHEMA` ist kein zulässiger Rollback. ## Quellen - `AGENTS.md` §Prisma-Schema & Migrationen, §RLS, §Ticket-Treue - `docs/AGENT-CHECKLIST.md` - `docs/deployment.md` §One-shot-Migrator - `docs/security/RLS-HARDENING-2026-07-13.md` - `infra/LESSONS.md` §9 - Prisma-Dokumentation: Baselining und Squashing migrations ## Umsetzungsnotiz 2026-07-22: Ticket als eigenständiger, fachmodell-neutraler Wartungsschnitt angelegt. Ausgangs-Pre-Flight auf `origin/main` ist grün (`pnpm typecheck`; `pnpm test`: 999 Testdateien, 7.135 Tests bestanden). Der aktuelle Main-Stand enthält 195 aktive Migrationen mit 42.140 SQL-Zeilen. Die Implementierung erfolgt isoliert auf `chore/prisma-baseline-20260722`. 2026-07-22: Die 195 Legacy-Migrationen wurden durch `00000000000000_hivegrid_baseline` ersetzt. Die Baseline enthält 293 Tabellen, 844 Policies, 92 Funktionen, 293 `ENABLE ROW LEVEL SECURITY`, 293 `FORCE ROW LEVEL SECURITY`, 2 Extensions sowie die migrations-eigenen SHK-Onboarding- und Customer-Portal-Feature-Flag-Referenzdaten. Baseline-SHA-256: `f39a3e6800356d3199b1274a492721217c12c0c5cafcf3f648b3050868c3abbe`. Das versionierte Audit-Archiv `prisma/baseline-legacy-migrations.tar.gz` hat SHA-256 `0571766bcd2bc7d4424706617ad9a495c2b11d6b3e8f9511510dc710716d6093`; sein Manifest pinnt alle 195 Migrationen einzeln. Proof: Fresh-DB-Deploy, checksum-verifizierte Legacy-Adoption, wiederholter No-op und der vollständige PostgreSQL-Katalog- und Referenzdatenvergleich sind grün. `prisma validate`, Migrations-Parity, Tenant-Policy-Contract (293/293), RLS-Release-Readiness (246/246), strikter RLS-Live-Test, Docker-Baseline (399 Checks), Docker-Non-Root, Deploy-/CI-/Source-/Doku-Verträge, Typecheck und Lint sind grün. Core-Tests: 1.001 Testdateien / 7.155 Tests bestanden; `@hivegrid/db`: 94 Testdateien / 854 Tests bestanden. Rollback, Merge-Reihenfolge und Cutover sind in `docs/ops/prisma-baseline.md` dokumentiert. Lokal sind 7/8 DoD erfüllt; offen bleibt ausschließlich PR plus grüne Remote-CI vor dem gemeinsamen Merge-Sign-off. 2026-07-22: PR [#215](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/215) gegen `main` ist eröffnet. Die Remote-CI für Implementierungs-Commit `66b1b1b68` ist mit 13/13 Checks grün, einschließlich Database Checks mit Baseline-Äquivalenz und Live-RLS sowie Docker Smoke, Typecheck/Tests, Coverage und Build/Bundle. Damit sind 8/8 DoD erfüllt. Der PR bleibt bis zum gemeinsamen Sign-off ungemergt. 2026-07-22: PR #215 wurde nach erneut grüner CI als Squash nach `main` gemergt. Der erste Staging-Deploy stoppte erwartungsgemäß vor `migrate resolve` und vor jeder Datenbankmutation, weil die bestehende Staging-Historie mindestens eine früher deployte, später im Git geänderte Migration mit ihrer damaligen Prüfsumme enthält. Der Hotfix auf `fix/prisma-baseline-staging-adoption-20260722` pinnt alle zehn im Git belegten historischen Prüfsummenvarianten samt Quellcommit. Eine solche Variante wird nur übernommen, wenn ein Live-`prisma migrate diff` keine Schemaabweichung findet und die zusätzlichen PostgreSQL- Katalogverträge für Audit-FKs, tenant-gebundenes Booking sowie Security-Definer-Owner/ACLs grün sind. Lokaler Proof des Hotfixes: Der vollständige Äquivalenzlauf spielte alle 195 Migrationen ein, simulierte alle acht betroffenen Migrationen mit den zehn historischen Ledger-Checksums und bestätigte danach Adoption, wiederholten No-op sowie vollständige Katalog- und Referenzdatenäquivalenz. Zusätzlich grün: `prisma validate`, Migrations-Parity, Tenant-Policy-Contract (293/293), RLS-Release-Readiness (246/246), strikter RLS-Live-Test, Docker-/Deploy-/CI-/Source-/Doku-Verträge, Typecheck, Lint sowie 1.017 Testdateien mit 7.341 bestandenen Tests. `DB-BASELINE`: 8/8 DoD = 100 % done; operativ offen ist nur der erneute Remote-CI- und Staging-Deploy-Nachweis vor dem Ticketabschluss. 2026-07-22: Im ersten Lauf von Hotfix-PR #218 stoppte ausschließlich der SHK-Migrationsfixture, weil der parallele Runner-Cold-Start von PostgreSQL das alte 30-Sekunden-Fenster überschritt; der Container war laut Runner-Log unmittelbar danach gesund. Der Fixture nutzt nun wie der benachbarte Identity-/Invite-Check einen auf 90 Sekunden begrenzten TCP-`pg_isready`-Probe. Der neue statische Vertragstest und der reale lokale SHK-Clean-/Legacy-Upgrade-Lauf (9/9 Tests) sind grün. Es gab keine Datenbank- oder Anwendungsänderung. 2026-07-22: Hotfix-PR [#218](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/218) wurde mit Merge-Commit `ce748f10b` nach `main` übernommen. Der exakt rebasierte PR-Head `bfbae1b98` bestand CI-Run [11057](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11057) mit 11/11 grünen Checks. Der erste Post-Merge-Lauf übernahm die Baseline auf Staging nach Prüfung von drei Git-belegten historischen Checksum-Varianten sowie Live-Schema- und sicherheitskritischer Katalogparität; anschließend meldete Prisma keine ausstehenden Migrationen. Ein nachgelagerter, transienter Controller-Pre-Stop-Health-Probe brach den Rollout sicher ab und stellte den vorherigen Release wieder her. Der idempotente Deploy-Re-Run [11058, Job 46077](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11058/jobs/46077) erkannte die bereits verbuchte Baseline, bestätigte erneut keine ausstehenden Migrationen und rollte alle Staging-Ressourcen einschließlich des revisionsgebundenen Portal-Domain-Controllers erfolgreich aus. `DB-BASELINE`: 8/8 DoD = 100 % done; 0 Punkte offen. 2026-07-23: Die erste Forward-Migration nach der konsolidierten Baseline (`kwp_project_inbound`) hat einen Reihenfolgefehler im One-shot-Migrator sichtbar gemacht: Ein Vergleich der bestehenden Legacy-Datenbank mit dem aktuellen Prisma-Schema muss die noch nicht angewandte Forward-Migration zwangsläufig als Drift melden. Der fail-closed Ablauf ist deshalb jetzt explizit `Rollen-Probe → Legacy-Historie und sicherheitskritische Varianten-Kataloge prüfen → Baseline übernehmen → prisma migrate deploy → aktuelles Live-Schema prüfen → Permission-Katalog synchronisieren`. Unbekannte Legacy-Checksums und abweichende sicherheitskritische Kataloge stoppen weiterhin vor jeder Adoption; eine Abweichung vom aktuellen Prisma-Schema stoppt nach den atomaren Forward-Migrationen und vor Permission-Sync beziehungsweise Rollout. Der vollständige Docker-Nachweis spielte alle 195 Legacy-Migrationen ein, simulierte die acht historischen Checksum-Varianten, adoptierte die Baseline, wandte `kwp_project_inbound` an und bestätigte anschließend `No difference detected`; Fresh-DB und Legacy-DB blieben vollständig katalogäquivalent. Die Änderung betrifft keine Prisma-Modelle oder Fachverträge. `DB-BASELINE`: 8/8 DoD = 100 % done; 0 Punkte offen.