轻量级数据库迁移工具: Alembic

Mon, 19 Aug 2024 09:32:43 +0800

数据库表结构维护的痛点

在缺乏专用迁移工具的环境下，团队对数据库结构的演进通常依赖手工脚本与临时操作，由此积累出一类共性工程问题。

痛点	具体问题
Schema 漂移（代码与库结构不一致）	本地可运行而生产环境报错；无人能准确描述生产库的真实结构
多环境同步	dev / staging / prod 结构各自为政，依赖手工维护的 SQL 脚本传递
回滚困难	结构变更出错后缺乏可靠的反向脚本，手动回滚极易遗漏
变更无版本 / 无审计	难以追溯"何人、何时、因何"修改了某个字段
团队协作冲突	多人并行修改表结构时，SQL 变更相互覆盖
DBA 不开放直连	生产库仅接受经审批的 SQL 脚本，不提供连接权限
事务安全	迁移中途失败，数据库结构处于半成品状态

迁移工具:Alembic如何解决上面痛点

痛点	无迁移工具时的典型困境	Alembic 的应对
Schema 漂移（代码与库结构不一致）	本地可运行而生产环境报错；无人能准确描述生产库的真实结构	以模型为单一真相源，`--autogenerate` 比对并生成差异
多环境同步	dev / staging / prod 结构各自为政，依赖手工维护的 SQL 脚本传递	`alembic upgrade head` 在各环境幂等执行
回滚困难	结构变更出错后缺乏可靠的反向脚本，手动回滚极易遗漏	每个迁移自带 `downgrade()`，支持可逆升级
变更无版本 / 无审计	难以追溯"何人、何时、因何"修改了某个字段	迁移文件纳入版本控制，天然携带作者、时间与说明
团队协作冲突	多人并行修改表结构时，SQL 变更相互覆盖	基于 UUID 的 DAG 版本图，支持分支与合并
DBA 不开放直连	生产库仅接受经审批的 SQL 脚本，不提供连接权限	`alembic upgrade head --sql` 导出纯 SQL 交付 DBA
事务安全	迁移中途失败，数据库结构处于半成品状态	默认在事务内执行（PostgreSQL / SQL Server 支持 DDL 事务）

alembic官方文档

Github仓库

Alembic是SQLAlchemy的子项目，SQLAlchemy通过python类定义表结构、Python对象表示数据行、通过Python而非SQL写query且支持多数据库的问题；Alembic是数据库表结构的“时间机器”

[!NOTE]

Alembic 是**“面向 SQLAlchemy 但保持解耦”**的迁移工具：它读取 Base.metadata（模型声明）以生成迁移脚本，但脚本本身是独立的 Python 模块，可脱离 ORM 运行时单独执行，亦可导出为标准 SQL。换言之，它与 SQLAlchemy 是"强协作、弱绑定"的关系。

核心功能

对数据库发起ALTER语句以修改表结构
为系统构造迁移脚本，每个脚本表明一系列步骤用来将目标数据库升级为新版本；类似地也可以将数据库降级到某个版本
允许脚本以某种顺序执行

目标

对事务型DDL完全支持
最小脚本构建

关键技术原理

版本即 DAG（有向无环图）

每个迁移文件头部声明两段核心元数据：

revision = "a1b2c3d4e5f6" # 本迁移的唯一标识（默认 12 位十六进制）
down_revision = "z9y8x7w6v5u4" # 前驱迁移的标识（可为 None 或列表）

全部迁移文件据此连成一条链（或多条分支）。alembic upgrade head 即沿 down_revision 链推进至末端。数据库中另有一张极小的 alembic_version 表，仅记录当前已应用的 revision，Alembic 据此判定"应从何处继续推进"

autogenerate（自动生成）原理

Auto Generating Migrations

工作机制为：

借助 SQLAlchemy 的 inspect 反射目标数据库当前 schema；
读取代码中 Base.metadata 声明的"期望 schema"；
二者求差，将差异渲染为一组 op.xxx() 指令并写入新迁移文件；
开发者须在应用前对生成结果进行人工审查——其输出应被视为待审的初始草案，而非可直接投产的终稿。

会检测的：

表的增加和移除
列的增加和移除
列上nullable状态的改变
索引和显式命名的唯一约束的改变
外键约束的改变
CHECK约束的增加和移除

可选择性检测的：

列类型的改变

EnvironmentContext.configure.compare_type设置成False则不检测，默认为True
server default的改变

EnvironmentContext.configure.compare_server_default参数控制，默认为False

不检测的：

表名的改变
列名的改变
匿名约束
特定的SQLAlchemy类型比如Enum（有的数据库后端不直接支持Enum类型）

op 指令与事务

迁移文件中调用的是 alembic.op（Operations）模块：op.create_table、op.add_column、op.alter_column、op.create_index、op.execute("RAW SQL") 等。它们生成的是最小化的 DDL，无需重新声明整张表结构。

关键约束：默认整段迁移包裹于单一事务内（PostgreSQL、SQL Server 支持 DDL 事务），中途失败可自动回滚。但部分操作（如 Postgres 的 ALTER TYPE ... ADD VALUE、CREATE INDEX CONCURRENTLY）无法在事务内执行，须以 op.execute("COMMIT") 显式退出事务，或借助 execute_if 有条件地执行。

离线 SQL 模式

alembic upgrade head --sql > migration.sql 不连接数据库，而是将所有 DDL 打印为标准 SQL 文本。这是对接"DBA 审批流 / 仅交付 SQL 不开放连接"这类企业约束的关键能力。

render_as_batch（SQLite 的补偿机制）

SQLite 几乎不支持 ALTER COLUMN。检测到 SQLite 时，Alembic 启用 batch 模式：新建表 → 拷贝数据 → 删除旧表 → 重命名，以此透明地完成"改列"语义。在 env.py 中设置 render_as_batch=True 即可启用。

如何使用Alembic管理数据库表结构版本

Tutorials

安装

uv add --dev alembic

positional arguments:
{branches,check,current,downgrade,edit,ensure_version,heads,history,init,list_templates,merge,revision,show,stamp,upgrade}
branches Show current branch points.
check Check if revision command with autogenerate has pending upgrade ops.
current Display the current revision for a database.
downgrade Revert to a previous version.
edit Edit revision script(s) using $EDITOR.
ensure_version Create the alembic version table if it doesn't exist already .
heads Show current available heads in the script directory.
history List changeset scripts in chronological order.
init Initialize a new scripts directory.
list_templates List available templates.
merge Merge two revisions together. Creates a new migration file.
revision Create a new revision file.
show Show the revision(s) denoted by the given symbol.
stamp 'stamp' the revision table with the given revision; don't run any migrations.
upgrade Upgrade to a later version.
options:
-h, --help show this help message and exit
--version show program's version number and exit
-c CONFIG, --config CONFIG
Alternate config file; defaults to value of ALEMBIC_CONFIG environment variable, or
"alembic.ini". May also refer to pyproject.toml file. May be specified twice to reference both
files separately
-n NAME, --name NAME Name of section in .ini file to use for Alembic config (only applies to configparser config, not
toml)
-x X Additional arguments consumed by custom env.py scripts, e.g. -x setting1=somesetting -x
setting2=somesetting
--raiseerr Raise a full stack trace on error
-q, --quiet Do not log to std output.

标准流程

init：初始化

创建通用模版

alembic init

生成的关键文件：

文件	职责
`alembic.ini`	全局配置（数据库连接串、脚本路径等）
`migrations/env.py`	核心：定义连接方式、`target_metadata` 获取与事务策略
`migrations/script.py.mako`	迁移文件模板（决定每个新文件的骨架）
`migrations/versions/`	全部迁移脚本的存放目录

查看有哪些模版：

alembic list_templates

alembic init --template multidb

将模型接入env.py

# migrations/env.py 中指定 target_metadata
from myapp.models import Base
target_metadata = Base.metadata
# 在 run_migrations_online() 的 context.configure 中开启更敏锐的探测
context.configure(
connection=connection,
target_metadata=target_metadata,
compare_type=True, # 检测列类型变化（默认关闭）
compare_server_default=True, # 检测 server_default 变化（默认关闭）
render_as_batch=True, # SQLite 兼容
)

[!NOTE]

常见坑：Base.metadata为空,数据库里表实际存在，导致得到的迁移脚本upgrade为删除表结构。

原因：未在env.py导入相关表的ORM模型，只导入了Base。

根因：Alembic autogenerate的工作方式：把"数据库当前 schema（通过 SQLAlchemy 反射得到）“与"你的 Base.metadata（Python 模型声明）“做一次结构化 diff。

但Alembic 不会扫描你的项目结构。原因在于它要保持 ORM 无关、项目结构无关——它不知道你的模型叫 models.py 还是 schema/ 目录，也不知道你用的是哪个 Base。所以它把"把哪个 metadata 交给它"这件事完全交给你手动接线。

而SQLAlchemy 的 declarative 模型，本质是类定义时自动执行的注册动作：Base.metadata.tables[”…”] = Table(…)。

所以只有导入具体的ORM模型，才会往Base注册表的元数据，从而被alembic用于和真实库表结构进行对比。

标准工作流

# 1) 修改 SQLAlchemy 模型后，先确保数据库处于最新状态
alembic upgrade head
# 2) 让 Alembic 比对模型与库结构，生成候选迁移
alembic revision --autogenerate -m "add user status column"
# 3) ★ 务必打开生成文件进行人工审查（参见第 6 节风险点）
vim migrations/versions/xxxx_add_user_status_column.py
# 4) 应用迁移
alembic upgrade head
# 常用诊断命令
alembic current # 查看数据库当前所处的 revision
alembic history --verbose# 查看迁移链
alembic heads # 查看是否存在多个头（多即分支冲突）
alembic downgrade -1 # 回退一个版本
alembic upgrade head --sql > out.sql # 导出 SQL 交付 DBA

[!WARNING]

常见陷阱：

① 未先执行 upgrade head 便运行 --autogenerate，导致将他人已应用的变更重复生成；

② 未开启 compare_type=True，致使 String(50)→String(100) 之类变更被静默忽略；

③ 直接信任 autogenerate 输出、未经审查即上线。

场景：一个项目多个库

最佳实践

数据库配置管理

默认生成的在alembic.ini模版文件中需要配置sqlalchemy.url，但如果alembic.ini要纳入版本管理，则不适合显式配置数据库用户密码。

开发环境，可以直接删掉 sqlalchemy.url 行，强制从环境变量取：

# env.py —— 不依赖 ini 里的 url
database_url = os.environ["DATABASE_URL"] # 缺失则直接报错，fail-fast
config.set_main_option("sqlalchemy.url", database_url)

[!TIP]

对于生产环境，CI（GitHub Actions / GitLab CI）里把 DATABASE_URL 配成加密变量 / secret，运行时注入，URL 永远不落盘到仓库。

生成与审查

每次仅承载一个逻辑变更，迁移文件宜小、宜单一职责
--autogenerate 的产物始终视为初始草案，审查者须逐行核对 drop/add 是否实为 rename
开启 compare_type 与 compare_server_default
为迁移赋予有意义的 -m 说明
在 CI 中引入"漂移检测"：模型与库不一致即令构建失败（见下方示例）

生产安全

大表新增 NOT NULL 列：先以 nullable + 数据回填，再置 NOT NULL，或附加 server_default
索引用 CREATE INDEX CONCURRENTLY 规避锁表（需退出事务）
采用 expand-contract 模式实现零停机：先加新结构、保持代码双兼容、再移除旧结构
downgrade 仅作为"结构回滚"的安全网，数据迁移不可逆
CI 强制单一 head：test $(alembic heads | wc -l) -eq 1

CI 漂移检测（强烈建议）

def test_no_drift(engine):
from alembic.autogenerate import compare_metadata
from alembic.migration import MigrationContext
with engine.connect() as conn:
ctx = MigrationContext.configure(conn)
diff = compare_metadata(ctx, Base.metadata)
assert diff == [], f"Schema drift: {diff}"

该测试可强制"模型变更必须配套相应迁移"，从源头杜绝代码与数据库悄然脱节。

常见的坑

Python 在执行这个类定义时，DeclarativeMeta（声明式元类）会顺手做一件事：Base.metadata.tables["mcp_audit_logs"] = Table(...)。也就是说——

Base.metadata.tables 这个字典，是靠"模型模块被 import"这个副作用逐步填进去的，不是靠 Alembic 去读你的 .py 源文件。

关键点：Base 这个类的对象本身是空的。from myapp.db import Base 只把"模具"拿过来，并不生产任何表。只有当你真正 import 了定义模型的那个模块，类体才会执行、表才会登记进 metadata。

Alembic 的 autogenerate 对比的是**内存里的 target_metadata（你给它的那个 metadata 对象）*和*数据库反射回来的 schema。如果你的模型模块在 Alembic 进程里从没被 import，那么 target_metadata.tables 里就根本没有 mcp_audit_logs → 反射看到库里有、metadata 里没有 → 判定为"多余" → upgrade() 生成 DROP。这就是你上一轮脚本反着来的完整因果链。

类似方案与优劣对比

方案	语言/生态	自动生成	DB 无关性	数据迁移	学习曲线	典型适用
Alembic	Python / SQLAlchemy	强（autogenerate）	中（绑定 SQLAlchemy 模型）	支持	中	FastAPI / Flask 等非 Django 的 Python 项目
Django Migrations	Python / Django	强（内置）	低（强绑定 Django ORM）	支持	低	Django 项目（开箱即用，无需额外引入）
Flyway	Java / CLI / 多语言	无（纯手写 SQL）	高（纯 SQL，跨任意 DB）	支持（依托 SQL）	低	多语言团队、企业级、DBA 主导、需严格 SQL 管控
Liquibase	Java / XML·YAML·JSON·SQL	部分（可 diff）	高（企业级多 DB）	强	高（概念体系庞大）	大型组织、复杂回滚、需审计与多格式
Yoyo	Python（轻量）	无	高（纯 SQL/Python）	支持	低	不愿引入 SQLAlchemy 依赖的小型 Python 项目
Atlas (Ariga)	Go / HCL·SQL	强（声明式，schema 即真相）	高	支持	中	声明式管理、Kubernetes / 云原生、希望摆脱手写顺序迁移
dbmate	Go / 单一 SQL	无	高	支持	低	极简、多语言团队、仅需"可执行的 SQL 迁移"
Rails / ActiveRecord	Ruby / Rails	强（内置）	低（绑定 Rails）	支持	低	Ruby on Rails 项目

延伸阅读

资料	聚焦主题	价值与说明
Alembic 官方文档 https://alembic.sqlalchemy.org/en/latest/	总览、Tutorial、Autogenerate	权威一手来源，覆盖完整。偏 reference 风格，需自行串联为实践路径。必读
Alembic Cookbook https://alembic.sqlalchemy.org/en/latest/cookbook.html	离线迁移、多租户、自定义版本表等进阶配方	官方进阶手册，解答"标准教程未覆盖"的真实场景。必读
Alembic Cheatsheet 03 — Autogenerate https://blog.rajpoot.dev/cheatsheets/alembic/03-autogenerate-cheatsheet	autogenerate 检测/漏检清单、env.py 配置、CI 漂移测试	对 autogenerate 的能与不能做了系统化梳理，并给出可复用的漂移检测代码。必读
Why Your Alembic Migrations Work Locally and Wreck Prod https://krun.pro/alembic-migrations	rename 陷阱、downgrade 数据不可逆、alembic_version 不匹配	以生产事故视角剖析"本地通过、线上翻车"的根因。必读
Zero-Downtime Schema Changes with Alembic https://timderzhavets.com/blog/zero-downtime-schema-changes-with-alembic-a-production	expand-contract 模式、CONCURRENTLY、迁移审查清单	系统讲解零停机迁移的工程方法，弥补本文在"大规模生产演进"上的篇幅限制。必读
Fix: Alembic Not Working https://fixdevs.com/blog/alembic-not-working	排错向：compare_type、多 head、自定义类型 / ENUM	以"故障—修复"结构组织，适合作为踩坑时的检索手册。

Alembic | NullSpace