执行 alembic downgrade -1 可回滚到前一迁移版本，alembic 自动读取 alembic_version 表并执行对应 downgrade()；若遇表不存在错误，需同步调整业务逻辑或停服务。
回滚到上一个迁移版本（最常用场景）
执行 alembic downgrade -1 即可回退到前一个版本。Alembic 会自动查找当前 alembic_version 表中记录的版本，然后执行对应迁移文件中的 downgrade() 函数。
常见错误现象：sqlalchemy.exc.ProgrammingError: (psycopg2.errors.UndefinedTable) relation "xxx" does not exist —— 这往往说明你刚建的表在 downgrade 中被删了，但后续代码还试图查它，得同步改业务逻辑或先停服务。
- 确保数据库连接配置正确，
alembic.ini或env.py中的SQLALCHEMY_URL指向目标库 - 如果迁移含数据操作（如
op.bulk_insert()），downgrade()必须显式逆向处理，否则回滚后数据不一致 - 运行前建议先用
alembic history确认当前版本链，避免误退多步
回滚到指定版本号（带 hash 的迁移）
Alembic 使用短哈希（如 3a7c12f）标识迁移，不是时间戳或序号。用 alembic downgrade 3a7c12f 回退到该版本（含），并执行其 downgrade()。
使用场景：上线后发现 v2.1 迁移有严重 bug，但 v2.0 是稳定的，而中间还有 v2.0.1、v2.0.2 两个小修迁移——这时不能只退一步，必须精准退到 3a7c12f（即 v2.0 的 revision id）。
-
alembic history --verbose可列出所有迁移及其 parent/child 关系，找到目标 revision - 若目标 revision 已被跳过（比如你当前在 v3，想退到 v1，但 v2 的 downgrade 不兼容），Alembic 会报错
Target database is not up to date，需手动检查依赖链 - 不要手动删
alembic_version表里的记录，这会导致状态错乱；始终走downgrade
撤销未提交的迁移文件（还没 upgrade 过）
如果刚写完 alembic revision -m "add user email" 生成了新文件，但还没运行 alembic upgrade head，此时想取消这个迁移，直接删掉生成的 Python 文件即可，无需 Alembic 命令。
容易踩的坑：alembic revision --autogenerate 会基于模型与当前 DB 差异生成新迁移，如果你删了文件但没清空 alembic_version，下次 autogenerate 可能重复生成相同内容，或漏掉变更。
- 删文件后，建议运行
alembic current确认输出为(head)或具体已应用版本，而非<base> - 如果已
upgrade过又想彻底“反悔”，不能只删文件，必须downgrade到上一版，再删文件，否则history会显示断链 - 团队协作时，删迁移文件前务必确认没人已基于它做了开发或部署
Flask 项目中集成 Alembic 的关键配置点
Flask 本身不感知 Alembic，靠 env.py 把 Flask-SQLAlchemy 的 db 实例注入到 Alembic 运行上下文。核心是重写 run_migrations_online() 中的 connectable 获取逻辑。
典型错误：alembic upgrade head 报 AttributeError: 'NoneType' object has no attribute 'bind'，本质是 context.get_bind() 拿不到 engine——因为 current_app 在 Alembic 独立进程中不可用。
- 在
env.py开头手动构建 engine：engine = create_engine(os.getenv("DATABASE_URL"))，绕过 Flask app context - 或者用 Flask-Migrate（它封装了 Alembic），通过
flask db downgrade -1调用，自动处理上下文 - 别在
env.py里 importapp或调用create_app()，Alembic 启动时不走 Flask CLI 生命周期
downgrade && upgrade 循环验证。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
