Illuminate\Database\Events\MigrationFailed. Cuando se produce una excepción durante la ejecución de una migración individual, Laravel emite este evento y después vuelve a lanzar la excepción.
No es un mecanismo que vuelva a ejecutar migraciones automáticamente. Es un evento para pasar a los logs y notificaciones el nombre de la migración fallida, si falló up o down, y la excepción original.
Información que contiene el evento
MigrationFailed hereda de MigrationEvent y expone los siguientes valores sobre una migración individual.
Si registras
migration::class además de name, podrás identificar la migración incluso en rutas donde no se puede obtener el nombre del archivo. Con migration->getConnection() también puedes comprobar el nombre de conexión que la migración especificó explícitamente.
Registrar un listener
Registra el evento en el service provider de tu aplicación y pasa al log el contexto estructurado y la excepción original.php artisan migrate y php artisan migrate:rollback siguen terminando con fallo.
Orden de emisión
En una migración individual normal,Migrator emite los eventos en el siguiente orden.
MigrationEnded solo se emite cuando la ejecución tiene éxito. Si el procesamiento de la migración, o un listener de un evento emitido durante la ejecución, lanza una excepción, se entra en el manejo de excepciones de runMigration y se emite MigrationFailed.
Además, si la excepción se vuelve a lanzar en medio de un lote, las migraciones restantes no se ejecutan. Por eso, no siempre se emite MigrationsEnded para un lote fallido. No manejes la finalización del lote y el fallo con un único evento.
Relación con las transacciones
Cuando el Schema Grammar de la base de datos admite transacciones de esquema ywithinTransaction de la migración está activado, Laravel envuelve la ejecución en una transacción.
MigrationFailed se emite después del rollback de la transacción. Sin embargo, en los siguientes casos la base de datos no siempre puede revertir todas las operaciones:
- La base de datos o el Schema Grammar que usas no admite transacciones de esquema
- La migración especifica
public $withinTransaction = false - La base de datos no trata el DDL como transaccional
migrations antes de recuperarlo.
Distinguir los fallos de up y down
Los fallos de rollback también se notifican con el mismo evento. Comprueba method para separar los destinos de notificación y los procedimientos operativos al aplicar y al revertir.
down, la excepción se produce antes de que la migración se elimine de la tabla migrations. Migrator realiza la eliminación solo después de que down termine correctamente, así que tras un fallo comprueba tanto el esquema real como el registro.
Límites de la monitorización y las notificaciones
MigrationFailed se procesa de forma síncrona en el proceso que ejecutó el despliegue o el comando Artisan manual. Si encolas la notificación, puedes separar su entrega en un procesamiento posterior sin ocultar el fallo del propio comando de migración.
Sin embargo, evita volver a ejecutar la migración fallida desde el listener. Volver a ejecutarla mientras el mismo comando no ha terminado complica los bloqueos, el DDL aplicado parcialmente y el orden del despliegue. Si es necesario volver a ejecutarla, corrige la causa, comprueba el estado y ejecútala como procedimiento operativo.
Comprobar el evento en las pruebas
Prepara una migración de prueba que falle y comprueba que el comando Artisan falla y que el evento contiene la excepción causante. No coloques las migraciones de prueba donde las encuentre la búsqueda de producción.Event::fake registra los eventos, así que puedes probar por separado del procesamiento real de notificaciones de la aplicación. Comprueba si hay rollback, y que no quede DDL aplicado parcialmente, en pruebas de integración separadas que usen tu base de datos y tu Schema Grammar.
Resumen
MigrationFailedpasamigration,method,nameyexceptioncuando falla una migración individual.MigrationEndedsolo se emite en caso de éxito, yMigrationsEndedsolo cuando el lote se completa hasta el final.- El comportamiento de las transacciones y del DDL varía según la base de datos, así que no trates el evento como una garantía de rollback.
- Limita los listeners a la monitorización y las notificaciones, y realiza las reejecuciones y la recuperación como procedimiento operativo después de comprobar la causa y el esquema.