Alembic 数据库迁移实践

Sun, 29 Mar 2026 00:00:00 +0000

💡 导读：

在使用 SQLAlchemy 开发项目时，Base.metadata.create_all(engine) 虽然能快速初始化表，但无法处理后续的字段增加、类型修改等演进需求。为了解决表结构的版本管理与同步问题，我们需要引入 Alembic。本文将深入探讨 Alembic 的工作机制、初始化配置以及标准工作流，并复盘 SQLite 兼容性与字段重命名等常见工程挑战。

Alembic 是由 SQLAlchemy 作者编写的轻量级数据库迁移工具，它为数据库的表结构演进提供了完整的版本控制能力。

一、工作机制

Alembic 的核心逻辑可以类比为代码的版本控制系统。它主要依赖以下三个部分协同工作：

环境目录 (alembic 文件夹)：执行初始化命令后生成的目录，包含迁移配置、环境脚本和所有的迁移版本文件。
版本脚本 (Revision Scripts)：存放于环境目录的 versions 文件夹下。每个脚本对应一次表结构变更，内部包含 upgrade() 向上升级和 downgrade() 向下回退两个核心函数。
alembic_version 表：Alembic 会在目标数据库中自动创建一张单行表，用于记录当前数据库实际处于哪个版本号。执行迁移时，Alembic 会对比本地脚本与该表中的版本号，决定执行哪些 upgrade 或 downgrade 操作。

二、初始化与配置

在项目根目录下，通过命令行工具初始化 Alembic 环境：

alembic init alembic

这会生成一个 alembic.ini 配置文件和一个 alembic 目录。要让 Alembic 能够自动检测到 SQLAlchemy 模型的变化，必须完成两处核心配置。

1. 配置数据库连接

在 alembic.ini 中找到 sqlalchemy.url，修改为你的数据库连接字符串。但在实际工程中，密码和 URL 通常写在环境变量中。更安全的做法是在 env.py 中动态加载项目配置并覆盖该值。

2. 绑定模型元数据 (Metadata)

这是 Alembic 自动生成迁移脚本的关键。打开 alembic/env.py，导入项目中的声明基类 Base 以及所有的模型文件。

# alembic/env.py 核心修改片段
from logging.config import fileConfig
from sqlalchemy import engine_from_config
from sqlalchemy import pool
from alembic import context

# 导入你的项目模型，确保模型在此处被加载
from myapp.database import Base
from myapp import models 

config = context.config

# 将 target_metadata 设为 SQLAlchemy 模型的 metadata
target_metadata = Base.metadata

# ... 其他代码保持不变 ...

如果在执行迁移时提示检测不到表结构变化，通常是因为模型类没有在 env.py 执行时被成功导入到内存中。

三、标准工作流

完成配置后，日常的模型修改和数据库同步将遵循以下标准步骤：

1. 修改模型代码

在 SQLAlchemy 的模型类中添加或修改字段。

2. 自动生成迁移脚本

使用 --autogenerate 标志，Alembic 会对比当前数据库的实际结构与内存中的 target_metadata 结构，自动生成对应的迁移代码。-m 参数用于添加简短的变更说明。

alembic revision --autogenerate -m "add user email column"

执行后，必须人工检查 versions 目录下新生成的脚本文件，确保 upgrade() 函数中的变更逻辑符合预期。

3. 执行升级迁移

将数据库更新到最新版本：

alembic upgrade head

4. 版本回退

如果迁移代码有误或需要撤销上一步的结构变更，可以执行回退命令。-1 表示向后回退一个版本：

alembic downgrade -1

四、常见问题

在使用 Alembic 的过程中，有几个高频的工程配置问题需要提前预防。

1. SQLite 的 ALTER 限制

SQLite 对 ALTER TABLE 操作支持有限，默认情况下 Alembic 无法在 SQLite 中直接重命名列或修改列类型。如果项目使用 SQLite，需要在 env.py 中开启批处理模式。

# env.py 中的配置修改
with connectable.connect() as connection:
    context.configure(
        connection=connection,
        target_metadata=target_metadata,
        render_as_batch=True  # 开启批处理模式支持 SQLite
    )

2. 字段重命名与空迁移

Alembic 默认的 --autogenerate 机制并不总是完美的。

重命名：如果修改了模型中的列名，Alembic 默认会将其识别为“删除旧列”并“增加新列”，这会导致该列的原有数据丢失。遇到重命名需求时，必须手动修改生成的迁移脚本，使用 op.alter_column 方法。
类型改变未检测：默认情况下，Alembic 不会检查字段类型或默认值的变化。如果需要检测这些精细变更，需要在 env.py 的 context.configure 中添加 compare_type=True 和 compare_server_default=True 参数。

五、总结

SQLAlchemy 负责解决应用程序层面的对象关系映射，而 Alembic 填补了数据库生命周期管理中的缺失环节。建立完善的 修改模型 -> 审查脚本 -> 升级数据库 工作流，是保证复杂系统数据一致性的基础工程规范。

Alembic on Jiangwan's Blog