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.php artisan migrate et php artisan migrate:rollback se terminent toujours en échec.
Ordre d’émission
Pour une migration individuelle normale, leMigrator é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 quewithinTransaction de la migration est activé, Laravel encapsule l’exécution dans une transaction.
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
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.
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é
MigrationFailedtransmetmigration,method,nameetexceptionlorsqu’une migration individuelle échoue.MigrationEndedn’est émis qu’en cas de succès, etMigrationsEndeduniquement 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.