Flask Migrate(Alembic)执行flask db migrate未生成迁移脚本问题

问题根因 #

该问题由Flask-Migrate（底层依赖Alembic）的元数据不匹配导致：Alembic会对比当前代码中定义的模型结构，和数据库alembic_version表记录的迁移版本对应的表结构，判断两者没有差异时就不会生成新的迁移脚本。你之前手动删除数据库表、删除历史迁移脚本的操作，破坏了两端元数据的对应关系，所以出现检测不到变更的情况。

解决步骤 #

1. 清理数据库残留元数据
   使用psql连接到你的PostgreSQL数据库，依次执行以下SQL：

-- 删除你之前手动删除过的表的残留（示例是你测试用的表，其他自行补充）
DROP TABLE IF EXISTS example_table;
-- 删除Alembic版本记录表，重置迁移版本基线
DROP TABLE IF EXISTS alembic_version;

2. 重置本地迁移目录

• 删除项目根目录下的migrations文件夹
• 执行初始化命令：flask db init

3. 生成基线迁移脚本
   执行迁移生成命令：flask db migrate -m "init baseline"
   执行完成后请到migrations/versions目录下确认生成的迁移文件，检查是否包含所有模型对应的建表逻辑，包括测试用的ExampleModel

4. 执行迁移同步表结构
   执行升级命令：flask db upgrade
   执行完成后即可在数据库中看到所有模型对应的表，后续的迁移操作也会恢复正常。

后续操作注意事项 #

• 如果你的模型拆分在多个文件中，需要确保migrations/env.py中可以正确导入所有模型类，否则会出现检测不到模型变更的问题，可在env.py开头手动导入你的models模块确认
• 不要手动删除迁移脚本和数据库中的业务表，调整表结构请通过修改模型后执行flask db migrate+flask db upgrade的流程处理，避免再次出现元数据不匹配问题
• Alembic的自动检测存在局限性，如果生成的迁移脚本缺少你需要的变更，可以手动修改迁移文件后再执行upgrade。

内容的提问来源于stack exchange，提问作者Dr. Funkenstein