HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/ops/prisma-baseline.md

Prisma-Baseline-Cutover

Seit dem Wartungsschnitt vom 2026-07-22 besteht die aktive Prisma-Historie aus 00000000000000_hivegrid_baseline. Die Baseline ersetzt 195 Migrationen bis 20260721160000_ak_p21_detach_guard_null_safety, ohne das Fachschema zu ändern. Die ersetzte Historie bleibt am Git-Commit 090e2558a6965e1c5804eb24d3eab5da8c8611a8 rekonstruierbar. Zusätzlich liegt sie für flache CI-Checkouts als checksum-geprüftes Audit-Archiv unter prisma/baseline-legacy-migrations.tar.gz; Prisma behandelt dieses Archiv nicht als aktive Migrationshistorie.

Laufzeitvertrag

• Frische Datenbanken haben noch keine Prisma-Historie. Der Adopter führt keine Schreibaktion aus; prisma migrate deploy wendet die Baseline normal an.
• Bestehende Datenbanken werden nur übernommen, wenn ihre erfolgreichen Legacy-Einträge entweder alle 195 Migrationen oder ein lückenloses Präfix dieser Kette bilden. Zulässig sind die kanonische SHA-256 oder eine der zehn im Manifest mit ihrem Git-Quellcommit belegten historischen SHA-256-Varianten. Ein exaktes Präfix wird ausschließlich über prisma migrate deploy aus dem checksum-geprüften Audit-Archiv auf die vollständige 195er-Kette vorwärts migriert. Lücken, fremde Namen, doppelte erfolgreiche Einträge und unbekannte Checksums bleiben harte Abbrüche. Bei einer historischen Variante werden vor der Baseline-Adoption zusätzlich Nullability/FK-Semantik, der tenant-gebundene Booking-Constraint sowie Owner und ACLs der betroffenen Security-Definer-Funktionen direkt im PostgreSQL-Katalog geprüft. Erst dann markiert prisma migrate resolve --applied die Baseline als angewendet. Die Baseline-DDL läuft dabei nicht. Nach dem regulären prisma migrate deploy muss ein prisma migrate diff die reale Datenbank gegen das aktuelle Prisma-Schema driftfrei bestätigen. Diese Reihenfolge erlaubt Forward-Migrationen nach der Baseline, ohne den noch nicht migrierten Legacy-Stand fälschlich gegen das bereits weiterentwickelte Schema zu vergleichen.
• Bereits baselinierte Datenbanken sind für die Adoption ein No-op. Fehlgeschlagene, lückenhafte, unbekannt checksum-abweichende, katalog-abweichende oder fremde Legacy-Historien brechen vor der Adoption ab. Scheitert eine Forward-Migration des exakten Präfixes, bleibt Primas eigener fehlgeschlagener Ledger-Eintrag sichtbar und jeder weitere Lauf stoppt fail-closed. Eine Abweichung vom aktuellen Prisma-Schema bricht nach den atomaren Forward-Migrationen und vor Permission-Sync beziehungsweise Rollout ab.
• Historie und Varianten-Katalog werden nach dem unveränderten Migrator-Rollen-Probe und vor prisma migrate deploy geprüft; die Prisma-Schema-Parität wird direkt danach im selben kurzlebigen start.sh migrate-Container geprüft. Nur dieser Prozess erhält DIRECT_URL; Runtime-Ressourcen erhalten sie nie.
• _prisma_migrations wird weder gelöscht noch umgeschrieben. Der zusätzliche Baseline-Eintrag ist der auditierbare Übergang zwischen alter und neuer Historie.

Einmaliger Merge- und Rollout-Ablauf

1. Während der PR offen ist, gilt Schema-Freeze. Parallele Schema-Branches werden nach dem Merge auf main rebased und erzeugen ihre Merge-Migration anschließend neu gegen die Baseline.
2. Vor dem Merge müssen Baseline-Äquivalenz, Migrations-Parity, der strikte RLS-Live-Test und die normalen Commit-/Push-Gates grün sein.
3. Der reguläre Main-Deploy baut zuerst das unveränderliche Image. Der Staging-One-shot-Migrator prüft die Rolle, vervollständigt bei Bedarf ein checksum-geprüftes Legacy-Präfix aus dem Audit-Archiv, übernimmt die vollständige Legacy-Historie, führt migrate deploy aus, prüft danach die aktuelle Schema-Parität und synchronisiert erst dann den Permission-Katalog.
4. Erst nach grünem Staging-Deploy und geprüftem Restore-Punkt wird derselbe Image-SHA über den bestehenden Promote-Ablauf nach Produktion gebracht. Der input-freie Production-Promote darf erst nach bestätigter Backup- oder Restore-Point-Bereitschaft gestartet werden; der manuelle Run ist die auditierte Operator-Bestätigung.
5. Der Produktions-One-shot-Migrator führt dieselbe fail-closed Adoption aus. Erst danach werden die Runtime-Ressourcen ausgerollt.

Keine manuelle migrate resolve-Ausführung ist Teil dieses Ablaufs. Wenn der Adopter stoppt, wird zuerst die gemeldete Historienabweichung untersucht; die Prisma-Tabelle wird nicht per SQL „repariert".

Verifikation

pnpm run verify:prisma-baseline
pnpm run verify:prisma-baseline-equivalence
pnpm exec prisma validate --config prisma.config.ts
pnpm run verify:migrations-parity
pnpm run verify:tenant-policy-contract
pnpm run verify:rls-release-readiness
HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live

Der Äquivalenztest entpackt die 195 Legacy-Dateien aus dem Audit-Archiv, prüft Archiv- und Einzeldatei-Checksums, spielt Legacy und Baseline in getrennte PostgreSQL-16- Datenbanken ein, simuliert alle acht Migrationen mit den zehn belegten historischen Ledger-Checksums, probt Adoption und wiederholten No-op und vergleicht Schema, RLS, Funktionen, ACLs, Extensions, Constraints, Indizes sowie die von Migrationen angelegten Referenzdaten.

Rollback

• Vor Merge: PR verwerfen. Es gab keine externe Datenbankmutation.
• Nach Merge, vor Adoption: Merge revertieren und die Legacy-Verzeichnisse aus Git wiederherstellen.
• Nach Adoption: Die Adoption hat keine DDL ausgeführt. Für einen Code-Rollback werden die Legacy-Dateien wiederhergestellt; ein altes Image darf jedoch nicht erneut migrate deploy ausführen, solange der zusätzliche Baseline- Eintrag nicht mit dem getesteten Rollback-Ablauf vereinbar ist.
• Bei einer frischen, nur aus der Baseline aufgebauten Wegwerf-Datenbank wird die Datenbank verworfen und neu erstellt. In Produktion wird niemals ein DROP SCHEMA als Rollback ausgeführt; dort gilt Restore-Punkt/Backup plus forward-only Korrekturmigration.