Naar hoofdinhoud gaan
Wilt u mislukte migraties monitoren, luister dan naar Illuminate\Database\Events\MigrationFailed. Wanneer er tijdens het uitvoeren van een enkele migratie een exception optreedt, verzendt Laravel dit event en gooit daarna de exception opnieuw. Dit is geen mechanisme dat migraties automatisch opnieuw uitvoert. Het event dient om de naam van de mislukte migratie, of up of down mislukte, en de oorspronkelijke exception door te geven aan logs en notificaties.

Gegevens van het event

MigrationFailed erft van MigrationEvent en stelt de volgende waarden voor een enkele migratie beschikbaar. Als u naast name ook migration::class vastlegt, kunt u de migratie identificeren, ook op paden waar de bestandsnaam niet beschikbaar is. Met migration->getConnection() kunt u ook de verbindingsnaam controleren die de migratie expliciet heeft opgegeven.

Een listener registreren

Registreer het event in de service provider van uw applicatie en geef gestructureerde context en de oorspronkelijke exception door aan de log.
Laat de listener zich richten op het vastleggen van de fout en wijzig daarin niet het schema en voer geen migraties opnieuw uit. Omdat de oorspronkelijke exception na het event opnieuw wordt gegooid, eindigen php artisan migrate en php artisan migrate:rollback nog steeds met een fout.

Volgorde van verzending

Bij een normale enkele migratie verzendt de Migrator de events in de volgende volgorde. MigrationEnded wordt alleen verzonden als de uitvoering slaagt. Gooit de verwerking van de migratie, of een listener van een event dat tijdens de uitvoering werd verzonden, een exception, dan komt de uitvoering in de exceptionafhandeling van runMigration terecht en wordt MigrationFailed verzonden. Wordt de exception halverwege een batch opnieuw gegooid, dan worden de resterende migraties niet uitgevoerd. Daarom wordt MigrationsEnded niet per se verzonden voor een mislukte batch. Behandel het voltooien van een batch en het mislukken niet met één en hetzelfde event.

Relatie met transacties

Wanneer de Schema Grammar van de database schematransacties ondersteunt en withinTransaction van de migratie is ingeschakeld, omsluit Laravel de uitvoering met een transactie.
Mislukt de verwerking op dit pad, dan wordt MigrationFailed verzonden na de rollback van de transactie. In de volgende gevallen kan de database echter niet altijd alle bewerkingen terugdraaien:
  • De gebruikte database of Schema Grammar ondersteunt geen schematransacties
  • De migratie stelt public $withinTransaction = false in
  • De database behandelt DDL niet als transactie
Concludeer dus niet alleen op basis van dit event dat het schema weer in de oorspronkelijke staat is. Controleer in de omgeving waar het misging het werkelijke schema en de staat van de tabel migrations voordat u herstelt.

Fouten in up en down onderscheiden

Fouten bij een rollback worden via hetzelfde event gemeld. Controleer method om notificatiebestemmingen en operationele procedures te scheiden voor toepassen en terugdraaien.
Als down mislukt, treedt de exception op voordat de migratie uit de tabel migrations wordt verwijderd. De Migrator verwijdert de record pas nadat down met succes is voltooid. Controleer na een fout daarom zowel het werkelijke schema als de record.

Grenzen van monitoring en notificaties

MigrationFailed wordt synchroon verwerkt in het proces dat de deployment of het handmatige Artisan-commando heeft uitgevoerd. Als u de notificatie in een queue plaatst, kunt u de bezorging ervan naar latere verwerking verplaatsen zonder de fout van het migratiecommando zelf te verbergen. Vermijd echter dat u de mislukte migratie vanuit de listener opnieuw uitvoert. Opnieuw uitvoeren terwijl hetzelfde commando nog niet is beëindigd, maakt locks, gedeeltelijk toegepaste DDL en de volgorde van de deployment ingewikkelder. Is opnieuw uitvoeren nodig, los dan de oorzaak op, controleer de staat en voer het uit als operationele procedure.

Het event in tests controleren

Bereid een test-migratie voor die mislukt en controleer dat het Artisan-commando mislukt en dat het event de veroorzakende exception bevat. Plaats test-migraties niet op een plek waar productie ze kan vinden.
Event::fake registreert events, zodat u los van de werkelijke notificatieverwerking van uw applicatie kunt testen. Of er een rollback plaatsvindt en of er geen DDL gedeeltelijk achterblijft, controleert u in aparte integratietests met uw database en Schema Grammar.

Samenvatting

  • MigrationFailed geeft bij het mislukken van een enkele migratie migration, method, name en exception door.
  • MigrationEnded wordt alleen bij succes verzonden, en MigrationsEnded alleen als de batch volledig is voltooid.
  • Het gedrag van transacties en DDL verschilt per database. Behandel het event daarom niet als garantie voor een rollback.
  • Beperk listeners tot monitoring en notificaties, en voer herhalingen en herstel uit als operationele procedure nadat u de oorzaak en het schema hebt gecontroleerd.

Geraadpleegde primaire bronnen

Laatst gewijzigd op 15 november 2026