メインコンテンツへスキップ

マイグレーション履歴について

このページでは、Prisma ORMがスキーマへの変更を追跡するためにマイグレーション履歴をどのように使用するかを説明します。

マイグレーション履歴​

マイグレーション履歴は、データモデルへの変更の記録であり、以下によって表現されます。

  • 各マイグレーション用のサブフォルダーと`migration.sql`ファイルを含む`prisma/migrations`フォルダー

    migrations/
      └─ 20210313140442_init/
        └─ migration.sql
      └─ 20210313140442_added_job_title/
        └─ migration.sql

    `migrations`フォルダーは、データモデルの履歴における**信頼できる情報源**です。

  • データベース内の`_prisma_migrations`テーブル。これは以下をチェックするために使用されます。

    • マイグレーションがデータベースに対して実行されたかどうか
    • 適用されたマイグレーションが削除されたかどうか
    • 適用されたマイグレーションが変更されたかどうか

    マイグレーションを変更または削除した場合（推奨されません）、次のステップは、開発環境にいるか（したがって`migrate dev`を使用しているか）、本番/テスト環境にいるか（したがって`migrate deploy`を使用しているか）によって異なります。

適用済みのマイグレーションを編集または削除しないでください​

一般的に、すでに適用されたマイグレーションを**編集または削除すべきではありません**。そうすると、開発環境と本番環境のマイグレーション履歴間に不整合が生じ、予期せぬ結果を招く可能性があります — たとえ、最初は変更によって何も壊れていないように見えてもです。

以下のシナリオは、一見無害に見える不整合を引き起こす変更をシミュレートしています。

  1. 開発環境で**すでに適用されている****既存のマイグレーション**を、`VARCHAR(550)`の値を`VARCHAR(560)`に変更して修正する
    ./prisma/migrations/20210310143435_default_value/migrations.sql
      -- AlterTable
     ALTER TABLE "Post" ALTER COLUMN "content" SET DATA TYPE VARCHAR(560);
    この変更を行った後、マイグレーション履歴の最終状態は、まだ`@db.VarChar(550)`を持つPrismaスキーマと一致しなくなります。
  2. `prisma migrate dev`を実行すると、マイグレーションが変更されたためにエラーが発生し、データベースのリセットが提案されます。
  3. `prisma migrate reset`を実行します — Prisma Migrateはデータベースをリセットし、編集したマイグレーションを含むすべてのマイグレーションを再実行します。
  4. 既存のすべてのマイグレーションを適用した後、Prisma Migrateはマイグレーション履歴の最終状態とPrismaスキーマを比較し、不一致を検出します。
    • Prismaスキーマには`@db.VarChar(550)`がある
    • データベーススキーマには`VARCHAR(560)`がある
  5. Prisma Migrateは、マイグレーション履歴の最終状態がPrismaスキーマと一致する必要があるため、値を`550`に戻す新しいマイグレーションを生成します。
  6. 今後、`prisma migrate deploy`を使用して本番環境とテスト環境にマイグレーションをデプロイする際、Prisma Migrateは常に、スキーマの最終状態が一致しているにもかかわらず、マイグレーション履歴が一致しないことを**警告します**（そして、コマンドを実行するたびに警告し続けます）。 
    6 migrations found in prisma/migrations
    WARNING The following migrations have been modified since they were applied:
    20210310143435_change_type

`migrate reset`後に何も壊れていないように見える変更でも問題を隠している可能性があります — 本番環境で再現できないバグが発生したり、その逆が発生したりする可能性があります — 特に変更が高度にカスタマイズされたマイグレーションに関するものである場合です。

Prisma Migrateがすでに適用されたマイグレーションの欠落または編集を報告した場合、リセットするのではなく、**根本原因**（ファイルを復元するか、変更を元に戻す）を修正することを推奨します。

マイグレーション履歴をソース管理にコミットする​

完全な`prisma/migrations`フォルダーをソース管理にコミットする必要があります。これには、プロバイダーの変更を試みたかどうかを検出するために使用される`prisma/migrations/migration_lock.toml`ファイルが含まれます。

`schema.prisma`ファイルをソース管理するだけでは不十分です — マイグレーション履歴を含める必要があります。これは以下の理由によるものです。

  • マイグレーションをカスタマイズし始めると、マイグレーション履歴には**Prismaスキーマでは表現できない情報**が含まれます。例えば、破壊的な変更によって引き起こされるデータ損失を軽減するためにマイグレーションをカスタマイズできます。
  • ステージング、テスト、本番環境にデプロイするために使用される`prisma migrate deploy`コマンドは、マイグレーションファイルのみを実行します。モデルを取得するためにPrismaスキーマを使用しません。
© . All rights reserved.