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指向你的数据库地址比如mysqlpymysql://user:passlocalhost/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 就能用。整体上手成本不高配置好一次后日常就是“改模型 → 生成脚本 → 执行迁移”三步循环。
