Illuminate\Database\Events\MigrationFailed. Quando si verifica un’eccezione durante l’esecuzione di una singola migrazione, Laravel emette questo evento e poi rilancia l’eccezione.
Non è un meccanismo che riesegue automaticamente le migrazioni. È un evento che serve a passare a log e notifiche il nome della migrazione fallita, se è fallito up o down, e l’eccezione originale.
Informazioni contenute nell’evento
MigrationFailed estende MigrationEvent ed espone i seguenti valori relativi a una singola migrazione.
Se registri anche
migration::class oltre a name, puoi identificare la migrazione anche nei percorsi in cui il nome del file non è disponibile. Con migration->getConnection() puoi anche verificare il nome della connessione specificato esplicitamente dalla migrazione.
Registrare un listener
Registra l’evento nel service provider della tua applicazione e passa al log un contesto strutturato e l’eccezione originale.php artisan migrate e php artisan migrate:rollback terminano comunque con un errore.
Ordine di emissione
Per una normale singola migrazione, ilMigrator emette gli eventi nel seguente ordine.
MigrationEnded viene emesso solo quando l’esecuzione ha successo. Se l’elaborazione della migrazione, o un listener di un evento emesso durante l’esecuzione, lancia un’eccezione, si entra nella gestione delle eccezioni di runMigration e viene emesso MigrationFailed.
Inoltre, se l’eccezione viene rilanciata a metà di un batch, le migrazioni rimanenti non vengono eseguite. Per questo MigrationsEnded non viene necessariamente emesso per un batch fallito. Non gestire il completamento del batch e il fallimento con un unico evento.
Rapporto con le transazioni
Quando lo Schema Grammar del database supporta le transazioni di schema ewithinTransaction della migrazione è attivo, Laravel racchiude l’esecuzione in una transazione.
MigrationFailed viene emesso dopo il rollback della transazione. Tuttavia, nei casi seguenti il database non può sempre annullare tutte le operazioni:
- Il database o lo Schema Grammar in uso non supporta le transazioni di schema
- La migrazione specifica
public $withinTransaction = false - Il database non tratta il DDL come transazionale
migrations prima del ripristino.
Distinguere i fallimenti di up e down
Anche i fallimenti del rollback vengono notificati con lo stesso evento. Controlla method per separare destinatari delle notifiche e procedure operative tra applicazione e annullamento.
down fallisce, l’eccezione si verifica prima che la migrazione venga rimossa dalla tabella migrations. Il Migrator esegue la rimozione solo dopo che down è terminato correttamente, quindi dopo un fallimento controlla sia lo schema effettivo sia il record.
Confini di monitoraggio e notifiche
MigrationFailed viene elaborato in modo sincrono nel processo che ha eseguito il deploy o il comando Artisan manuale. Se metti la notifica in coda, puoi spostarne la consegna a un’elaborazione successiva senza nascondere il fallimento del comando di migrazione stesso.
Evita però di rieseguire la migrazione fallita dal listener. Rieseguirla mentre lo stesso comando non è ancora terminato complica i lock, il DDL applicato parzialmente e l’ordine del deploy. Se una riesecuzione è necessaria, correggi la causa, verifica lo stato ed eseguila come procedura operativa.
Verificare l’evento nei test
Prepara una migrazione di test che fallisce e verifica che il comando Artisan fallisca e che l’evento contenga l’eccezione che l’ha causato. Non collocare le migrazioni di test dove possono essere trovate in produzione.Event::fake registra gli eventi, quindi puoi testare separatamente dall’elaborazione reale delle notifiche dell’applicazione. Verifica la presenza del rollback, e che non resti DDL applicato parzialmente, in test di integrazione separati che usano il tuo database e il tuo Schema Grammar.
Riepilogo
MigrationFailedpassamigration,method,nameedexceptionquando una singola migrazione fallisce.MigrationEndedviene emesso solo in caso di successo, eMigrationsEndedsolo quando il batch viene completato fino alla fine.- Il comportamento di transazioni e DDL varia a seconda del database, quindi non considerare l’evento come una garanzia di rollback.
- Limita i listener a monitoraggio e notifiche, ed esegui riesecuzioni e ripristino come procedura operativa dopo aver verificato la causa e lo schema.