Alembic 使用指南

井九

发布于 2026-07-08 12:20:09

文章被收录于专栏：四楼没电梯四楼没电梯

什么是 Alembic
为什么需要 Alembic
Alembic 工作原理
安装
初始化项目
配置数据库
创建第一个 Migration
升级数据库
回滚数据库
自动生成 Migration
修改 Migration
数据迁移
Branch（分支）
Merge（合并）
Stamp 的使用
常用命令
env.py 详解
与 SQLAlchemy 结合
FastAPI 中使用
多数据库支持
企业最佳实践
常见问题

一、什么是 Alembic

Alembic 是 SQLAlchemy 官方维护的数据库版本管理工具（Migration Tool）。

作用类似：

Django Migration
Laravel Migration
Flyway
Liquibase

它负责：

让数据库结构像代码一样可以进行版本控制。

例如：

今天数据库

user
------
id
name

明天增加

email

Alembic 会记录：

V1
↓

V2
↓

V3

任何时候都可以：

升级
回滚
查看历史

二、为什么需要 Alembic

假设没有 Migration。

开发：

ALTER TABLE user
ADD email varchar(100);

测试：

ALTER TABLE user
ADD phone varchar(20);

线上：

忘了执行……

于是：

代码
↓

找不到字段

↓

程序崩溃

Migration 就是解决这个问题。

三、Alembic 工作原理

真正执行的是：

Migration Script

不是 Model。

四、安装

pip install alembic

如果没有 SQLAlchemy：

pip install sqlalchemy

FastAPI：

pip install fastapi sqlalchemy alembic

五、初始化项目

执行：

alembic init alembic

生成：

project/

    alembic/

        versions/

        env.py

        script.py.mako

    alembic.ini

目录说明：

alembic.ini

↓

数据库配置

----------------

env.py

↓

迁移入口

----------------

versions

↓

所有 Migration

六、配置数据库

修改：

alembic.ini

例如：

sqlalchemy.url = mysql+pymysql://root:123456@127.0.0.1/demo

更推荐：

不要写死。

修改：

env.py

例如：

from app.config import settings

config.set_main_option(
    "sqlalchemy.url",
    settings.DATABASE_URL
)

这样：

开发

测试

生产

都可以使用不同配置。

七、SQLAlchemy Model

例如：

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy import Column,Integer,String

class Base(DeclarativeBase):
    pass


class User(Base):

    __tablename__="user"

    id=Column(Integer,primary_key=True)

    name=Column(String(50))

env.py：

from app.models import Base

target_metadata = Base.metadata

这一步非常重要。

Alembic 自动比较：

数据库

VS

metadata

八、创建 Migration

手动：

alembic revision -m "create user"

生成：

versions/

20260628_create_user.py

里面：

def upgrade():
    pass

def downgrade():
    pass

自己写：

from alembic import op
import sqlalchemy as sa

def upgrade():

    op.create_table(
        "user",

        sa.Column("id",sa.Integer(),primary_key=True),

        sa.Column("name",sa.String(50))
    )

def downgrade():

    op.drop_table("user")

九、自动生成 Migration

十、升级数据库

十一、查看历史

alembic history

输出：

v1

↓

v2

↓

v3

查看当前：

alembic current

查看 head：

alembic heads

十二、回滚数据库

回退一步：

alembic downgrade -1

回退指定版本：

alembic downgrade 6b3c1f

全部删除：

alembic downgrade base

流程：

十三、修改 Migration

例如：

新增：

age

生成：

def upgrade():

    op.add_column(

        "user",

        sa.Column("age",sa.Integer())
    )

删除：

op.drop_column(
    "user",
    "age"
)

修改字段：

op.alter_column(
    "user",
    "name",
    nullable=False
)

十四、数据迁移

Migration 不只是修改表。

还可以修改数据。

例如：

from alembic import op

def upgrade():

    conn=op.get_bind()

    conn.execute(

        sa.text(

        """
        UPDATE user

        SET age=18

        WHERE age IS NULL
        """
        )

    )

这是企业里最常见的操作。

十五、Branch（分支）

多人开发：

A：

V1

↓

V2

B：

V1

↓

V3

变成：

Alembic：

Multiple Heads

查看：

alembic heads

十六、Merge

合并：

alembic merge heads -m "merge branch"

变成：

以后：

upgrade head

不会报错。

十七、Stamp

有时候：

数据库已经存在。

但是没有 Migration。

可以：

alembic stamp head

作用：

只记录版本

不执行 SQL

非常适合：

旧项目接入 Alembic。

十八、env.py 工作流程

env.py：

负责：

创建 Engine
获取 Metadata
比较数据库
执行 Migration

十九、常用命令

命令	说明
init	初始化
revision	创建 Migration
revision --autogenerate	自动生成
upgrade head	升级
downgrade	回滚
history	历史
current	当前版本
heads	多个 Head
merge	合并
stamp	记录版本

二十、FastAPI 集成

项目：

app/

models/

config.py

main.py

alembic/

config：

DATABASE_URL="mysql+pymysql://..."

env.py：

from app.models import Base
from app.config import DATABASE_URL

target_metadata=Base.metadata

config.set_main_option(
    "sqlalchemy.url",
    DATABASE_URL
)

部署：

docker

↓

启动

↓

alembic upgrade head

↓

启动 FastAPI

二十一、多数据库

env.py：

DATABASE_URLS={

    "master":"...",

    "report":"..."
}

分别执行：

upgrade(master)

upgrade(report)

企业常见：

主库
日志库
BI 库

二十二、最佳实践

永远使用 Autogenerate

alembic revision --autogenerate

不要全部手写。

检查 Migration

自动生成并不是万能。

例如：

字段改名：

name

↓

username

Alembic：

可能：

drop

+

create

而不是：

rename

需要人工修改。

一个功能一个 Migration

不要：

1000 行

建议：

新增订单

↓

一个 Migration

新增支付

↓

一个 Migration

方便回滚。

不要修改历史 Migration

已经上线：

20250101_create_user.py

不要再修改。

新增：

20250203_add_email.py

Migration 要进入 Git

必须提交：

versions/

否则：

其他开发无法同步数据库。

CI/CD 自动执行

部署：

git pull

pip install -r requirements.txt

alembic upgrade head

systemctl restart app

二十三、常见问题

为什么 autogenerate 没检测到？

一般原因：

没有设置：

target_metadata

为什么提示 Multiple Heads？

多人同时开发。

执行：

merge

即可。

为什么 downgrade 失败？

因为：

upgrade 写了：

create_table

但是：

downgrade 没写：

drop_table

为什么删除字段后数据丢失？

Migration 本质执行：

ALTER TABLE

DROP COLUMN

无法恢复。

建议：

先：

rename

↓

备份

↓

删除

二十四、企业推荐工作流

总结

Alembic 是 SQLAlchemy 官方推荐的数据库迁移工具，它通过维护数据库版本脚本，实现数据库结构与代码同步演进。熟练掌握 Alembic 不仅可以完成字段新增、删除、修改等基础操作，还能应对多人协作、分支合并、数据迁移、CI/CD 自动部署等企业级场景。

建议遵循以下原则：

使用 --autogenerate 自动生成迁移脚本，再人工审核
每次业务变更对应一个独立 Migration
历史 Migration 一旦上线，不再修改
将 versions/ 纳入 Git 版本控制
在 CI/CD 中自动执行 alembic upgrade head
对涉及数据变更的 Migration，务必编写可回滚逻辑并充分测试

掌握这些实践后，Alembic 将成为团队数据库版本管理的核心工具，帮助项目在持续迭代中保持数据库结构的一致性、可追溯性和可维护性。

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2026-07-07，如有侵权请联系 cloudcommunity@tencent.com 删除

配置

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度