golang-migrate Version Collision Fix¶
概念概覽
問題根因¶
核心知識¶
問題根因¶
golang-migrate/v4 的 file source driver 對版本號去重：同一版本前綴（044_）只能有一個 up/down 對。兩個衝突的情況：
- 044_add_settlement_runs_activity_fk.up.sql
- 044_create_sticker_tables.up.sql
不能重新編號其中一個（若 migration 已跑過 staging/prod 會造成 dirty state）。若尚未部署，正確做法是折回而非另起一個 045_。
修正策略（未部署時）¶
- 將 FK constraint 折回
043_create_activity_tables.up.sql（在settlement_runs建表 DDL 內直接加CONSTRAINT fk_settlement_runs_activity FOREIGN KEY (activity_id) REFERENCES activity_instances(id)） - 刪除
044_add_settlement_runs_activity_fk.{up,down}.sql兩個檔案 - 不需要新的
045_migration
關鍵前提判斷¶
此修法的前提是「尚未 deploy 到 staging/prod」。若已部署，則必須保留已跑過的版本號，改用新版本號（045+）補丁。
經驗教訓¶
-
migration 版本號衝突在 deploy 前修正成本極低（折回即可），deploy 後成本極高（必須補丁 migration）
-
FK constraint 應在建表時一併定義，不應分拆成獨立 migration（除非有 bootstrap 順序問題）
常見陷阱¶
- migration 版本號衝突只有在執行 migrate up 時才會報錯，開發期間無任何警告
最佳實踐¶
-
建表 migration 應包含所有 FK、constraint、index，減少後續補丁 migration 的數量
-
PR review 前用 ls migrations/postgres/ | sort 肉眼確認無重複版本號
相關概念¶
- Activity Framework GameDataProvider Constructor Injection
- postgres-schema-design----dangling---
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- golang-migrate Transaction Safety Contract — 共享：
golang-migrate,migration/ 獨特：ci,create-index-concurrently
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-10 | a7f313c0-2db2-4e32-8dc4-43117b1a66b8 | 兩支 migration 檔案使用相同版本前綴（044）造成 file source driver 拒絕執行，正確修法是將 FK constraint 折回前一個 migration（043）並刪除重複檔案 |