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

トラブルシューティング

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

警告

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

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

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

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

  • すでに適用されたマイグレーションが後で変更された場合
  • すでに適用されたマイグレーションがファイルシステムから欠落している場合

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

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

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

Prisma Migrateがprisma migrate devの実行時にマイグレーション履歴の競合を検出した場合、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の回避策を参照してください。