データベースマイグレーションエラー

CI/CDおよび本番デプロイでのPrismaマイグレーション失敗の解決方法。

データベースマイグレーションエラーとは

データベースマイグレーションエラーは、Prismaマイグレーションファイルに競合や問題があり、正常に実行できない場合に発生します。これらのエラーは通常、GitHub Actionsで以下の場面で表示されます：

  • Create Neon Branch — PRをプレビュー環境にデプロイする時
  • Apply Migrations to Neon Main — mainブランチにマージする時

主な原因：

  • 複数のPRからの重複したCREATE TABLE文
  • スキーマ定義の欠落や不整合
  • 新しいマイグレーションをブロックする失敗したマイグレーション

症状

以下のようなエラーが表示されます：

マイグレーションエラーの例text
Error: P3009
migrate found failed migrations in the target database, new migrations will not be applied.

A]migrate resolve --rolled-back 20260401071036_pr576_23836534312

to remove it from the database migrations table.
Read more about how to resolve migration issues in a production database:
https://pris.ly/d/migrate-resolve

また、マイグレーション出力で関係のないテーブルが変更されている場合は、ブランチが最新のmainから作成されていないことを示しています。

ステップ1: ブランチを最新状態にする

トラブルシューティングの前に、ブランチにmainからの最新の変更があることを確認してください：

ブランチを更新bash
git checkout main
git pull origin main
git checkout your-feature-branch
git merge main

ブランチが古いmainから作成されている場合、関係のないテーブルのマイグレーション変更が表示されることがあります。これはブランチをリベースするか再作成する必要があることを示しています。

多くの場合、最もシンプルな解決策は現在のPRをクローズし、mainからブランチを更新して、新しいPRを作成することです：

PRをクローズして最新のmainから再作成
Claudeプロンプト
PRがmainブランチの最新状態に基づいていないため、データベースマイグレーションエラーが発生しています。以下を手伝ってください： 1. 現在のPRをクローズ（PR #{PR番号}） 2. mainから最新の変更をプル 3. 更新されたmainから新しいブランチを作成 4. 変更を新しいブランチにcherry-pickまたは再適用 5. 新しいブランチをプッシュして新しいPRを作成 現在のブランチ名: [ブランチ名]

ステップ2: 問題を診断する

失敗したGitHub Actionからエラーをコピーし、Claudeに分析を依頼します：

マイグレーション問題を診断
Claudeプロンプト
あなたはシニアソフトウェアエンジニアです。GitHub Actionからのエラーメッセージを渡します。このエラーはブランチをRailwayにデプロイしようとした際に発生しました。Prismaマイグレーションの問題を示しています。マイグレーションファイルとschema.prismaファイルを確認し、問題を特定してください。 エラーメッセージ: [エラーメッセージをここに貼り付け] 問題の解決を手伝ってください。マイグレーションファイルは変更しないでください。ファイルを確認し、問題に対する推奨事項のみを提供してください。

Claudeの分析結果を受け取ったら、次に進む前にVibe Codingプランナー（チームのITスタッフまたはプロジェクトリーダー）に問題とClaudeの推奨事項を報告してください。診断の妥当性を確認し、最も安全な修正方法についてアドバイスを受けられます。

ステップ3: マイグレーションファイルを修正する

Claudeの推奨に基づいて、以下の作業が必要な場合があります：

  1. 重複したCREATE TABLE文を削除 — 複数のPRが同じテーブルを作成した場合
  2. schema.prismaを更新 — 期待されるデータベース状態と一致させる
  3. 競合するマイグレーションを削除 — すでに適用された変更と競合する場合

重要: 他のアプリケーションに属するテーブルやカラムを削除しないように注意してください。

危険ゾーン: ステップ4以降はデータベースを直接変更する操作です。これらの操作は、実行前にITスタッフの確認と承認が必要です。誤ったロールバックはデータ損失や他のアプリケーションの障害を引き起こす可能性があります。

ステップ4: 失敗したマイグレーションをロールバックする

修正をプッシュした後も、失敗したマイグレーションがデータベースに記録されているため、GitHub Actionが失敗する可能性があります。ロールバックが必要です。

新しいエラーをコピーし、Claudeにロールバックコマンドを依頼します：

ロールバックコマンドを取得
Claudeプロンプト
あなたはシニアソフトウェアエンジニアです。GitHub Actionからのエラーメッセージを渡します。このエラーはブランチをRailwayにデプロイしようとした際に発生しました。Prismaマイグレーションの問題を示しています。マイグレーションファイルとschema.prismaファイルを確認し、問題を特定してください。失敗したマイグレーションをロールバックするために必要なコマンドを提供してください。 エラーメッセージ: [エラーメッセージをここに貼り付け] 失敗したマイグレーションをロールバックするために必要なコマンドを提供してください。 例: DATABASE_URL="postgresql://..." \ pnpm --filter database exec prisma migrate resolve --rolled-back 20260401071036_pr576_23836534312 DATABASE_URL="postgresql://..." \ pnpm --filter database exec prisma migrate deploy

ステップ5: ロールバックコマンドを実行する

  1. Railwayサービスの「Variables」からDATABASE_URLを取得
  2. ローカルでロールバックコマンドを実行：
失敗したマイグレーションをロールバックbash
DATABASE_URL="postgresql://your-connection-string" \
pnpm --filter database exec prisma migrate resolve --rolled-back 20260401071036_migration_name
  1. ロールバック完了後、GitHub Actionを再実行

mainにマージ後にエラーが発生した場合

PRをmainにマージした後にマイグレーションが失敗した場合：

  1. mainから新しいブランチを作成
  2. 失敗したmerge-main-neon-cleanupアクションからエラーをコピー
  3. 上記のステップ2-5に従って問題を診断し修正
  4. 修正を新しいPRとしてプッシュ

セーフティネット: ポイントインタイムリカバリ

mainへのマージ後に何か問題が発生した場合、Neonはポイントインタイムリカバリを提供しています。チームリーダーまたはデータベース管理者に連絡して：

  1. 問題のあるマージ前の時点にデータベースを復元
  2. 正しいマイグレーションを再適用

注意: ポイントインタイムリカバリは、他の修正が失敗した後の最後の手段としてのみ使用してください。

マージ前のチェックリスト

データベース変更を含むPRをマージする前に：

  • 最新のmainからブランチを作成
  • schema.prismaが最新
  • マイグレーションファイルが既存のテーブルと競合しない
  • 重複したCREATE TABLE文がない
  • プレビューデプロイが成功
  • すべてのCIチェックが通過

クイズ

Quiz

'P3009 migrate found failed migrations'というエラーが表示されました。最初に何をすべきですか？