Passer au contenu principal
Pour surveiller les échecs de migration, écoutez Illuminate\Database\Events\MigrationFailed. Lorsqu’une exception survient pendant l’exécution d’une migration individuelle, Laravel émet cet événement puis relance l’exception. Il ne s’agit pas d’un mécanisme qui réexécute automatiquement les migrations. Cet événement sert à transmettre aux logs et aux notifications le nom de la migration échouée, l’indication que c’est up ou down qui a échoué, et l’exception d’origine.

Informations portées par l’événement

MigrationFailed hérite de MigrationEvent et expose les valeurs suivantes pour une migration individuelle. Si vous enregistrez migration::class en plus de name, vous pouvez identifier la migration même sur les chemins où le nom du fichier n’est pas disponible. Avec migration->getConnection(), vous pouvez aussi vérifier le nom de connexion que la migration a spécifié explicitement.

Enregistrer un listener

Enregistrez l’événement dans le service provider de votre application et transmettez au log un contexte structuré et l’exception d’origine.
Limitez le listener à l’enregistrement de l’échec, sans modifier le schéma ni réexécuter de migrations. Comme l’exception d’origine est relancée après l’événement, php artisan migrate et php artisan migrate:rollback se terminent toujours en échec.

Ordre d’émission

Pour une migration individuelle normale, le Migrator émet les événements dans l’ordre suivant. MigrationEnded n’est émis que si l’exécution réussit. Si le traitement de la migration, ou un listener d’un événement émis pendant l’exécution, lance une exception, l’exécution passe dans la gestion d’exceptions de runMigration et MigrationFailed est émis. Par ailleurs, si l’exception est relancée au milieu d’un lot, les migrations restantes ne sont pas exécutées. MigrationsEnded n’est donc pas forcément émis pour un lot échoué. Ne gérez pas la fin d’un lot et l’échec avec le seul et même événement.

Relation avec les transactions

Lorsque la Schema Grammar de la base de données prend en charge les transactions de schéma et que withinTransaction de la migration est activé, Laravel encapsule l’exécution dans une transaction.
Si le traitement échoue sur ce chemin, MigrationFailed est émis après le rollback de la transaction. Cependant, dans les cas suivants, la base de données ne peut pas toujours annuler toutes les opérations :
  • La base de données ou la Schema Grammar utilisée ne prend pas en charge les transactions de schéma
  • La migration définit public $withinTransaction = false
  • La base de données ne traite pas le DDL de manière transactionnelle
Ne concluez donc pas que le schéma est revenu à son état d’origine simplement parce que vous avez reçu cet événement. Dans l’environnement en échec, vérifiez le schéma réel et l’état de la table migrations avant de procéder à la reprise.

Distinguer les échecs de up et de down

Les échecs de rollback sont signalés par le même événement. Vérifiez method pour séparer les destinataires des notifications et les procédures d’exploitation entre l’application et l’annulation.
Lorsque down échoue, l’exception survient avant que la migration ne soit supprimée de la table migrations. Le Migrator n’effectue la suppression qu’après la réussite de down. Après un échec, vérifiez donc à la fois le schéma réel et l’enregistrement.

Limites de la surveillance et des notifications

MigrationFailed est traité de manière synchrone dans le processus qui a exécuté le déploiement ou la commande Artisan manuelle. En mettant la notification en file d’attente, vous pouvez déporter sa livraison vers un traitement ultérieur sans masquer l’échec de la commande de migration elle-même. Évitez toutefois de réexécuter la migration échouée depuis le listener. La réexécuter alors que la même commande n’est pas terminée complique les verrous, le DDL partiellement appliqué et l’ordre du déploiement. Si une réexécution est nécessaire, corrigez la cause, vérifiez l’état, puis lancez-la en tant que procédure d’exploitation.

Vérifier l’événement dans les tests

Préparez une migration de test qui échoue, puis vérifiez que la commande Artisan échoue et que l’événement contient l’exception à l’origine de l’échec. Ne placez pas les migrations de test là où la recherche de production peut les trouver.
Event::fake enregistre les événements, ce qui vous permet de tester séparément du traitement réel des notifications de l’application. Vérifiez la présence d’un rollback, et l’absence de DDL partiellement appliqué, dans des tests d’intégration distincts utilisant votre base de données et votre Schema Grammar.

Résumé

  • MigrationFailed transmet migration, method, name et exception lorsqu’une migration individuelle échoue.
  • MigrationEnded n’est émis qu’en cas de succès, et MigrationsEnded uniquement lorsque le lot s’exécute jusqu’au bout.
  • Le comportement des transactions et du DDL varie selon la base de données. Ne considérez donc pas l’événement comme une garantie de rollback.
  • Limitez les listeners à la surveillance et aux notifications, et effectuez les réexécutions et la reprise en tant que procédure d’exploitation après avoir vérifié la cause et le schéma.

Sources primaires consultées

Dernière modification le 15 novembre 2026