Zum Inhalt

ADR-010: Prisma-Migrationen als führendes Deploymentverfahren

Stand: 09.08.2026 15:22 Branch: main Status: Akzeptiert

Datum, Uhrzeit Version Änderung Autor
09.08.2026 15:22 1.2 Initiale Prisma-v4-Migration, getrennte PostgreSQL-Schutzmigration und automatisierte statische Prüfung nachgeführt Codex
09.08.2026 14:24 1.1 Akzeptierte providerneutrale RLS-Strategie gemäss ADR-012 als Migrationsgrundlage verknüpft Codex
09.08.2026 14:07 1.0 Prisma-Migrationen mit kontrollierten PostgreSQL-Ergänzungen als führendes Deploymentverfahren festgelegt Codex

Kontext

Zu Beginn des Entscheids existierten keine Prisma-Migrationen unter backend/prisma/migrations. Stattdessen lagen mehrere manuelle Gesamt-, Delta- und Einzelskripte unter database/. Diese Dateien bilden unterschiedliche historische Stände ab, widersprechen teilweise dem gemäss ADR-009 führenden Prisma-Schema und wurden zeitweise durch prisma db push oder direkte Ausführung ergänzt. Inzwischen bilden die eingecheckte Initialmigration und die nachgelagerte PostgreSQL-Schutzmigration den ersten umgesetzten Stand dieses Entscheids.

UC00 benötigt zusätzlich PostgreSQL-Funktionen, die nicht vollständig in der Prisma Schema Language ausdrückbar sind, insbesondere Row-Level Security (RLS, zeilenbasierte Zugriffskontrolle), Rollen, Grants, Trigger und möglicherweise Erweiterungen. Ein führendes Verfahren muss deshalb Prisma-Modelle und kontrolliertes ergänzendes SQL gemeinsam versionieren können.

Geprüfte Varianten

Variante A: Manuelle SQL-Gesamt- und Deltascripts

Das Deployment verwendet schema-final.sql für neue Datenbanken und separat gepflegte Deltas für bestehende Datenbanken. PostgreSQL-Funktionen sind vollständig ausdrückbar, aber Prisma-Schema, Gesamtschema und Deltafolge können unabhängig auseinanderlaufen.

Variante B: prisma db push

Das Prisma-Schema wird direkt auf die Zielumgebung übertragen. Das ist für kurzlebige Prototypen einfach, erzeugt aber keine versionierte Migrationshistorie und eignet sich nicht als kontrollierter Weg für gemeinsam genutzte Test-, Staging- oder Produktionsdatenbanken.

Variante C: Prisma Migrate mit überprüften SQL-Ergänzungen

prisma migrate dev --create-only erzeugt eine Migration, deren SQL vor Anwendung geprüft und bei Bedarf um Datenmigrationen und PostgreSQL-Funktionen ergänzt wird. Test-, Staging- und Produktionsumgebungen verwenden ausschliesslich die eingecheckte Migrationsfolge mit prisma migrate deploy.

Variante D: Externes Migrationswerkzeug neben Prisma

Ein separates Werkzeug verwaltet alle Migrationen. Dies ist möglich, führt für V1 aber zusätzliche Abhängigkeiten und eine zweite Werkzeugkette ein, ohne dass dafür ein nachgewiesener Bedarf besteht.

Entscheidung

Variante C wird akzeptiert: Die versionierte Migrationsfolge unter backend/prisma/migrations/ ist das führende Deploymentverfahren.

Es gelten folgende Regeln:

  1. Änderungen der Prisma-Anwendungsmodelle beginnen im gemäss ADR-009 führenden backend/prisma/schema.prisma.
  2. Eine neue Migration wird in der Entwicklung zunächst mit prisma migrate dev --create-only erzeugt.
  3. Das erzeugte migration.sql wird vor Anwendung auf Datenverlust, Sperren, Laufzeit, Rückfüllung, Indizes, Constraints, Reihenfolge und Wiederholbarkeit geprüft.
  4. Erforderliche Datenmigrationen sowie PostgreSQL-Ergänzungen wie RLS-Policies, Rollen, Grants, Trigger, Funktionen und Erweiterungen werden in derselben versionierten Migrationsfolge als kontrolliertes SQL ergänzt.
  5. Erst die geprüfte Migration wird mit prisma migrate dev gegen eine kontrollierte Entwicklungsdatenbank angewendet.
  6. Test-, Staging- und Produktionsumgebungen verwenden ausschliesslich prisma migrate deploy aus einer automatisierten Deployment-Pipeline. Das Kommando wird nicht durch lokal umgebogene Produktionszugangsdaten ausgeführt.
  7. prisma db push ist nur für eine ausdrücklich kurzlebige persönliche Prototypdatenbank ohne schützenswerte oder gemeinsam genutzte Daten zulässig. Für die gemeinsame Entwicklungsdatenbank, Tests, Staging und Produktion ist es nicht zulässig.
  8. prisma db pull dient ausschliesslich der Diagnose und Driftanalyse. Änderungen werden nach Prüfung bewusst in Schema und Migration zurückgeführt.
  9. Direkte manuelle Änderungen an gemeinsam genutzten Datenbanken sind unzulässig. Ein zwingender Notfall-Hotfix wird dokumentiert, auditiert und unverzüglich durch eine neue Migration sowie einen Driftabgleich in das Repository zurückgeführt.
  10. Bereits angewendete Migrationen werden nicht nachträglich verändert. Korrekturen erfolgen durch neue vorwärtsgerichtete Migrationen.
  11. database/schema-final.sql, schema-migrate.sql, schema-migrate-uc00.sql und die übrigen verändernden Einzelskripte sind historische Quellen und dürfen nicht mehr als Deploymentweg ausgeführt werden.
  12. database/schema-analysis.sql bleibt bis zur Ablösung ein manuell geprüftes Diagnosewerkzeug ohne Schreiboperationen und ohne Führungsrolle.

Einführung bei bestehender Entwicklungsdatenbank

Vor der ersten Migration wird der tatsächliche Entwicklungsdatenbankstand read-only inventarisiert und gegen Prisma-Ausgangsbasis sowie historische SQL-Dateien geprüft.

Da Entwicklungs-, Test- und Demo-Umgebungen gemäss UC00 ausschliesslich synthetische Daten enthalten dürfen, ist für V1 folgender Weg bevorzugt:

  1. UC00-Zielschema fachlich und technisch freigeben;
  2. initiale Migration mit prisma migrate diff --from-empty --to-schema ... --script erzeugen;
  3. erforderliche Erweiterungen, Trigger und nach ADR-012 beschlossene RLS-Objekte ergänzen;
  4. Migration vollständig prüfen;
  5. gemeinsame Entwicklungsdatenbank kontrolliert zurücksetzen und aus Migrationen neu aufbauen;
  6. Seed mit ausschliesslich synthetischen Daten ausführen;
  7. Schema, Drift, Build, Integration und Tenant-Isolation prüfen.

Sollten entgegen dieser Vorgabe erhaltenswerte Daten vorhanden sein, ist vor jedem Reset anzuhalten. Dann sind Backup, Ist-Soll-Abgleich und ein dokumentiertes Baselining mit prisma migrate resolve --applied erforderlich.

Verbindliche Prüfgates

Eine Migration darf erst veröffentlicht oder angewendet werden, wenn mindestens folgende Prüfungen erfolgreich sind:

  • prisma validate und prisma generate;
  • Backend-Build unmittelbar nach der Client-Erzeugung;
  • Review des vollständigen Migrations-SQLs;
  • Kennzeichnung jeder löschenden oder irreversiblen Operation;
  • Datenrückfüllung vor NOT NULL- oder Constraint-Verschärfung;
  • Prüfung auf lange Tabellensperren und erforderliche gestufte Einführung;
  • Neuaufbau einer leeren Testdatenbank aus der vollständigen Migrationsfolge;
  • Upgrade-Test von einem unterstützten vorherigen Stand;
  • Seed- und Integrationstests;
  • RLS-, Rollen- und Tenant-Isolationstests für sicherheitsrelevante Tabellen;
  • dokumentierter Backup- und Wiederherstellungsweg vor produktiven destruktiven Änderungen;
  • prisma migrate status und zusätzlicher Driftabgleich nach Deployment.

prisma migrate deploy allein erkennt nicht jede ausserhalb der Migrationshistorie entstandene Drift. Der zusätzliche Driftabgleich bleibt deshalb ein eigenes Deployment-Gate.

Konsequenzen

  • Die vorhandenen SQL-Dateien bleiben zur Nachvollziehbarkeit erhalten, werden aber als historisch oder diagnostisch gekennzeichnet.
  • Die initiale Migrationsfolge wurde aus dem freigegebenen UC00-Zielschema erzeugt; kein veraltetes Gesamtschema wurde als Baseline übernommen.
  • RLS und andere PostgreSQL-Spezialfunktionen werden nicht in einer unabhängigen Nebenablage gepflegt, sondern in versionierten Migrationen.
  • Produktionsänderungen werden automatisierbar, prüfbar und umgebungsübergreifend reproduzierbar.
  • Rollback bedeutet grundsätzlich Korrektur durch eine neue Vorwärtsmigration oder Wiederherstellung aus einem geprüften Backup; angewendete Migrationen werden nicht umgeschrieben.

Umsetzungsstand

Teil Status
Führendes Deploymentverfahren Akzeptiert
Bestehende SQL-Dateien klassifiziert Umgesetzt
NPM-Skripte für Create, Deploy und Status Umgesetzt
Initiale Prisma-Migration Erstellt und statisch geprüft; Ausführung gegen eine leere PostgreSQL-Testdatenbank offen
PostgreSQL-Ergänzung für Constraints, Rollen und RLS Erstellt und statisch geprüft; Laufzeit- und Isolationstest offen
Automatisierte statische Migrationsprüfung Umgesetzt mit npm run prisma:migrations:validate
Entwicklungsdatenbank-Inventar und Resetfreigabe Offen
Automatisierte Deployment-Pipeline Offen
Drift-, Upgrade- und Wiederherstellungstests Offen

Quellen

Verknüpfte Dokumente