メインコンテンツへスキップ
マイグレーションの失敗を監視したい場合は、Illuminate\Database\Events\MigrationFailed をリッスンします。Laravelは単一のマイグレーションの実行中に例外が発生すると、このイベントを発行してから例外を再スローします。 これはマイグレーションを自動的に再実行する仕組みではありません。失敗した名前、up / down のどちらで失敗したか、元の例外をログや通知へ渡すためのイベントです。

イベントが持つ情報

MigrationFailed は MigrationEvent を継承し、単一のマイグレーションに関する次の値を公開します。 name だけでなく migration::class も記録すると、ファイル名を取得できない経路でも対象を特定できます。migration->getConnection() を使えば、マイグレーションが明示的に指定した接続名も確認できます。

リスナーを登録する

アプリケーションのサービスプロバイダーでイベントを登録し、構造化されたコンテキストと元の例外をログへ渡します。
リスナーは失敗の記録に集中させ、スキーマの変更やマイグレーションの再実行は行わないようにします。イベントの後で元の例外が再スローされるため、php artisan migrate や php artisan migrate:rollback の終了は失敗のままです。

発行される順序

通常の単一マイグレーションでは、Migrator は次の順序でイベントを発行します。 MigrationEnded は実行が成功した場合にだけ発行されます。マイグレーションの処理や、実行中に発行されたイベントのリスナーが例外を投げると、runMigration の例外処理へ入り MigrationFailed が発行されます。 また、バッチの途中で例外が再スローされると、残りのマイグレーションは実行されません。そのため、失敗したバッチに対して MigrationsEnded が発行されるとは限りません。バッチ完了の処理と失敗時の処理を同じイベントだけで扱わないようにします。

トランザクションとの関係

データベースのSchema Grammarがスキーマトランザクションをサポートし、マイグレーションの withinTransaction が有効な場合、Laravelは実行をトランザクションで囲みます。
この経路で処理が失敗すると、トランザクションのロールバック後に MigrationFailed が発行されます。ただし、次のような場合はデータベースがすべての操作をロールバックできるとは限りません。
  • 使用するデータベースやSchema Grammarがスキーマトランザクションをサポートしていない
  • マイグレーションで public $withinTransaction = false を指定している
  • データベースがDDLをトランザクションとして扱わない
したがって、このイベントを受け取ったことだけでスキーマが元の状態に戻ったと判断しないでください。失敗した環境では、実際のスキーマと migrations テーブルの状態を確認してから復旧します。

up と down の失敗を区別する

ロールバックの失敗も同じイベントで通知されます。method を確認して、適用時と取り消し時で通知先や運用手順を分けられます。
down の失敗では、対象のマイグレーションが migrations テーブルから削除される前に例外が発生します。Migrator は正常に down が完了した後で削除処理を行うため、失敗後は実際のスキーマと記録の両方を確認します。

監視と通知の境界

MigrationFailed は、デプロイや手動のArtisanコマンドを実行したプロセス内で同期的に処理されます。通知をキューへ投入すると、マイグレーションコマンド自体の失敗を隠さずに、通知の配信を後続処理へ分離できます。 ただし、失敗したマイグレーションをリスナーから再実行するのは避けます。同じコマンドが終了していない状態で再実行すると、ロック、部分的に適用されたDDL、デプロイ順序の問題を複雑にするためです。再実行が必要な場合は、原因を修正し、状態を確認したうえで運用手順として実行します。

テストでイベントを確認する

失敗するテスト用マイグレーションを用意し、Artisanコマンドが失敗することと、イベントが原因の例外を持つことを確認します。テスト用のマイグレーションは本番の検索対象へ置かないでください。
Event::fake はイベントを記録するため、アプリケーションの実際の通知処理とは分けてテストできます。ロールバックの有無や、DDLが部分的に残らないことは、使用するデータベースとSchema Grammarを使った別の統合テストで確認します。

まとめ

  • MigrationFailed は単一マイグレーションの失敗時に、migration、method、name、exception を渡します。
  • MigrationEnded は成功時だけ、MigrationsEnded はバッチが最後まで完了した場合に発行されます。
  • トランザクションやDDLの挙動はデータベースによって異なるため、イベントをロールバックの保証として扱いません。
  • リスナーは監視と通知に限定し、再実行や復旧は原因とスキーマを確認してから運用手順で行います。

参照した一次情報

最終更新日 2026年11月15日