Einen Bestehenden Datenbank-Baseline in Prisma erstellen, ohne „migrate reset“ auszuführen

Point Prisma migriert in eine Datenbank, die bereits Tabellen und Daten enthält. Es ist sehr wahrscheinlich, dass der erste Befehl npx prisma migrate dev mit einem Warnhinweis wegen Strukturunterschieden abbricht und vorschlägt, alles zurückzusetzen. Dieser Hinweis signalisiert Prisma, dass die Datenbank eine Struktur aufweist, von der ihre Migrationshistorie nichts weiß. Wenn man diesen Vorschlag annimmt, werden die Daten gelöscht. Diese Anleitung erklärt, warum es zu Konflikten kommt, warum ein Zurücksetzen fast nie die richtige Lösung für eine wichtige Datenbank ist, und wie man das vorhandene Schema als Ausgangspunkt festlegt, sodass Prisma nur von dort an Änderungen vornimmt.

Warum Prisma einen Konflikt erkennt

Prisma Migrate bewahrt zwei Aufzeichnungen über die Entwicklung Ihres Schemas auf: die Migrationsspeicherdateien in prisma/migrations sowie eine Tabelle namens _prisma_migrations innerhalb der Datenbank, die auflistet, welche dieser Dateien bereits angewendet wurden. Wenn Sie migrate dev ausführen, wiedergibt Prisma die Migrationsgeschichte gegenüber einer temporären Schatten-Datenbank ab und vergleicht das Ergebnis mit der echten Datenbank.

Falls die echte Datenbank bereits Tabellen enthält, die durch keine Migration erstellt wurden – beispielsweise weil sie manuell erstellt wurde, mit einem anderen Tool oder durch eine frühere Version der Anwendung – stimmen die beiden Datenbanken nicht überein. Prisma bezeichnet dies als Abweichung. Da migrate dev ein Entwicklungscommand ist, besteht seine Standardlösung darin, die Datenbank zu löschen und sie aus der Migrationsgeschichte neu aufzubauen, weshalb es einen Neustart vorschlägt. Das ist für eine temporäre lokale Datenbank sinnvoll, doch zerstörerisch für alle anderen Fälle.

Für weitere Hintergrundinformationen dazu, wie die Schattendatenbank an diesem Vergleich teilnimmt, sehen Sie Prismas Schattendatenbank und Namensunterschiede.

Warum migrate reset die falsche Lösung ist

npx prisma migrate reset löscht die Datenbank oder jede Tabelle in ihrem Schema, erstellt sie neu anhand der Migrationsdateien und führt Seed-Skripte aus. Alle vorhandenen Zeilen gehen verloren. Bei einer Datenbank mit echten Benutzern, Bestellungen oder Inhalten handelt es sich dabei nicht um eine Konfliktlösung, sondern um Datenverlust.

Der bessere Ansatz ist es, die Datenbank unberührt zu lassen und stattdessen Prismas Sicht der Welt mit ihr auf den neuesten Stand zu bringen. Dazu speichern Sie die aktuelle Struktur als erste Migration und teilen Prisma mit, dass diese Migration bereits vorhanden ist.

Schritt für Schritt zur Erstellung einer Baseline

Schritt 1: Die vorhandene Datenbank analysieren

Führen Sie npx prisma db pull aus. Prisma verbindet sich mit der Datenbank, liest ihre Tabellen, Spalten, Indizes und Beziehungen sowie schreibt die entsprechenden Modelle in schema.prisma hin. Nach diesem Schritt beschreibt die Skriptdatei die Datenbank genau so, wie sie ist.

Schritt 2: Eine Basismigration erstellen, ohne sie anzuwenden

Erstellen Sie einen Ordner für die Baseline, zum Beispiel prisma/migrations/0_init. Das Präfix 0_ sorgt dafür, dass er vor allen späteren, mit einem Zeitstempel versehenen Migrationsdateien sortiert wird. Erstellen Sie anschließend die SQL-Anweisungen, mit denen das aktuelle Schema aus dem Nichts erstellt werden kann, und speichern Sie diese dort unter Verwendung von npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql. In neueren Prisma-Versionen kann der Ziel-Parameter stattdessen --to-schema heißen, daher prüfen Sie mit npx prisma migrate diff --help die Eigenschaften Ihrer Version.

Dieser Schritt ist wichtig, weil er die Migrationsdatei erstellt, ohne die Datenbank zu verändern. Ein häufiger Fehler besteht darin, zu diesem Zeitpunkt npx prisma migrate dev --name baseline auszuführen. Bei einer Datenbank, die bereits Tabellen enthält und keine Migrationshistorie besitzt, erkennt dieser Befehl denselben Abweichungsgrad wie zuvor und bittet erneut um Zurücksetzen – genau das, was man vermeiden möchte. Die Baseline-SQL sollte niemals auf der vorhandenen Datenbank ausgeführt werden, da deren Tabellen bereits existieren.

Schritt 3: Die Baseline als angewendet markieren

Führen Sie npx prisma migrate resolve --applied 0_init aus. Der Parameter ist der Name des Migrationsordners. Wenn ein Ordner mit einem Zeitstempel erstellt wurde, wie zum Beispiel 20250101120000_baseline, müssen Sie diesen vollständigen Namen übergeben, nicht nur baseline.

Diese Anweisung führt keine SQL-Anfragen an Ihre Tabellen aus. Sie fügt eine Zeile in _prisma_migrations ein, die angibt, dass die Baseline angewendet wurde. Im Grunde genommen ändern Sie Prismas Buchhaltungssystem, damit es die aktuelle Struktur als beabsichtigt und gültig betrachtet.

Wie dies den Konflikt löst

Es ähnelt einem Git-Merge-Konflikt: Wenn Ihre Branch keine Commits enthält, die bereits in main vorhanden sind, aktualisieren Sie die Branch anstelle dessen, main zu löschen. Hier ist die Datenbank weiter entwickelt, und Sie bringen Prismas Historie auf den neuesten Stand.

Nachdem die Baseline erfasst wurde, führt der nächste Aufruf von npx prisma migrate dev 0_init in der Schattendatenbank aus, erhält dieselbe Struktur wie die echte Datenbank und stellt keinen Abweichungen fest. Von da an erzeugt Prisma bei Änderungen von schema.prisma eine neue Migration, die nur den Unterschied enthält, und wendet diesen ausschließlich an.

Warum das für große Datenbanken wichtig ist

Die Erstellung einer Baseline lohnt sich am meisten, wenn die Datenbank viele Daten enthält. Da die Baseline in _prisma_migrations gespeichert wird und das Schema der aktiven Datenbank entspricht, lässt Prisma die vorhandenen Tabellen und Zeilen unberührt und wendet nur neue Änderungen an, sodass Ihre users-Tabelle unverändert bleibt.

Halten Sie einige praktische Punkte im Hinterkopf:

• Führen Sie einmal migrate resolve --applied in jeder vorhandenen Umgebung durch, wie z. B. im Staging- oder Produktivumfeld, da jede Datenbank ihre eigene _prisma_migrations-Tabelle hat.
• In der Produktivumgebung wenden Sie spätere Migrationsänderungen mit npx prisma migrate deploy an, nicht mit migrate dev, da diese ausschließlich für die Entwicklung bestimmt ist.
• Committen Sie den Baseline-Ordner in das Versionierungssystem, damit jeder Entwickler und jede CI-Aufgabe vom selben Ausgangspunkt ausgehen.

Kernpunkte

• Ein Abweichungswarnhinweis in einer vorhandenen Datenbank bedeutet, dass die Migrationsgeschichte von Prisma fehlt – nicht, dass die Datenbank falsch ist.
• Durch Zurücksetzen werden Daten gelöscht; betrachten Sie es daher nur als Werkzeug für einmalige lokale Datenbanken.
• Erstellen Sie eine Baseline, indem Sie mit db pull Informationen abrufen, mit migrate diff --from-empty SQL-Code generieren und diesen mit migrate resolve --applied aufzeichnen.
• Verwenden Sie migrate dev nicht, um eine Baseline für eine bereits befüllte Datenbank zu erstellen, da dies denselben Zurücksetzungsaufruf auslöst.
• Nach der Erstellung der Baseline verwaltet Prisma nur inkrementelle Änderungen, und die vorhandenen Daten bleiben unberührt.