Vai al contenuto principale
Se vuoi monitorare i fallimenti delle migrazioni, ascolta 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.
Fai in modo che il listener si concentri sulla registrazione del fallimento, senza modificare lo schema né rieseguire migrazioni. Poiché l’eccezione originale viene rilanciata dopo l’evento, php artisan migrate e php artisan migrate:rollback terminano comunque con un errore.

Ordine di emissione

Per una normale singola migrazione, il Migrator 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 e withinTransaction della migrazione è attivo, Laravel racchiude l’esecuzione in una transazione.
Se l’elaborazione fallisce in questo percorso, 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
Quindi non concludere che lo schema sia tornato allo stato originale solo perché hai ricevuto questo evento. Nell’ambiente in cui si è verificato il fallimento, controlla lo schema effettivo e lo stato della tabella 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.
Quando 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.
  • MigrationFailed passa migration, method, name ed exception quando una singola migrazione fallisce.
  • MigrationEnded viene emesso solo in caso di successo, e MigrationsEnded solo 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.

Fonti primarie consultate

Ultima modifica il 15 novembre 2026