为何Python Flask项目中使用Alembic比手动改表结构更安全

Alembic 通过版本化迁移实现安全、幂等、可回滚的数据库变更管理，而手动 SQL 缺乏状态跟踪、不可逆且易出错；autogenerate 仅生成草稿，需人工审查并完善 upgrade/downgrade 逻辑。

因为 Alembic 把数据库结构变更变成了可版本化、可重复执行、可回滚的代码操作，而手动改表是无记录、不可逆、依赖人肉同步的高危行为。

alembic upgrade head 不会重复执行已应用的迁移

Alembic 在数据库中建了一张 alembic_version 表，只存一个字段：当前已执行到的迁移脚本版本号。每次成功执行 alembic upgrade head，它就更新这个值；下次再跑，会自动跳过已记录的版本。

• 手动 SQL 没有这种状态跟踪，靠人记“这个 ALTER 执行过了吗”，极易漏或重
• CI/CD 流水线里反复部署时，alembic upgrade head 是幂等的，手动 SQL 不是
• 多环境（本地/测试/生产）只要连对库，命令一跑，结构自动对齐，不用比对 SQL 文件列表

alembic downgrade -1 能快速回退破坏性变更

每个迁移脚本都必须定义 upgrade() 和 downgrade() 两个函数。比如加字段的 upgrade 是 ALTER TABLE ADD COLUMN，对应的 downgrade 就是 ALTER TABLE DROP COLUMN（前提是数据库支持，如 MySQL 8.0+）。

• 手动执行 DROP COLUMN 后，数据永久丢失，基本无法恢复
• 用 alembic downgrade -1 回退，不仅结构还原，如果 downgrade 里写了数据备份逻辑，还能恢复部分数据
• 上线后发现新字段导致查询变慢，5 秒内就能切回上一版结构，不用翻聊天记录找原始 SQL

alembic revision --autogenerate 生成脚本前必须人工审查

alembic revision --autogenerate -m "add user_phone" 会比对当前模型与数据库实际结构，生成迁移内容。但它不是万能的：

立即学习“Python免费学习笔记（深入）”；

• 重命名字段会被识别为“删旧列 + 加新列”，直接运行会丢数据 → 必须手动改成 ALTER TABLE RENAME COLUMN
• 某些索引、CHECK 约束、JSON 字段默认值，autogenerate 可能漏掉或写错 → 得打开生成的 versions/xxx.py 文件逐行看
• 涉及数据迁移（比如把一个字段拆成两个），autogenerate 完全不处理 → 要在 upgrade() 里手写 UPDATE 语句，并加事务包装

真正安全的不是 Alembic 本身，而是它强制你把每次结构变更显式写成带版本号的 Python 文件、提交进 Git、走 Code Review —— 这个流程卡住了绝大多数低级错误。最容易被忽略的，是认为“生成了就能直接上生产”，其实 autogenerate 只是草稿，downgrade 的健壮性、大表 ALTER 的锁表现、跨数据库兼容性，都得在测试环境实测过才敢动生产。