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

数据库表结构维护的痛点

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

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

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

工作机制为：

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

会检测的：

• 表的增加和移除
• 列的增加和移除
• 列上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 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。这就是你上一轮脚本反着来的完整因果链。

类似方案与优劣对比

延伸阅读