マイグレーションのスクワッシュ

このガイドでは、複数のマイグレーションファイルを単一のマイグレーションにスクワッシュする方法について説明します。

マイグレーションのスクワッシュについて

マイグレーションファイルの一部または全部を単一のマイグレーションにスクワッシュすることが役立つ場合があります。このガイドでは、これを行うことが望ましい2つのシナリオについて説明します

• 開発環境からクリーンに移行する：ローカルのマイグレーションをマージ前に1つにスクワッシュする
• 本番環境でクリーンな履歴を作成する：すべてのマイグレーションを単一のファイルにスクワッシュする

どちらの場合も、Prisma Migrateはこれを行うためのツールを提供します。migrate diffコマンドを使用して2つのデータベーススキーマを比較し、一方から他方への移行を単一のSQLファイルとして出力します。このガイドの残りの部分では、これら2つのシナリオでこれを実行する方法の詳細な手順を説明します。

開発環境からクリーンに移行する

マイグレーションのスクワッシュは、ブランチベースのワークフローで開発する際に役立ちます。フィーチャーブランチでの大規模なローカル開発作業中に、migrate devを使用して複数のマイグレーションを生成する場合があります。機能が完了した後、マイグレーション履歴には、mainブランチにプッシュされる最終的なマイグレーション履歴に不要な中間ステップが含まれる可能性があります。

本番環境で中間ステップの適用を避けるべき重要な理由があるかもしれません（データが失われたり、非常に遅く/破壊的になる可能性があります）。そうでない場合でも、本番環境のマイグレーション履歴の clutter を避けたい場合があります。

migrate devを使用してこれを実現する方法の詳細な手順については、「開発環境からクリーンに移行する方法」のセクションを参照してください。

本番環境でクリーンな履歴を作成する

マイグレーションのスクワッシュは、本番環境ですべてのマイグレーションファイルを1つにスクワッシュするためにも使用できます。これは、本番環境がより長いマイグレーション履歴を蓄積し、新しい環境でそれをリプレイすることが、余分な時間を必要とする中間ステップのために負担になっている場合に役立ちます。チームがマイグレーションステップから価値を引き出していない（そして、いざとなればバージョン管理履歴からそれらを取り戻すことができる）ため、履歴全体を単一のマイグレーションにスクワッシュするという決定がなされます。

migrate diffとmigrate resolveを使用してこれを実現する方法の詳細な手順については、「本番環境でクリーンな履歴を作成する方法」のセクションを参照してください。

マイグレーションをスクワッシュする際の考慮事項

警告

マイグレーションをスクワッシュする際、migration.sqlファイルに手動で変更または追加したSQLは保持されないことに注意してください。ビューやトリガーなどのカスタム追加を含むマイグレーションファイルがある場合は、マイグレーションをスクワッシュした後にそれらを再追加してください。

マイグレーションをスクワッシュする方法

このセクションでは、上記で説明した2つのシナリオでマイグレーションをスクワッシュする方法に関するステップバイステップの手順を提供します。

• 開発環境からクリーンに移行する
• 本番環境でクリーンな履歴を作成する

開発環境からクリーンに移行する方法

マイグレーションをスクワッシュする前に、次の開始条件を満たしていることを確認してください。

• スクワッシュされるマイグレーションの内容は、まだ本番データベースに適用されていません。
• 本番環境に適用されたすべてのマイグレーションは、すでにローカルのマイグレーション履歴の一部です。
• ブランチに追加した新しいマイグレーションファイルには、カスタムSQLはありません。

情報

フィーチャーブランチを作成した後に本番データベースのマイグレーション履歴が分岐した場合、最初に本番環境からのマイグレーション履歴とデータモデルの変更をローカル履歴にマージする必要があります。

次に、以下の手順に従ってください。

1. ローカルの./prisma/migrationsフォルダーの内容を、mainブランチのマイグレーション履歴と一致するようにリセットします。

2. 新しいマイグレーションを作成します。

   npx prisma migrate dev --name squashed_migrations

   これにより、単一のマイグレーションが作成され、次の状態に移行します。

   • リセットされたマイグレーション履歴で説明されているmainブランチの状態から
   • ./prisma/schema.prismaファイルで説明されているローカル機能の状態へ
   • そして、これをsquashed_migrationsで終わる新しいディレクトリ（--nameフラグで指定）の新しいmigration.sqlファイルに出力します。

この単一のマイグレーションファイルは、migrate deployを使用して本番環境に適用できるようになりました。

本番環境でクリーンな履歴を作成する方法

マイグレーションをスクワッシュする前に、次の開始条件を満たしていることを確認してください。

• マイグレーション履歴内のすべてのマイグレーションは、本番データベースに適用されています。
• データモデルはマイグレーション履歴と一致します。
• データモデルとマイグレーション履歴は同期しています。

次に、mainブランチまたは新しくチェックアウトされたブランチ（他の変更が加えられる前にmainにマージされるブランチ）で、次の手順に従ってください。

1. ./prisma/migrationsディレクトリのすべての内容を削除します。

2. ./prisma/migrationsディレクトリに新しい空のディレクトリを作成します。このガイドでは、これを000000000000_squashed_migrationsと呼びます。その中に、新しい空のmigration.sqlファイルを追加します。

   情報

   マイグレーションを000000000000_squashed_migrationsと名付け、先頭にゼロをすべて付けたのは、マイグレーションディレクトリで最初のマイグレーションにしたいからです。Migrateは、ディレクトリ内のマイグレーションを辞書式順（アルファベット順）に実行します。これが、migrate devを使用すると、日付と時刻をプレフィックスとしてマイグレーションを生成する理由です。マイグレーションには別の名前を付けることができますが、後のマイグレーションよりもソート順が低くなる限り、たとえば0_squashedや202207180000_squashedなどです。

3. 次の状態に移行する単一のマイグレーションを作成します。

   • 空のデータベースから
   • ./prisma/schema.prismaファイルで説明されている本番データベーススキーマの現在の状態へ
   • そして、これを上記で作成したmigration.sqlファイルに出力します。

   これは、migrate diffコマンドを使用して行うことができます。プロジェクトのルートディレクトリから、次のコマンドを実行します。

   npx prisma migrate diff \
    --from-empty \
    --to-schema-datamodel ./prisma/schema.prisma \
    --script > ./prisma/migrations/000000000000_squashed_migrations/migration.sql

4. このマイグレーションを本番環境に適用済みとしてマークし、そこで実行されないようにします。

   これは、migrate resolveコマンドを使用して、000000000000_squashed_migrationsディレクトリ内のマイグレーションをすでに適用済みとしてマークすることで行うことができます。

   npx prisma migrate resolve \
    --applied 000000000000_squashed_migrations

これで、本番環境に適用済みとしてマークされた単一のマイグレーションファイルが作成されます。新しいチェックアウトでは、本番データベーススキーマの状態に移行する単一のマイグレーションのみが取得されます。

本番データベースには、マイグレーションテーブルに適用されたマイグレーションの履歴がまだ含まれています。マイグレーションフォルダーとデータモデルの履歴も、ソース管理で引き続き利用できます。