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>合并，生成一个合并 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() 后没备份数据，就再也找不回来了。
