---
title: "Alembic"
created: 2026-07-17
tags:
  - 项目筑基
---
# Alembic

> **Alembic 是 SQLAlchemy 官方推荐的数据库迁移（Migration）工具，用于以版本化的方式管理数据库表结构的变更。**

Alembic 由 SQLAlchemy 的作者 Mike Bayer 开发，专门解决一个开发中的常见痛点：**当你的数据模型（表结构）发生变化时，如何安全、可追溯地把这些变化同步到数据库，而不是手动写 SQL 或者直接删库重建。** 它把每一次结构变更都记录成一个"版本"，就像 Git 管理代码一样管理你的数据库 schema。

### **它到底解决什么问题**

在实际项目里，数据库表结构会不断演进：今天加一个字段，明天改一个字段类型，后天新建一张表。如果没有工具管理，你会面临几个麻烦：团队成员之间的数据库结构不一致、线上和本地环境对不上、想回退到之前的结构却无从下手。Alembic 通过"迁移脚本 + 版本链"的机制解决这些问题，每个变更都有唯一版本号，并记录它的上一个版本，从而形成一条可以随时向前（upgrade）或向后（downgrade）移动的链条。

### **核心概念**

理解 Alembic 主要抓住下面几个概念：

| 概念 | 说明 |
| --- | --- |
| Migration Script（迁移脚本） | 每次结构变更生成的一个 Python 文件，包含 `upgrade()` 和 `downgrade()` 两个函数 |
| Revision（版本） | 每个脚本的唯一标识（如 `a1b2c3d4`），并记录 `down_revision` 指向上一个版本 |
| `alembic_version` 表 | Alembic 在你的数据库里自动建的一张表，记录当前数据库处于哪个版本 |
| `env.py` | 迁移运行时的配置入口，连接数据库、指定 metadata 等 |
| Autogenerate | 自动对比模型和数据库现状，生成迁移脚本的功能 |

### **典型工作流程**

一个最常见的使用流程是这样的。首先初始化环境，生成 Alembic 的目录结构：

```
alembic init alembic
```

然后在 `env.py` 里把你的模型 metadata 关联进来，之后每当你修改了 SQLAlchemy 的模型定义，就可以让 Alembic 自动比对差异并生成迁移脚本：

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

生成的脚本大致长这样，`upgrade` 描述如何应用变更，`downgrade` 描述如何回退：

```python
def upgrade():
op.add_column('users', sa.Column('email', sa.String(length=120)))
def downgrade():
op.drop_column('users', 'email')
```

最后把变更应用到数据库，或在需要时回退：

```
alembic upgrade head # 升级到最新版本
alembic downgrade -1 # 回退一个版本
```

### **需要注意的点**

Autogenerate 虽然强大，但它**不是万能的**——它能检测到新增/删除表、新增/删除列等常见变更，但对于列改名、某些约束变化、服务端默认值等情况可能识别不准，因此每次生成脚本后都建议人工检查一遍再执行。此外，`downgrade` 逻辑需要你自己保证正确性，尤其是涉及数据迁移（而不仅仅是结构变更）时，回退可能造成数据丢失，要格外谨慎。

总的来说，如果你在用 Python 做后端开发、特别是搭配 SQLAlchemy 或 FastAPI/Flask 这类框架，Alembic 几乎是管理数据库结构演进的标准配置。它让数据库变更变得像代码一样可版本化、可协作、可回滚。

---
⬅️ [[03-RAG 检索增强生成|03-RAG 检索增强生成]] 🏠 [[00-数据库|00-数据库]] ➡️ [[00-工具与环境|00-工具与环境]]