Illuminate\Database\Events\MigrationFailed。当单个迁移在执行过程中发生异常时,Laravel 会先触发此事件,然后重新抛出该异常。
这并不是自动重新执行迁移的机制。它是一个用于将失败的迁移名称、是 up 还是 down 失败,以及原始异常传递给日志和通知的事件。
事件包含的信息
MigrationFailed 继承自 MigrationEvent,并公开关于单个迁移的以下值。
除了
name 之外再记录 migration::class,即使在无法获取文件名的路径中也能确定目标迁移。使用 migration->getConnection() 还可以确认迁移显式指定的连接名称。
注册监听器
在应用的服务提供者中注册事件,并将结构化的上下文和原始异常传递给日志。php artisan migrate 和 php artisan migrate:rollback 仍会以失败结束。
触发顺序
对于普通的单个迁移,Migrator 按以下顺序触发事件。
MigrationEnded 只在执行成功时触发。如果迁移的处理,或执行过程中触发的事件的监听器抛出异常,就会进入 runMigration 的异常处理,并触发 MigrationFailed。
此外,如果在批次中途重新抛出异常,剩余的迁移将不会执行。因此,失败的批次不一定会触发 MigrationsEnded。不要只用同一个事件来同时处理批次完成和失败。
与事务的关系
当数据库的 Schema Grammar 支持架构事务,且迁移的withinTransaction 处于启用状态时,Laravel 会用事务包裹执行过程。
MigrationFailed 会在事务回滚之后触发。但在以下情况下,数据库不一定能回滚所有操作:
- 所使用的数据库或 Schema Grammar 不支持架构事务
- 迁移中指定了
public $withinTransaction = false - 数据库不将 DDL 作为事务处理
migrations 表的状态,然后再进行恢复。
区分 up 与 down 的失败
回滚失败也通过同一事件通知。检查 method,即可在应用与撤销时区分通知目标和运维流程。
down 失败时,异常发生在目标迁移从 migrations 表中删除之前。Migrator 只在 down 正常完成后才执行删除,因此失败后请同时确认实际的架构和记录。
监控与通知的边界
MigrationFailed 在执行部署或手动 Artisan 命令的进程内同步处理。将通知放入队列,就可以在不掩盖迁移命令本身失败的前提下,把通知的投递分离到后续处理中。
但应避免在监听器中重新执行失败的迁移。在同一命令尚未结束时重新执行,会使锁、部分应用的 DDL 以及部署顺序等问题变得复杂。需要重新执行时,请先修复原因并确认状态,再作为运维流程执行。
在测试中确认事件
准备一个会失败的测试用迁移,确认 Artisan 命令失败,并且事件持有导致失败的异常。不要把测试用迁移放在生产环境的扫描范围内。Event::fake 会记录事件,因此可以与应用实际的通知处理分开测试。是否发生回滚、DDL 是否会部分残留,请使用所用数据库和 Schema Grammar 编写单独的集成测试来确认。
总结
- 单个迁移失败时,
MigrationFailed会传递migration、method、name和exception。 MigrationEnded只在成功时触发,MigrationsEnded只在批次完整执行完毕时触发。- 事务和 DDL 的行为因数据库而异,因此不要把该事件当作回滚的保证。
- 将监听器限定于监控和通知,重新执行和恢复应在确认原因和架构后作为运维流程进行。