Zum Inhalt

ADR-009: Prisma-Schema als technische Wahrheit

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

Datum, Uhrzeit Version Änderung Autor
09.08.2026 15:22 1.2 UC00-Zielschema und statisch geprüfte Migrationsfolge als umgesetzte Folgeschritte nachgeführt Codex
09.08.2026 14:24 1.1 Providerneutrale RLS-Strategie gemäss ADR-012 als ergänzenden technischen Nachweis verknüpft Codex
09.08.2026 14:01 1.0 Prisma-Schema als technische Schemadefinition mit klaren Grenzen zu Fachmodell, Migration und Datenbankstand festgelegt Codex

Kontext

Im Repository existieren mehrere Darstellungen des Datenbankschemas: backend/prisma/schema.prisma, manuelle SQL-Dateien, Datenbankdokumentation, historische Schema-Abgleiche und ein zeitweise mit db pull oder db push veränderter Entwicklungsdatenbankstand. Frühere Unterlagen bezeichneten unterschiedliche Stände gleichzeitig als Prisma v2, v3 oder v4. Dadurch waren technische Fertigmeldungen nicht reproduzierbar.

Die Fachregeln für UC00 sind inzwischen umfangreicher als die eingecheckte Prisma-Ausgangsbasis. Die Festlegung einer technischen Wahrheit darf deshalb nicht fälschlich bedeuten, dass der aktuelle Schemastand fachlich vollständig, migriert oder produktionsbereit ist.

Geprüfte Varianten

Variante A: Tatsächliche Datenbank als technische Wahrheit

Das Schema wird mit prisma db pull aus einer Entwicklungs- oder Produktionsdatenbank abgeleitet. Dies bildet den jeweiligen Ist-Stand ab, macht aber nicht nachvollziehbar, ob er fachlich beabsichtigt, vollständig migriert oder zwischen Umgebungen identisch ist.

Variante B: Manuelle SQL-Gesamtschemas als technische Wahrheit

Dateien wie database/schema-final.sql definieren das Gesamtschema. Dies kann PostgreSQL-Funktionen vollständig ausdrücken, erzeugt neben Prisma aber eine zweite Modellquelle und erhöht das Risiko auseinanderlaufender Tabellen, Enums, Relationen und Client-Typen.

Variante C: Prisma-Schema als technische Schemadefinition

Das eingecheckte backend/prisma/schema.prisma ist die führende technische Definition der durch Prisma verwalteten Anwendungsmodelle. Versionierte Migrationen bilden die kontrollierte Änderungshistorie; der tatsächliche Datenbankstand ist ein zu prüfender Deploymentzustand. Fachregeln und akzeptierte Architekturentscheidungen bleiben vorgelagerte Quellen.

Variante D: Gleichberechtigte Mehrfachquellen

Prisma, SQL-Gesamtschema und Datenbank dürfen unabhängig verändert werden. Diese Variante ist flexibel, verhindert aber keine Drift und erlaubt keine eindeutige Konfliktauflösung.

Entscheidung

Variante C wird akzeptiert: backend/prisma/schema.prisma ist die technische Wahrheit der durch Prisma verwalteten Anwendungsmodelle.

Dabei gelten verbindlich folgende Grenzen:

  1. Fachliche Regeln und akzeptierte Architecture Decision Records (ADRs, Architekturentscheidungsprotokolle) bestimmen, was das Zielmodell leisten muss. Ein abweichendes Prisma-Schema ändert keine Fachregel.
  2. Das Prisma-Schema definiert Modelle, Felder, Enums, Relationen, Schlüssel, Indizes und Prisma-seitig ausdrückbare Datenbankabbildungen des eingecheckten Zielstands.
  3. Der generierte Prisma Client ist ein abgeleitetes Build-Artefakt. Er darf nicht als eigenständige Quelle verwendet werden und muss vor jedem Build neu aus dem eingecheckten Schema erzeugbar sein.
  4. Versionierte Migrationen dokumentieren und deployen Änderungen. Ihre führende Rolle und der Umgang mit nicht durch Prisma ausdrückbaren PostgreSQL-Objekten werden in ADR-010 festgelegt.
  5. Der tatsächliche Stand einer Entwicklungs-, Test- oder Produktionsdatenbank ist ein Deploymentzustand. Er gilt nur nach Migration-, Drift- und Funktionsprüfung als mit dem Repositorystand übereinstimmend.
  6. prisma db pull ist ein Diagnose- und Abgleichswerkzeug. Es darf die eingecheckte Schemadefinition nicht ungeprüft überschreiben.
  7. Manuelle SQL-Gesamtschemas, Diagramme, Tabellenlisten und Datenbankdokumentationen sind abgeleitet oder historisch. Sie dürfen keine widersprechende zweite Schemadefinition bilden.
  8. PostgreSQL-Funktionen ausserhalb des Prisma-Schemamodells, insbesondere Row-Level Security (RLS, zeilenbasierte Zugriffskontrolle), Rollen, Grants, Trigger und bestimmte Erweiterungen, benötigen versionierte technische Artefakte und eigene Nachweise. Sie heben die Prisma-Führungsrolle für Anwendungsmodelle nicht auf.
  9. Versionsnamen wie „Prisma v2“, „Prisma v3“ oder „Prisma v4“ werden nur für ausdrücklich abgenommene Stände verwendet. Bis zur Zielmodellabnahme gilt „Prisma-Ausgangsbasis“.

Verbindlicher Änderungsfluss

Eine modellrelevante Änderung erfolgt in dieser Reihenfolge:

  1. führende Fachregel oder akzeptierten Architekturentscheid identifizieren;
  2. Auswirkung in der UC-Nachverfolgbarkeit und Abschlusscheckliste erfassen;
  3. Prisma-Schema ändern;
  4. Migration gemäss ADR-010 erzeugen und prüfen;
  5. Prisma-Syntax validieren und Client neu erzeugen;
  6. Backend unmittelbar danach bauen;
  7. Migration gegen eine kontrollierte Entwicklungsdatenbank anwenden und Drift prüfen;
  8. Seed, automatisierte Tests und erforderliche Sicherheitsprüfungen ausführen;
  9. abgeleitete Datenbankdokumentation und Statusangaben nachführen.

Ein erfolgreicher prisma validate-Lauf allein bestätigt weder fachliche Vollständigkeit noch Migration, Laufzeitverhalten oder Produktionsbereitschaft.

Konsequenzen

  • Die aktuelle Prisma-Ausgangsbasis bleibt technische Wahrheit des eingecheckten Ist-Stands, obwohl sie das UC00-Zielmodell noch nicht vollständig abbildet.
  • Der nach prisma generate fehlschlagende Backend-Build ist ein echter Konsistenzfehler und wird nicht durch einen älteren generierten Client verdeckt.
  • Bestehende historische SQL-Dateien sind gemäss ADR-010 kein führender Deploymentweg.
  • Datenbankdokumentation wird erst nach Freigabe des Zielschemas aus den führenden technischen Artefakten nachgeführt.
  • Schemaänderungen direkt in einer Datenbank sind ohne Rückführung in Schema, Migration, Tests und Dokumentation nicht abgeschlossen.
  • Bereits veröffentlichte Migrationen dürfen nicht nachträglich verändert werden; Korrekturen erfolgen durch neue Migrationen.

Umsetzungsstand

Teil Status
Führungsrolle des Prisma-Schemas Akzeptiert
Nachverfolgbarkeitsmatrix UC00 Umgesetzt
Reproduzierbare Prüfung von Ausgangsschema und Client Umgesetzt
Reproduzierbarer Backend-Build nach Client-Erzeugung Blockiert; acht Fehler offen
ADR-010 zum Deploymentverfahren Akzeptiert und mit initialer Migrationsfolge begonnen
ADR-012 zur RLS-Strategie Akzeptiert; Migration statisch umgesetzt, Laufzeitnachweise offen
UC00-Zielschema, Migration und Seed Zielschema und Migrationsfolge statisch geprüft; Datenbank-Rollout und Seed offen
Abgeleitete Datenbankdokumentation Offen

Verknüpfte Dokumente