107 lines
5.9 KiB
Markdown
107 lines
5.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|