> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# MigrationFailedイベントでマイグレーション失敗を扱う

> Laravel 13のMigrationFailedイベントを使い、失敗したマイグレーションの情報、トランザクション境界、監視とテストの設計を理解します。

マイグレーションの失敗を監視したい場合は、`Illuminate\Database\Events\MigrationFailed` をリッスンします。Laravelは単一のマイグレーションの実行中に例外が発生すると、このイベントを発行してから例外を再スローします。

これはマイグレーションを自動的に再実行する仕組みではありません。失敗した名前、`up` / `down` のどちらで失敗したか、元の例外をログや通知へ渡すためのイベントです。

## イベントが持つ情報

`MigrationFailed` は `MigrationEvent` を継承し、単一のマイグレーションに関する次の値を公開します。

| プロパティ | 型 | 内容 |
| - | - | - |
| `migration` | `Migration` | 実行対象のマイグレーションインスタンス |
| `method` | `string` | 呼び出されたメソッド。通常は `up` または `down` |
| `name` | `string\|null` | マイグレーション名。実行経路によっては `null` |
| `exception` | `Throwable` | 失敗の原因になった例外 |

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

## リスナーを登録する

アプリケーションのサービスプロバイダーでイベントを登録し、構造化されたコンテキストと元の例外をログへ渡します。

```php theme={null}
<?php

namespace App\Providers;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
            Log::error('Database migration failed.', [
                'migration' => $event->name,
                'class' => $event->migration::class,
                'method' => $event->method,
                'connection' => $event->migration->getConnection(),
                'exception' => $event->exception,
            ]);
        });
    }
}
```

リスナーは失敗の記録に集中させ、スキーマの変更やマイグレーションの再実行は行わないようにします。イベントの後で元の例外が再スローされるため、`php artisan migrate` や `php artisan migrate:rollback` の終了は失敗のままです。

## 発行される順序

通常の単一マイグレーションでは、`Migrator` は次の順序でイベントを発行します。

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>バッチ開始"] --> B["MigrationStarted<br>単一マイグレーション開始"]
    B --> C{"up / down が成功?"}
    C -->|成功| D["MigrationEnded<br>単一マイグレーション完了"]
    D --> E["次のマイグレーション"]
    E --> F["MigrationsEnded<br>バッチ完了"]
    C -->|例外| G["MigrationFailed<br>例外を保持"]
    G --> H["元の例外を再スロー"]
```

`MigrationEnded` は実行が成功した場合にだけ発行されます。マイグレーションの処理や、実行中に発行されたイベントのリスナーが例外を投げると、`runMigration` の例外処理へ入り `MigrationFailed` が発行されます。

また、バッチの途中で例外が再スローされると、残りのマイグレーションは実行されません。そのため、失敗したバッチに対して `MigrationsEnded` が発行されるとは限りません。バッチ完了の処理と失敗時の処理を同じイベントだけで扱わないようにします。

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

データベースのSchema Grammarがスキーマトランザクションをサポートし、マイグレーションの `withinTransaction` が有効な場合、Laravelは実行をトランザクションで囲みます。

```php theme={null}
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('orders', function (Blueprint $table): void {
            $table->string('status');
        });
    }
};
```

この経路で処理が失敗すると、トランザクションのロールバック後に `MigrationFailed` が発行されます。ただし、次のような場合はデータベースがすべての操作をロールバックできるとは限りません。

* 使用するデータベースやSchema Grammarがスキーマトランザクションをサポートしていない
* マイグレーションで `public $withinTransaction = false` を指定している
* データベースがDDLをトランザクションとして扱わない

したがって、このイベントを受け取ったことだけでスキーマが元の状態に戻ったと判断しないでください。失敗した環境では、実際のスキーマと `migrations` テーブルの状態を確認してから復旧します。

## `up` と `down` の失敗を区別する

ロールバックの失敗も同じイベントで通知されます。`method` を確認して、適用時と取り消し時で通知先や運用手順を分けられます。

```php theme={null}
Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
    $operation = $event->method === 'down' ? 'rollback' : 'migrate';

    Log::critical('Migration operation failed.', [
        'operation' => $operation,
        'migration' => $event->name ?? $event->migration::class,
        'exception' => $event->exception,
    ]);
});
```

`down` の失敗では、対象のマイグレーションが `migrations` テーブルから削除される前に例外が発生します。`Migrator` は正常に `down` が完了した後で削除処理を行うため、失敗後は実際のスキーマと記録の両方を確認します。

## 監視と通知の境界

`MigrationFailed` は、デプロイや手動のArtisanコマンドを実行したプロセス内で同期的に処理されます。通知をキューへ投入すると、マイグレーションコマンド自体の失敗を隠さずに、通知の配信を後続処理へ分離できます。

ただし、失敗したマイグレーションをリスナーから再実行するのは避けます。同じコマンドが終了していない状態で再実行すると、ロック、部分的に適用されたDDL、デプロイ順序の問題を複雑にするためです。再実行が必要な場合は、原因を修正し、状態を確認したうえで運用手順として実行します。

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

失敗するテスト用マイグレーションを用意し、Artisanコマンドが失敗することと、イベントが原因の例外を持つことを確認します。テスト用のマイグレーションは本番の検索対象へ置かないでください。

```php theme={null}
<?php

namespace Tests\Feature;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use RuntimeException;
use Tests\TestCase;

class MigrationFailureTest extends TestCase
{
    public function test_failed_migration_dispatches_event(): void
    {
        Event::fake([MigrationFailed::class]);

        $this->artisan('migrate', [
            '--path' => 'tests/Fixtures/migrations/2026_01_01_000000_fail.php',
        ])->assertFailed();

        Event::assertDispatched(MigrationFailed::class, function (MigrationFailed $event): bool {
            return $event->method === 'up'
                && $event->exception instanceof RuntimeException;
        });
    }
}
```

`Event::fake` はイベントを記録するため、アプリケーションの実際の通知処理とは分けてテストできます。ロールバックの有無や、DDLが部分的に残らないことは、使用するデータベースとSchema Grammarを使った別の統合テストで確認します。

## まとめ

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

## 参照した一次情報

* [Laravel公式ドキュメント: マイグレーションイベント](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Laravel公式ドキュメント: イベントリスナー](https://github.com/laravel/docs/blob/13.x/events.md#registering-events-and-listeners)
* [Framework 13.x: MigrationFailed](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationFailed.php)
* [Framework 13.x: MigrationEvent](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationEvent.php)
* [Framework 13.x: Migratorのイベント発行](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x: Migration基底クラス](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [データベースマイグレーション](https://kawax.biz/jp/migrations.md)
- [パッケージのマイグレーション公開と更新](https://kawax.biz/jp/advanced/package-migrations.md)
- [応用トピック](https://kawax.biz/jp/advanced/index.md)
- [Laravelパッケージ開発](https://kawax.biz/jp/advanced/package-development.md)
- [Laravel 12 から 13 へのアップグレードガイド](https://kawax.biz/jp/blog/upgrade-12-to-13.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.