Alembic 已有数据库怎么标记当前迁移版本

已有数据库接入 Alembic 时，最容易犯的错误是直接执行 alembic upgrade head，让历史迁移重新碰撞现有表结构。正确做法是：先确认数据库结构已经等价于某个迁移版本，再用 alembic stamp 只登记版本，不执行迁移函数。

官方地址：https://alembic.sqlalchemy.org/

如果数据库已经是目标 revision 对应的结构，就用明确的 revision 建立基线；单分支可用 head，多 head 场景应明确使用 heads 或逐个 revision。stamp 不负责补表、加字段和修复结构差异。

先判断要标记到哪个版本

先看迁移目录中的 revision 链，再把它和数据库实际结构逐项对照。Alembic 通过版本表记录数据库当前指针，官方文档也说明，upgrade 会根据当前版本和目标版本计算需要执行的迁移路径。因此，基线版本必须是“结构已经存在”的版本，而不是“希望最终到达”的版本。

例如历史迁移已经在生产库之外完成，但没有留下 Alembic 版本记录，可以把“最后一次已经落实的迁移”作为目标。若表结构只完成了一半，就不能靠 stamp 掩盖差异，应先补齐结构或另写一次有明确变更的迁移。

revision、head 和 heads 怎么选

这三个写法不是同义词：

可以先查看当前迁移目录的 head，再决定目标。下面的命令只展示判断所需信息，注释说明每个命令的用途：

# 查看迁移目录中有哪些最新分支
alembic heads --verbose

# 查看数据库当前版本；首次接入时可能没有版本记录
alembic current

# 查看从基线到最新版本的迁移关系
alembic history --verbose

用 stamp 建立基线，再让 upgrade 接管后续变更

确认结构一致后，单分支可以使用明确 revision，例如：

# 只登记已经存在的结构对应版本，不执行 upgrade() 里的 DDL
alembic stamp 3f2a9c1d4b7e

# 多分支时登记迁移目录的全部 head；先确认每个 head 都与数据库现状匹配
alembic stamp heads

# 记录完成后，再查看数据库版本指针
alembic current

官方 Commands API 将 stamp 定义为给版本表写入目标 revision，明确说明不会运行迁移。之后新增字段、索引或表时，仍然创建新的 revision，并让发布流程执行 alembic upgrade head 或明确的目标版本。

如果需要在 Python 程序中调用同样的能力，可以使用 Alembic 的命令 API：

from alembic import command
from alembic.config import Config

# 读取项目迁移配置；目标 revision 必须先与数据库结构核对
config = Config("alembic.ini")
command.stamp(config, "3f2a9c1d4b7e")

# 后续真正发生结构变化时，才调用 upgrade
command.upgrade(config, "head")

示例把两种动作分开：stamp 建立版本基线，upgrade 才执行迁移脚本。生产环境不要把二者无条件串在一次初始化脚本里，否则结构未核对时可能把错误版本写成“已完成”。

多 head、误标记和回滚边界

多个 head 通常意味着迁移分支尚未合并。Alembic 官方分支文档建议先理解 branchpoint、head 和 mergepoint 的关系；如果业务上需要一条统一链，可以创建 merge revision，再以 merge 后的目标作为基线。不要把多个 head 当成一个普通字符串，也不要为了消除报错随意 stamp 到最新。

如果误标记了版本，先暂停自动发布，确认数据库实际结构和版本表内容，再决定用明确 revision 修正指针，或编写一条补偿迁移。stamp base 会移除版本记录，它不是撤销表结构的命令，不能代替 downgrade。

常见问题

已有数据库能直接 stamp head 吗？ 可以，但前提是数据库结构已经完整匹配唯一 head；否则只是把差异隐藏到版本表之外。

stamp 会创建缺失的表吗？ 不会。它只维护 Alembic 的版本记录，缺失结构应通过正式迁移或人工修复后再建立基线。

为什么 stamp 后 upgrade 仍然报错？ 常见原因是基线 revision 选错、存在多个 head，或数据库结构与迁移脚本并不等价。回到结构对照和迁移分支检查，不要重复 stamp。

总的判断标准只有一句话：数据库已经是什么结构，就登记到对应的 revision；数据库还没有什么结构，才让 upgrade 通过迁移脚本去完成。