手把手教你使用 Alembic 进行数据迁移

庖丁解牛：认识 Alembic

Alembic 是 SQLAlchemy 作者打造的数据库迁移工具，就像给数据库装上git。它能记录数据结构的变化轨迹，让你可以随时前进后退，特别适合在团队协作中保持数据库结构同步。

迁移模式

有两种迁移模式：

• 手动迁移：适合明确知道要执行什么 SQL 语句的场景，就像亲手给数据库做手术，这种需要手工编写迁移脚本，适合进行大型数据迁移场景 ，对每一步都需要精细控制。
• 自动迁移：通过比对模型定义与当前数据库状态生成迁移脚本，这种模式适合迭代开发阶段，随着模型的升级不断升级数据库。

生成模式双雄

模式	特点	使用场景
在线模式	直接连接数据库生成迁移脚本	开发环境，有数据库权限
离线模式	不连接数据库生成通用迁移脚本	生产环境，权限受限时使用

第 1 步：（安装环境）

# 安装核心工具
pip install alembic sqlalchemy psycopg2-binary

# 验证安装
alembic --version

>>> alembic 1.13.1
>>>   Location: /usr/local/lib/python3.11/site-packages/alembic

第 2 步：（初始化项目）

alembic init migrations

>>>   Creating directory /project/migrations ... done
>>>   Creating directory /project/migrations/versions ... done
>>>   Generating /project/alembic.ini ... done
>>>   Generating /project/migrations/env.py ... done
>>>   Generating /project/migrations/README ... done

项目结构说明：

├── alembic.ini       # 配置文件（数据库连接等）
└── migrations        # 迁移脚本目录
    ├── env.py        # 迁移环境配置
    └── versions      # 存放迁移脚本

第 3 步：（配置数据库）

修改 alembic.ini：

sqlalchemy.url = postgresql://user:password@localhost/mydb

验证连接：

alembic current

>>> INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
>>> INFO  [alembic.runtime.migration] Will assume transactional DDL.
>>> Current revision for postgresql://user:***@localhost/mydb: None

第 4 步：（生成迁移脚本）

alembic revision -m "创建用户表"

>>> Generating /project/migrations/versions/5506a3d76c0e_创建用户表.py ... done

打开生成的迁移文件：

def upgrade():
    # 手动添加 SQL 操作
    op.create_table(
        'users',
        Column('id', Integer, primary_key=True),
        Column('name', String(50))
    )

def downgrade():
    op.drop_table('users')

第 5 步：自动生成脚本（高级技巧）

在 env.py 添加模型导入：

from models import Base  # 导入你的 SQLAlchemy 模型
target_metadata = Base.metadata

生成自动迁移：

alembic revision --autogenerate -m "自动生成用户表"

>>> INFO  [alembic.autogenerate.compare] Detected added table 'users'
>>> Generating /project/migrations/versions/8a3d2e1f_自动生成用户表.py ... done

第 6 步：（运行迁移）

alembic upgrade head

>>> INFO  [alembic.runtime.migration] Running upgrade  -> 5506a3d76c0e, 创建用户表
>>> INFO  [alembic.runtime.migration] Running upgrade 5506a3d76c0e -> 8a3d2e1f, 自动生成用户表

第 7 步：（回滚操作）

alembic downgrade -1

>>> INFO  [alembic.runtime.migration] Running downgrade 8a3d2e1f -> 5506a3d76c0e, 自动生成用户表

第 8 步：（查看历史）

alembic history --verbose

Rev: 8a3d2e1f (head)
Parent: 5506a3d76c0e
Path: migrations/versions/8a3d2e1f_auto_生成用户表.py

    自动生成用户表

Rev: 5506a3d76c0e
Parent: <base>
Path: migrations/versions/5506a3d76c0e_创建用户表.py

    创建用户表

第 9 步：（删除迁移）

# 删除所有迁移文件
rm -rf migrations/versions/*

# 重置数据库版本
alembic downgrade base

>>> INFO  [alembic.runtime.migration] Running downgrade 5506a3d76c0e -> , 创建用户表

---

常见问题急救包

1. 自动生成不工作？

   • 检查 target_metadata 是否正确导入模型
   • 确认模型类是否继承自 Base = declarative_base()

2. 迁移冲突怎么办？

# 手动解决冲突后标记为完成
alembic stamp head

3. 生产环境迁移规范

# 生成 SQL 文件供 DBA 审核
alembic upgrade head --sql > migration.sql

学习路线推荐

• 官方文档：https://alembic.sqlalchemy.org/en/latest/

---