2026/8/9

Alembic 是什么
Alembic 是"数据库结构的版本管理工具"，相当于给数据库表结构做的 Git。
Git 管的是代码的版本，Alembic 管的是"表结构长什么样"的版本。每次改表（加列、删列、改字段），都生成一个迁移脚本（类似一次 commit），记录下来：
alembic/versions/
├─ 0001_创建所有表.py
├─ 0002_给任务表加步骤配置列.py
├─ 0003_给提交表加步骤数据列.py
└─ ...
工作流程（以后改表就三步）
改代码：在 models.py 里加新字段
自动生成迁移脚本：运行 alembic revision --autogenerate -m "给任务表加 xx 列"，Alembic 对比"代码里定义的表"和"数据库里实际的表"，自动算出差异，生成一个脚本
应用迁移：运行 alembic upgrade head，数据库就变成最新结构了
更妙的是可以回退：alembic downgrade 能撤销上一次结构变更。

场景 没有迁移工具 有 Alembic
你加了新列 手动执行 ALTER，容易忘 写进迁移脚本，跑 upgrade 就完事
同事拉你的代码 不知道要改表 他也跑一次 upgrade，结构自动同步
部署上线 在服务器手敲 SQL，心惊胆战 部署脚本自动跑迁移
改错了想回退 手动拼反向 SQL downgrade 一键回退
多个环境（开发/测试/生产） 每个环境手动搞一遍 同一套迁移脚本，处处一致

企业里"开发机、测试机、生产机"三套数据库全靠迁移脚本保证结构一致，这是数据安全的基本功。

数据库迁移就是像管代码版本一样管理表结构的变更。我们项目早期改表靠手动 ALTER，加列之后容易漏。后来用 Alembic：改完模型后 --autogenerate 生成迁移脚本，upgrade head 应用，downgrade 回退。好处是可追溯、可复现、团队和环境之间结构一致，部署时自动执行，不会出现'我本地能跑、服务器跑不了'。