11 KiB
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
- Eine einzelne Baseline-Migration stellt den aktuellen Main-Datenbankzustand aus einer leeren PostgreSQL-16-Datenbank her.
- Prisma-Schema, RLS-Policies, Security-Definer-Funktionen, Grants, Extensions, Constraints und Indizes entsprechen katalogseitig dem Endzustand der bisherigen vollständigen Migrationskette.
- 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. - 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.
- 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. - Automatisierte Tests decken Fresh-DB, Legacy-Adoption, wiederholten No-op, partielle/abweichende Historie und den vollständigen Alt-vs.-Baseline-Katalogvergleich ab.
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.- 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 deployim 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 deployausfü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 SCHEMAist kein zulässiger Rollback.
Quellen
AGENTS.md§Prisma-Schema & Migrationen, §RLS, §Ticket-Treuedocs/AGENT-CHECKLIST.mddocs/deployment.md§One-shot-Migratordocs/security/RLS-HARDENING-2026-07-13.mdinfra/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 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 wurde mit
Merge-Commit ce748f10b nach main übernommen. Der exakt rebasierte PR-Head bfbae1b98 bestand CI-Run
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
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.