Alembic
Alembic 是 SQLAlchemy 官方推荐的数据库迁移（Migration）工具，用于以版本化的方式管理数据库表结构的变更。
Alembic 由 SQLAlchemy 的作者 Mike Bayer 开发，专门解决一个开发中的常见痛点：当你的数据模型（表结构）发生变化时，如何安全、可追溯地把这些变化同步到数据库，而不是手动写 SQL 或者直接删库重建。 它把每一次结构变更都记录成一个"版本"，就像 Git 管理代码一样管理你的数据库 schema。
它到底解决什么问题
在实际项目里，数据库表结构会不断演进：今天加一个字段，明天改一个字段类型，后天新建一张表。如果没有工具管理，你会面临几个麻烦：团队成员之间的数据库结构不一致、线上和本地环境对不上、想回退到之前的结构却无从下手。Alembic 通过"迁移脚本 + 版本链"的机制解决这些问题，每个变更都有唯一版本号，并记录它的上一个版本，从而形成一条可以随时向前（upgrade）或向后（downgrade）移动的链条。
核心概念
理解 Alembic 主要抓住下面几个概念：
| 概念 | 说明 |
|---|---|
| Migration Script（迁移脚本） | 每次结构变更生成的一个 Python 文件，包含 upgrade() 和 downgrade() 两个函数 |
| Revision（版本） | 每个脚本的唯一标识（如 a1b2c3d4），并记录 down_revision 指向上一个版本 |
alembic_version 表 |
Alembic 在你的数据库里自动建的一张表，记录当前数据库处于哪个版本 |
env.py |
迁移运行时的配置入口，连接数据库、指定 metadata 等 |
| Autogenerate | 自动对比模型和数据库现状，生成迁移脚本的功能 |
典型工作流程
一个最常见的使用流程是这样的。首先初始化环境，生成 Alembic 的目录结构：
alembic init alembic
然后在 env.py 里把你的模型 metadata 关联进来，之后每当你修改了 SQLAlchemy 的模型定义，就可以让 Alembic 自动比对差异并生成迁移脚本：
alembic revision --autogenerate -m "add user email column"
生成的脚本大致长这样，upgrade 描述如何应用变更，downgrade 描述如何回退：
def upgrade():
op.add_column('users', sa.Column('email', sa.String(length=120)))
def downgrade():
op.drop_column('users', 'email')
最后把变更应用到数据库，或在需要时回退：
alembic upgrade head # 升级到最新版本
alembic downgrade -1 # 回退一个版本
需要注意的点
Autogenerate 虽然强大，但它不是万能的——它能检测到新增/删除表、新增/删除列等常见变更，但对于列改名、某些约束变化、服务端默认值等情况可能识别不准，因此每次生成脚本后都建议人工检查一遍再执行。此外，downgrade 逻辑需要你自己保证正确性，尤其是涉及数据迁移（而不仅仅是结构变更）时，回退可能造成数据丢失，要格外谨慎。
总的来说，如果你在用 Python 做后端开发、特别是搭配 SQLAlchemy 或 FastAPI/Flask 这类框架，Alembic 几乎是管理数据库结构演进的标准配置。它让数据库变更变得像代码一样可版本化、可协作、可回滚。
⬅️ 03-RAG 检索增强生成 🏠 00-数据库 ➡️ 00-工具与环境
💬 评论