Ustalanie punktu odniesienia dla istniejącej bazy danych w Prisma bez uruchamiania migrate reset

Przy użyciu narzędzia Prisma Migrate z bazą danych, która już zawiera tabele i dane, istnieje duże prawdopodobieństwo, że pierwsze wywołanie npx prisma migrate dev zatrzyma się z ostrzeżeniem o niezgodnościach i zaproponuje sformatowanie całej bazy. To ostrzeżenie oznacza, że w bazie danych znajduje się struktura, o której historia migracji nic nie wie. Jeśli ją zaakceptujesz, twoje dane zostaną usunięte. Ten przewodnik wyjaśnia, dlaczego dochodzi do konfliktów, dlaczego sformatowanie prawie nigdy nie jest właściwym rozwiązaniem w przypadku ważnej bazy danych oraz jak ustalić bazę dla istniejącego schematu, aby Prisma traktowało go jako punkt wyjścia i stosowało zmiany tylko w jego oparciu.

Dlaczego Prisma wykrywa konflikt

Prisma Migrate przechowuje dwa zapisy dotyczące ewolucji Twojego schematu: pliki migracji w katalogu prisma/migrations oraz tabelę o nazwie _prisma_migrations w bazie danych, która wymienia pliki, które zostały zastosowane. Gdy uruchomisz polecenie migrate dev, Prisma odtwarza historię migracji w tymczasowej bazie danych i porównuje wynik z rzeczywistą bazą.

Jeśli rzeczywista baza danych już zawiera tabele, których nie stworzyła żadna migracja – na przykład dlatego, że została utworzona ręcznie, za pomocą innego narzędzia lub starszej wersji aplikacji – obie bazy się nie pokrywają. Prisma nazywa to odchyleniem. Ponieważ migrate dev jest poleceniem rozwojowym, jego domyślnym rozwiązaniem jest wyczyśczenie bazy danych i jej odbudowa na podstawie historii migracji, dlatego proponuje sformatowanie bazy. Jest to rozsądne w przypadku lokalnej bazy danych przeznaczonej do szybkiego użycia, ale destruktywne dla wszystkich innych przypadków.

Jeśli chcesz uzyskać więcej informacji na temat tego, w jaki sposób baza danych shadow bierze udział w tym porównaniu, zapoznaj się z bazą danych shadow Prismy i niezgodnościami w nazewnictwie.

Dlaczego migrate reset to niewłaściwe rozwiązanie

npx prisma migrate reset usuwa bazę danych lub każdą tabelę w jej schemacie, tworzy je na nowo na podstawie migracji i uruchamia skrypty seed. Wszystkie istniejące rekordy są tracione. W przypadku bazy danych zawierającej rzeczywistych użytkowników, zamówienia lub treści jest to nie rozwiązanie konfliktu, lecz utrata danych.

Lepszym podejściem jest pozostawienie bazy danych w spokoju i zaktualizowanie jej widoku świata przez Prismę. Robi się to poprzez zapisanie obecnej struktury jako pierwszej migracji i poinformowanie Prismy, że ta migracja już istnieje.

Krok po kroku tworzenie punktu odniesienia

Krok 1: Przegląd istniejącej bazy danych

Zainstaluj i uruchom npx prisma db pull. Prisma łączy się z bazą danych, odczytuje jej tabele, kolumny, indeksy i relacje, a następnie zapisuje odpowiadające im modele do pliku schema.prisma. Po tym kroku plik schematu opisuje bazę danych dokładnie taką, jaka jest.

Krok 2: Stworzenie migracji wyjściowej bez jej zastosowania

Stwórz folder dla punktu wyjścia, na przykład prisma/migrations/0_init. Przedrostek 0_ sprawia, że plik ten zostanie posortowany przed wszystkimi późniejszymi migracjami z datą. Następnie utwórz SQL, który stworzy obecny schemat od zera i zapisał go tam, używając polecenia npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql. W nowszych wersjach Prismy flaga docelowa może nazywać się --to-schema, dlatego sprawdź pomoc dla swojej wersji, używając polecenia npx prisma migrate diff --help.

Krok ten jest ważny, ponieważ tworzy plik migracji bez ingerencji w bazę danych. Powszechnym błędem jest uruchomienie w tym momencie polecenia npx prisma migrate dev --name baseline. W przypadku bazy danych, która już zawiera tabele i nie ma historii migracji, to polecenie wykrywa tę samą odchylkę co wcześniej i prosi o ponowne sformatowanie, co jest dokładnie tym, czego chcemy uniknąć. SQL bazowego stanu nigdy nie powinien być wykonywany na istniejącej bazie danych, ponieważ jej tabele już się tam znajdują.

Krok 3: Oznaczenie bazowego stanu jako zastosowanego

Uruchom polecenie npx prisma migrate resolve --applied 0_init. Argumentem jest nazwa folderu z migracjami. Jeśli folder został utworzony z datą i godziną, na przykład 20250101120000_baseline, musisz podać dokładną tę nazwę, a nie tylko baseline.

To polecenie nie wykonywa żadnych zapytań SQL na twoich tabelach. Wstawia wiersz do _prisma_migrations, w którym informuje się, że zastosowano bazę wyjściową. W praktyce edytujesz rejestrację zmian w Prismie, aby przyjąło ono obecną strukturę jako zamierzoną i ważną.

Jak to rozwiązuje konflikt

Przypomina to konflikt łączenia w Git: gdy twoja gałąź nie ma komitetów już obecnych na gałęzi main, aktualizujesz tę gałąź zamiast usuwać main. Tutaj baza danych jest bardziej zaawansowana, więc aktualizujesz historię Prismy tak, by odpowiadała jej stanowi.

Po zapisaniu bazy wyjściowej następne polecenie npx prisma migrate dev odtwarza operację 0_init w bazie cieniowej, uzyskuje taką samą strukturę jak w rzeczywistej bazie danych i nie wykrywa żadnych odchyleń. Od tego momentu, gdy zmienisz plik schema.prisma, Prisma generuje nową migrację zawierającą jedynie różnice i ją aplikuje.

Dlaczego to ma znaczenie dla dużych baz danych

Bazowanie na stanie początkowym przynosi największe korzyści, gdy baza danych przechowuje dużą ilość danych. Ponieważ stan początkowy jest zapisywany w pliku _prisma_migrations, a schemat odpowiada bazy danych w użyciu, Prisma pozostawia istniejące tabele i wiersze nietknięte i stosuje tylko nowe zmiany, dzięki czemu tabela users pozostaje nienaruszona.

Pamiętaj o kilku praktycznych kwestiach:

• Zastosuj polecenie migrate resolve --applied raz w każdym istniejącym środowisku, takim jak staging czy produkcja, ponieważ każda baza danych ma swój własny plik _prisma_migrations.
• W środowisku produkcyjnym stosuj późniejsze migracje za pomocą polecenia npx prisma migrate deploy, a nie migrate dev, które jest przeznaczone wyłącznie do celów rozwojowych.
• Zapisz folder z danymi stanu początkowego do systemu kontroli wersji, aby wszyscy programiści i zadania CI mieli ten sam punkt wyjścia.

Główne wnioski

• Ostrzeżenie o driftzie w istniejącej bazie danych oznacza, że brakuje historii migracji Prismy, a nie to, że baza danych jest błędna.
• Resetywanie usuwa dane; należy je traktować jako narzędzie przeznaczone wyłącznie do tymczasowych baz danych lokalnych.
• Ustalanie bazy odniesienia polega na analizie za pomocą db pull, generowaniu zapytań SQL przy użyciu migrate diff --from-empty oraz zapisywaniu ich za pomocą migrate resolve --applied.
• Nie używaj migrate dev do tworzenia bazy odniesienia w bazie danych już zawierającej dane, ponieważ wywołuje to to samo pytanie o reset.
• Po ustaleniu bazy odniesienia Prisma zarządza jedynie zmianami inkrementalnymi, a istniejące dane pozostają nietknięte.

Literatura pokrewna

• Shadow Database Prismy i niezgodność w nazewnictwie: instrukcja obsługi — Dlaczego prisma migrate dev prosi o sformatowanie bazy danych, jak skonfigurować bezpieczną bazę shadow oraz jak przekształcić zasady pisowni Prismy na format snake_case w Postgresie.
• Drizzle czy Prisma? Sprawdź typ połączenia i zapisany SQL przed podjęciem decyzji — Stwórz te same tabele użytkowników i faktur w Drizzle oraz Prisma, porównaj typy wyników połączeń i zapisany SQL, a także wykryj mapowania sterowników, które zamieniają wartości liczbowe na łańcuchy tekstowe.