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

# Migrationsfehler mit dem MigrationFailed-Event behandeln

> Verwenden Sie das MigrationFailed-Event aus Laravel 13 und verstehen Sie die Informationen einer fehlgeschlagenen Migration, Transaktionsgrenzen sowie das Design von Monitoring und Tests.

Wenn Sie Migrationsfehler überwachen möchten, lauschen Sie auf `Illuminate\Database\Events\MigrationFailed`. Tritt während der Ausführung einer einzelnen Migration eine Exception auf, löst Laravel dieses Event aus und wirft die Exception anschließend erneut.

Es handelt sich nicht um einen Mechanismus, der Migrationen automatisch erneut ausführt. Das Event dient dazu, den Namen der fehlgeschlagenen Migration, ob `up` oder `down` fehlgeschlagen ist, und die ursprüngliche Exception an Logs und Benachrichtigungen weiterzugeben.

## Informationen des Events

`MigrationFailed` erbt von `MigrationEvent` und stellt für eine einzelne Migration die folgenden Werte bereit.

| Eigenschaft | Typ | Inhalt |
| - | - | - |
| `migration` | `Migration` | Die auszuführende Migrationsinstanz |
| `method` | `string` | Die aufgerufene Methode, in der Regel `up` oder `down` |
| `name` | `string\|null` | Der Migrationsname. Je nach Ausführungspfad `null` |
| `exception` | `Throwable` | Die Exception, die den Fehler verursacht hat |

Wenn Sie zusätzlich zu `name` auch `migration::class` protokollieren, können Sie die Migration auch auf Pfaden identifizieren, auf denen der Dateiname nicht verfügbar ist. Mit `migration->getConnection()` sehen Sie außerdem den Verbindungsnamen, den die Migration explizit angegeben hat.

## Einen Listener registrieren

Registrieren Sie das Event im Service Provider Ihrer Anwendung und übergeben Sie strukturierten Kontext sowie die ursprüngliche Exception an das Log.

```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,
            ]);
        });
    }
}
```

Beschränken Sie den Listener auf das Protokollieren des Fehlers und ändern Sie darin weder das Schema noch führen Sie Migrationen erneut aus. Da die ursprüngliche Exception nach dem Event erneut geworfen wird, enden `php artisan migrate` und `php artisan migrate:rollback` weiterhin mit einem Fehler.

## Reihenfolge der Events

Bei einer normalen einzelnen Migration löst der `Migrator` die Events in der folgenden Reihenfolge aus.

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>Batch beginnt"] --> B["MigrationStarted<br>Einzelne Migration beginnt"]
    B --> C{"up / down erfolgreich?"}
    C -->|Erfolg| D["MigrationEnded<br>Einzelne Migration abgeschlossen"]
    D --> E["Nächste Migration"]
    E --> F["MigrationsEnded<br>Batch abgeschlossen"]
    C -->|Exception| G["MigrationFailed<br>Enthält die Exception"]
    G --> H["Ursprüngliche Exception erneut werfen"]
```

`MigrationEnded` wird nur ausgelöst, wenn die Ausführung erfolgreich ist. Wirft die Verarbeitung der Migration oder ein Listener für ein während der Ausführung ausgelöstes Event eine Exception, gelangt die Ausführung in die Exception-Behandlung von `runMigration` und `MigrationFailed` wird ausgelöst.

Wird die Exception mitten in einem Batch erneut geworfen, werden die verbleibenden Migrationen nicht ausgeführt. Daher wird für einen fehlgeschlagenen Batch nicht unbedingt `MigrationsEnded` ausgelöst. Behandeln Sie den Abschluss eines Batches und den Fehlerfall nicht mit demselben Event.

## Zusammenhang mit Transaktionen

Wenn die Schema Grammar der Datenbank Schema-Transaktionen unterstützt und `withinTransaction` der Migration aktiviert ist, umschließt Laravel die Ausführung mit einer Transaktion.

```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');
        });
    }
};
```

Schlägt die Verarbeitung auf diesem Pfad fehl, wird `MigrationFailed` nach dem Rollback der Transaktion ausgelöst. In folgenden Fällen kann die Datenbank jedoch nicht unbedingt alle Operationen zurückrollen:

* Die verwendete Datenbank oder Schema Grammar unterstützt keine Schema-Transaktionen
* Die Migration setzt `public $withinTransaction = false`
* Die Datenbank behandelt DDL nicht transaktional

Schließen Sie also nicht allein aus dem Empfang dieses Events, dass das Schema wieder im ursprünglichen Zustand ist. Prüfen Sie in der betroffenen Umgebung das tatsächliche Schema und den Zustand der Tabelle `migrations`, bevor Sie wiederherstellen.

## Fehler in `up` und `down` unterscheiden

Fehler beim Rollback werden über dasselbe Event gemeldet. Prüfen Sie `method`, um Benachrichtigungsziele und Betriebsabläufe für das Anwenden und das Zurücknehmen zu trennen.

```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,
    ]);
});
```

Schlägt `down` fehl, tritt die Exception auf, bevor die Migration aus der Tabelle `migrations` entfernt wird. Der `Migrator` entfernt den Eintrag erst, nachdem `down` erfolgreich abgeschlossen wurde. Prüfen Sie nach einem Fehler daher sowohl das tatsächliche Schema als auch den Eintrag.

## Grenzen von Monitoring und Benachrichtigungen

`MigrationFailed` wird synchron in dem Prozess verarbeitet, der das Deployment oder den manuellen Artisan-Befehl ausgeführt hat. Wenn Sie die Benachrichtigung in eine Queue stellen, können Sie deren Zustellung in die nachgelagerte Verarbeitung auslagern, ohne den Fehler des Migrationsbefehls selbst zu verbergen.

Vermeiden Sie es jedoch, die fehlgeschlagene Migration aus dem Listener erneut auszuführen. Eine erneute Ausführung, bevor derselbe Befehl beendet ist, verkompliziert Sperren, teilweise angewendetes DDL und die Reihenfolge des Deployments. Wenn eine erneute Ausführung nötig ist, beheben Sie die Ursache, prüfen Sie den Zustand und führen Sie sie dann als Betriebsablauf aus.

## Das Event in Tests prüfen

Bereiten Sie eine fehlschlagende Test-Migration vor und prüfen Sie, dass der Artisan-Befehl fehlschlägt und das Event die verursachende Exception enthält. Legen Sie Test-Migrationen nicht dort ab, wo sie in der Produktion gefunden werden.

```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` zeichnet Events auf, sodass Sie getrennt von der tatsächlichen Benachrichtigungsverarbeitung Ihrer Anwendung testen können. Ob ein Rollback stattfindet und ob kein DDL teilweise zurückbleibt, prüfen Sie in separaten Integrationstests mit Ihrer Datenbank und Schema Grammar.

## Zusammenfassung

* `MigrationFailed` übergibt beim Fehlschlagen einer einzelnen Migration `migration`, `method`, `name` und `exception`.
* `MigrationEnded` wird nur bei Erfolg ausgelöst, `MigrationsEnded` nur, wenn der Batch vollständig abgeschlossen wurde.
* Das Verhalten von Transaktionen und DDL unterscheidet sich je nach Datenbank. Behandeln Sie das Event daher nicht als Garantie für ein Rollback.
* Beschränken Sie Listener auf Monitoring und Benachrichtigungen und führen Sie erneute Ausführungen und Wiederherstellungen erst nach Prüfung von Ursache und Schema als Betriebsablauf durch.

## Verwendete Primärquellen

* [Offizielle Laravel-Dokumentation: Migrations-Events](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Offizielle Laravel-Dokumentation: Event-Listener](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: Auslösen von Events im Migrator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x: Basisklasse Migration](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [Weiterführende Themen](https://kawax.biz/de/advanced/index.md)
- [Datenbank-Migrationen](https://kawax.biz/de/migrations.md)
- [SessionEvent](https://kawax.biz/de/packages/laravel-copilot-sdk/session-event.md)
- [Events und Listener](https://kawax.biz/de/events.md)
- [Event-Listener in Paketen registrieren und cachen](https://kawax.biz/de/advanced/package-events.md)


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