Alembic自动生成迁移脚本时错误尝试删除alembic_version表的问题排查

看起来你碰到了Alembic autogenerate的一个常见配置坑，我来一步步拆解你的问题和解决方案：

1. 这是Alembic的已知问题吗？它默认应该忽略alembic_version表吗？ #

Alembic 确实应该默认忽略自己的alembic_version表，不会把它纳入迁移对比的范围。但这个问题通常出现在特定的配置组合下（比如你用了include_schemas=True加上指定了target_schema），属于配置导致的预期外行为，而非Alembic的核心bug。社区里也有不少人碰到过类似情况，大多是Schema扫描范围的配置和元数据对比逻辑的交互问题。

2. 我的配置哪里出问题了？ #

你的核心问题出在include_schemas=True的使用上：

• 当你设置include_schemas=True时，Alembic会扫描target_schema（这里是public）下的所有表，然后和target_metadata里定义的表做对比。
• 因为alembic_version表不在你的target_metadata（即frontend_metadata）里，Alembic会错误地判定这张表是“多余的”，所以生成了op.drop_table的指令。
• 正常情况下Alembic会自动排除自己的版本表，但include_schemas=True的全量扫描逻辑会绕过这个默认排除规则。

你的target_metadata和target_schema本身配置是正确的，只是和include_schemas=True的组合触发了这个问题。

3. 不用手动修改迁移脚本的话，正确的解决方法是什么？ #

有两个可靠的方案，推荐按优先级尝试：

方案一：添加exclude_tables配置（最简单）

在env.py的context.configure调用中，直接添加exclude_tables={"alembic_version"}，明确告诉Alembic排除这张表的对比：

修改run_migrations_offline和run_migrations_online里的配置：

# run_migrations_offline中的配置
context.configure(
    url=url,
    target_metadata=target_metadata,
    literal_binds=True,
    dialect_opts={"paramstyle": "named"},
    include_schemas=True,            
    version_table_schema=target_schema,
    exclude_tables={"alembic_version"}  # 新增这一行
)

# run_migrations_online中的配置
context.configure(
    connection=connection,
    target_metadata=target_metadata,
    include_schemas=True,           
    version_table_schema=target_schema,
    compare_type=True,
    compare_server_default=True,
    exclude_tables={"alembic_version"}  # 新增这一行
)

这个配置会让Alembic在扫描Schema时直接跳过alembic_version表，不会把它当成需要删除的多余表。

方案二：自定义include_object钩子（更灵活）

如果需要更精细的控制（比如未来要排除其他系统表），可以写一个自定义的过滤函数，手动跳过alembic_version：

def include_object(object, name, type_, reflected, compare_to):
    # 排除alembic_version表
    if type_ == "table" and name == "alembic_version":
        return False
    # 保留其他所有对象的对比逻辑
    return True

然后在两个run_migrations函数的context.configure中添加这个钩子：

include_object=include_object

这个方法的优势是可扩展性强，以后要排除其他表只需修改这个函数即可。

后续验证步骤 #

修改配置后，你可以按以下步骤确认问题解决：

1. 若之前alembic_version表已被误删，先手动恢复：CREATE TABLE public.alembic_version (version_num VARCHAR(32) NOT NULL PRIMARY KEY);
2. 重新运行alembic revision --autogenerate -m "Initial schema setup"
3. 检查生成的迁移脚本，确认op.drop_table('alembic_version')已消失
4. 执行alembic upgrade head，此时应该能正常完成迁移

备注：内容来源于stack exchange，提问作者NoNam4