多特性分支场景下Alembic数据库迁移冲突的解决方案问询

问题本质 #

团队用Alembic+SQLAlchemy做数据库迁移时，多开发者从主分支拉取特性分支（feature1/feature2）开发，会遇到两类问题：

1. 开发者1在feature1创建并运行迁移后，开发者2在feature2创建迁移时报错FAILED: Can't locate revision identified by <last_migration_ran's_id>，原因是共享数据库的迁移版本和本地分支的迁移历史不匹配；
2. 两人同时创建迁移，开发者1先在共享库执行后，开发者2执行时同样出现版本不匹配错误。
   此外，分支迁移合并后执行顺序混乱还会引发不可预测问题。

具体解决方案 #

1. 本地环境隔离：避免共享数据库干扰 #

建议每个开发者使用独立的本地测试数据库，不要共用同一台测试库。这样各自创建、运行迁移完全独立，不会互相影响。

• 操作方式：修改alembic.ini中的sqlalchemy.url为自己的本地数据库地址，例如：

  sqlalchemy.url = postgresql://dev:123456@localhost/db_dev_lisi
  

2. 创建迁移前先同步主分支 #

每次生成新迁移文件前，必须拉取主分支最新代码并合并到当前特性分支，确保本地迁移历史与主分支一致：

• 步骤：

  git checkout feature2
  git pull origin main
  alembic upgrade head  # 同步本地数据库到主分支最新状态
  alembic revision --autogenerate -m "add user_address column"
  

3. 修复版本不匹配报错 #

如果已经出现Can't locate revision错误，按以下场景处理：

• 场景A：本地迁移历史落后于共享数据库
  1. 切换到主分支，拉取最新代码并执行alembic upgrade head，让本地数据库同步到最新状态；
  2. 切回特性分支，合并主分支代码；
  3. 重新生成迁移文件（若原迁移与主分支迁移有冲突，需手动修改迁移文件内容）。
• 场景B：共享数据库存在本地无记录的迁移
  禁止直接在共享库上强制修改版本，应立刻切换回本地独立数据库测试。若必须临时对齐，可谨慎执行alembic stamp <数据库当前的revision_id>，将本地迁移历史标记为与数据库一致，但后续要及时合并主分支代码修正历史。

4. 多分支迁移的合并与团队协作规范 #

迁移冲突的合并处理

当两个分支修改了同一张表/列，合并代码时必须手动处理迁移文件冲突：

• 例如两个分支都给user表添加了字段，合并后需将两个迁移的操作合并到一个文件，或调整执行顺序（确保依赖逻辑正确）；
• 合并完成后，必须在本地测试库执行alembic upgrade head验证迁移正常，再提交代码。

团队协作规范

• 禁止直接在共享测试/预发布库运行特性分支的迁移，所有分支迁移仅在本地环境验证；
• 迁移文件命名要清晰，比如20240520_add_user_phone_column.py，便于快速识别修改内容；
• 每次合并主分支后，必须重新检查迁移历史，若有分叉则重新生成迁移，确保主分支的迁移历史是线性的。

参考协作思路 #

结合同类工具的实践经验：

• 类似Flask-Migrate（基于Alembic）的多分支场景：核心是本地隔离+分支同步+合并后统一执行，避免共享数据库被分支迁移污染；
• 类似Flyway的多分支协作逻辑：强调迁移的原子性与可追溯性，分支迁移仅在本地运行，合并后重新整理迁移历史，保证生产环境的迁移顺序严格线性。

内容的提问来源于stack exchange，提问作者user17443811