Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,106 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user