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 的行為因資料庫而異,因此不要把該事件當作回滾的保證。
- 將監聽器限定於監控與通知,重新執行與復原應在確認原因與結構描述後作為維運流程進行。