トラブルシューティング

このガイドでは、開発環境でのPrisma Migrateに関する問題の解決方法について説明します。これには、多くの場合データベースのリセットが伴います。本番環境に特化したトラブルシューティングについては、以下を参照してください。

• 本番環境のトラブルシューティング
• 本番データベースのパッチ適用 / ホットフィックス

警告

このガイドは**MongoDBには適用されません**。
`migrate dev`の代わりに、`db push`がMongoDBで使用されます。

マイグレーション履歴の競合の処理

マイグレーション履歴の競合は、**ファイルシステムのマイグレーションフォルダ**と**データベース内の_prisma_migrationsテーブル**の間に不一致がある場合に発生します。

開発環境におけるマイグレーション履歴の競合の原因

• 既に適用されたマイグレーションが後で変更された場合
• 既に適用されたマイグレーションがファイルシステムから見つからない場合

開発環境では、フィーチャーブランチ間の切り替えによって履歴の競合が発生する可能性があります。これは、_prisma_migrationsテーブルにbranch-1からのマイグレーションが含まれており、branch-2に切り替えるとそれらのマイグレーションの一部が消える可能性があるためです。

注：開発環境と本番環境の間で不一致が生じる可能性があるため、意図的にマイグレーションを削除または編集してはなりません。

開発環境におけるマイグレーション履歴の競合の修正

prisma migrate devを実行したときにPrisma Migrateがマイグレーション履歴の競合を検出した場合、CLIはデータベースのリセットとマイグレーション履歴の再適用を要求します。

スキーマドリフト

データベーススキーマのドリフトは、データベーススキーマがマイグレーション履歴と同期していない、つまりデータベーススキーマが真実の情報源から「乖離」している場合に発生します。

開発環境におけるスキーマドリフトの原因

スキーマドリフトは、以下の場合に発生する可能性があります。

• マイグレーションを使用せずにデータベーススキーマが変更された場合 — 例えば、prisma db pushを使用したり、手動でデータベーススキーマを変更したりした場合。

注：スキーマドリフトを検出するにはシャドウデータベースが必要なため、これは開発環境でのみ行うことができます。

開発環境におけるスキーマドリフトの修正

データベースに手動で変更を加えたものの、それを保持したくない場合、またはPrismaスキーマで簡単に再現できる場合

1. データベースをリセットします。

   npx prisma migrate reset

2. Prismaスキーマで変更を再現し、新しいマイグレーションを生成します。

   npx prisma migrate dev

データベースに手動で変更を加え、それを保持したい場合は、以下を行うことができます。

1. データベースをイントロスペクトします。

   npx prisma db pull

   Prismaは、データベースで直接行われた変更でスキーマを更新します。

2. イントロスペクトされた変更をマイグレーション履歴に含めるための新しいマイグレーションを生成します。

   npx prisma migrate dev --name introspected_change

   Prisma Migrateはリセットを促し、その後、既存のすべてのマイグレーションと、イントロスペクトされた変更に基づく新しいマイグレーションを適用します。これにより、データベースとマイグレーション履歴が手動での変更を含めて同期されます。

失敗したマイグレーション

開発環境における失敗したマイグレーションの原因

マイグレーションは以下の場合に失敗する可能性があります。

• マイグレーションを実行する前に変更し、構文エラーを導入した場合
• 既にデータがあるテーブルに必須（NOT NULL）の列を追加した場合
• マイグレーションプロセスが予期せず停止した場合
• マイグレーションプロセスの途中でデータベースがシャットダウンした場合

_prisma_migrationsテーブル内の各マイグレーションには、エラーを保存するlogs列があります。

開発環境における失敗したマイグレーションの修正

開発者環境で失敗したマイグレーションを処理する最も簡単な方法は、根本原因に対処し、データベースをリセットすることです。例：

• データベースを手動で編集してSQL構文エラーを導入した場合は、失敗したmigration.sqlファイルを更新し、データベースをリセットします。

  prisma migrate reset

• データを持つデータベースに適用できないPrismaスキーマの変更を導入した場合（例：データを持つテーブルに必須の列を追加した場合）

  1. migration.sqlファイルを削除します。

  2. スキーマを変更します - 例えば、必須フィールドにデフォルト値を追加します。

  3. マイグレーションを実行します。

     prisma migrate dev

     Prisma Migrateはデータベースのリセットとすべてのマイグレーションの再適用を促します。

• 何らかの原因でマイグレーションプロセスが中断された場合は、データベースをリセットします。

  prisma migrate reset

Prisma MigrateとPgBouncer

接続プールにPgBouncerを使用している環境でPrisma Migrateコマンドを実行しようとすると、以下のエラーが表示される場合があります。

Error: undefined: Database error
Error querying the database: db error: ERROR: prepared statement "s0" already exists

詳細情報と回避策については、Prisma MigrateとPgBouncerの回避策を参照してください。