Alembic 是 SQLAlchemy 官方推出的轻量级数据库迁移工具，核心作用是把数据库表结构的变更（建表、加列、改类型、加索引等）纳入版本控制，让你在不同环境（开发/测试/生产）里能重复、安全地把数据库升级或回滚到指定版本。
为什么需要它
直接用 Base.metadata.create_all() 只能在表不存在时创建，修改已有表结构不会自动同步。 Alembic 把每次结构变更记录成独立的迁移脚本，配合 Git 使用，团队成员执行一条命令就能同步最新结构，出问题也能回滚。
快速上手
- 安装与初始化 ：pip install alembic，然后 alembic init alembic，如果是异步环境则 alembic init -t async alembic。会生成 alembic.ini（配置文件）和 alembic/ 目录（含 env.py、versions/）。
- 配置数据库连接 ：修改 alembic.ini 里的 sqlalchemy.url 指向你的数据库地址，比如 mysql+pymysql://user:pass@localhost/dbname。生产环境不建议硬编码密码，可以在env.py里从环境变量读取，覆盖这个配置。
- 关联模型 ：打开 alembic/env.py，导入你的 Base，把 target_metadata = None 改成 target_metadata = Base.metadata。这步漏了，自动生成的迁移脚本会是空的。
- 生成迁移脚本 ：改完模型后执行 alembic revision --autogenerate -m "描述信息"，Alembic 会对比模型和数据库差异，自动生成迁移脚本。
- 执行迁移 ：alembic upgrade head 把数据库升级到最新版本；回滚用 alembic downgrade -1（回滚一个版本）或 alembic downgrade base（全部回滚）。
常用命令速查
使用建议
- 自动生成的脚本必须人工检查 ：--autogenerate 不是万能的，字段重命名、表重命名这类操作它可能识别成"删旧建新"，导致数据丢失，需要手动改成 op.alter_column 或 op.rename_table。
- 已提交的迁移脚本不要修改：就像不能改 Git 历史一样，新变更通过新增迁移脚本实现。
- 迁移前先备份数据库，并在开发或测试环境充分验证后再上生产。
Alembic 在 Flask 里可以配合 Flask-Migrate 使用，FastAPI 里直接集成 SQLAlchemy 就能用。整体上手成本不高，配置好一次后，日常就是"改模型 → 生成脚本 → 执行迁移"三步循环。