SQL Alembic 的 autogenerate 与手动 revision 的结合使用规范

autogenerate生成迁移文件不准，因其仅对比表结构字段增删改，无法识别语义变更、约束名差异、索引顺序、视图/函数/自定义类型及__table_args__中非约束配置；常见错误包括漏生成改动、误判为drop/add column、忽略server_default或enum变更等。

autogenerate 生成的 migration 文件为什么经常不准

因为 autogenerate 依赖 sqlAlchemy 对当前模型与数据库 schema 的对比，但它看不到语义变更、数据迁移逻辑、约束名差异、索引顺序变化，也搞不定视图/函数/自定义类型。它只“看得到”表结构字段增删改，且默认忽略 __table_args__ 里的非约束类配置（比如 comment 或 schema）。

常见错误现象：alembic revision --autogenerate 没生成任何改动，或生成了 DROP COLUMN 又 ADD COLUMN（实际只是改了 Nullable），或漏掉外键约束名变更导致 downgrade 失败。

• 使用场景：适合字段级小迭代（加字段、改类型、调 nullable），不适合重命名列、拆分表、迁移历史数据
• 必须手动检查生成的 upgrade() 和 downgrade()：确认没有意外的 DROP、没有遗漏的 op.create_index()、外键名是否与 DB 实际一致
• 若模型中用了 server_default 或 server_onupdate，autogenerate 通常不生成对应 SQL，需补上 op.alter_column(..., server_default=...)
• postgresql 下，enum 类型变更必须手动处理——autogenerate 不会帮你 CREATE TYPE 或 ALTER TYPE

什么时候必须用手动 revision 而不是 autogenerate

当你需要控制执行顺序、嵌入原生 SQL、操作非表对象（如函数、触发器）、做数据清洗，或 autogenerate 无法识别变更意图时，就得甩开它，直接 alembic revision -m "xxx" 手写。

典型场景包括：列重命名（SQLAlchemy 模型里改 Column('new_name') 不等于 DB 里 ALTER TABLE RENAME COLUMN）、添加唯一约束但要跳过重复值、把 json 字段拆成多个 varchar 字段并迁移数据。

• 重命名列必须手写：op.alter_column('tbl', 'old_name', new_column_name='new_name')，且 PostgreSQL/mysql 语法不同，不能靠 autogenerate 推断
• 数据迁移务必放在 upgrade() 中靠前位置，避免在结构变更后查不到旧字段；downgrade() 里得反向补全，否则回滚失败
• 用 op.execute("UPDATE ...") 时，记得加事务控制——Alembic 默认不在 upgrade/downgrade 中开事务，大更新要包 with op.batch_alter_table(...) as batch_op: 或显式用 connection
• 如果 migration 要调用自定义函数（如 my_normalize(text)），必须确保该函数已在 target DB 存在，autogenerate 不会帮你创建

autogenerate 和手动 revision 混用时的版本依赖怎么理清

Alembic 不关心你是手写还是自动生成，只按 revision id 和 down_revision 连成链。混用本身没问题，但容易出现「两个 revision 都声称自己是同一个 down_revision 的子节点」，导致 alembic upgrade head 报 Multiple heads 错误。

常见错误现象：alembic revision --autogenerate 生成了新文件，但你之前手写了一个未提交的 revision，结果两者都指向同一个父 revision，Alembic 就懵了。

• 每次手写 alembic revision -m "xxx" 后，立刻 git commit，再让队友跑 autogenerate——避免本地残留未提交 revision
• 发现 Multiple heads，先用 alembic branches 看分叉点，再用 alembic merge -m "merge heads" <rev1><rev2></rev2></rev1> 合并，生成一个合并 revision
• 不要手动改 down_revision 字符串——它由 Alembic 自动生成，改错会导致 upgrade 跳过中间步骤
• 团队协作时，在 env.py 里设 compare_type=True 和 compare_server_default=True，能让 autogenerate 更敏感，减少漏判，但也可能多报——需权衡

如何让 autogenerate 少出错、手动 revision 更易维护

核心是让 Alembic “看得更准”，同时让人眼 review 成本更低。不靠玄学，靠三处配置和一条纪律。

• 在 env.py 的 run_migrations_online() 中，给 context.configure() 加参数：include_schemas=True（多 schema 场景）、include_object=include_object（过滤掉视图/序列等不想管的对象）
• 所有手动 revision 文件顶部加注释说明变更意图和影响范围，例如：# 数据迁移：将 user.email_lower 改为唯一索引，先去重再建约束
• 避免在 upgrade() 里写复杂 Python 逻辑——它运行在 DB 连接上下文中，没日志、难调试；真要判断，用 op.get_bind().execute(text("select ...")) 查，别用纯 Python if
• 每个 revision 文件只做一件事：要么改结构，要么迁数据，不要混在一起。混了就难 rollback，也难定位问题

最常被忽略的是：autogenerate 不检查数据一致性，也不校验 downgrade 是否真的可逆。哪怕语法全对，一个 op.drop_column() 后没备份数据，就再也找不回来了。