Source: Dev.to

为什么 Alembic 基本上是你数据库的 Git，且你真的需要它

在现代的 Web 开发中，数据库迁移（database migrations）已经成为不可或缺的工具。它们让我们能够：

• 版本化 数据库模式（schema），就像 Git 版本化代码一样；
• 在团队中协作，确保每个人的本地数据库结构保持一致；
• 安全地回滚（rollback）错误的更改；
• 在 CI/CD 流水线 中自动执行迁移。

Alembic 正是为此而生的。它是 SQLAlchemy 生态系统中的迁移工具，但它的理念和使用方式让人联想到 Git。

下面我们来详细看看 Alembic 为什么可以被称作“数据库的 Git”，以及在实际项目中它能为我们解决哪些痛点。

1. Alembic 与 Git 的相似之处

正是因为这种一一对应的关系，Alembic 能够让我们像管理代码一样管理数据库结构。

2. 为什么你需要 Alembic

2.1 防止“数据库漂移”

在没有迁移工具的项目里，团队成员往往手动修改数据库（ALTER TABLE、CREATE INDEX 等），导致：

• 本地环境与生产环境不一致；
• 难以追踪谁在什么时候做了哪些更改；
• 迁移到新机器时需要手动执行大量 SQL。

Alembic 把这些操作写进 迁移脚本，每一次更改都有明确的记录，避免了所谓的“数据库漂移”。

2.2 自动化 CI/CD

在持续集成/持续部署（CI/CD）流程中，你可以：

alembic upgrade head   # 在部署前自动把数据库升级到最新版本

如果迁移失败，CI 会直接报错，阻止错误的代码进入生产环境。

2.3 安全的回滚机制

当某次迁移导致业务故障时，只需要：

alembic downgrade -1   # 回滚到上一个版本

这比手动编写 DROP TABLE、ALTER COLUMN 更可靠，也更易于审计。

2.4 与 SQLAlchemy 完美集成

因为 Alembic 是为 SQLAlchemy 设计的，它可以直接读取模型（model）元数据，自动生成迁移脚本的 autogenerate 功能：

alembic revision --autogenerate -m "add users table"

这让我们在模型层面做出更改后，只需一条命令即可得到对应的迁移脚本。

3. Alembic 的核心概念

3.1 Revision（修订）

每个迁移文件都有一个唯一的 revision ID（类似 Git 的 commit hash），以及指向前一个修订的 down_revision。

# versions/3b1f2c4e5a6b_add_users_table.py
revision = '3b1f2c4e5a6b'
down_revision = '2a9d8e7f6c5b'
branch_labels = None
depends_on = None

3.2 Upgrade / Downgrade

每个迁移文件必须实现两个函数：

def upgrade():
    op.create_table(
        "users",
        sa.Column("id", sa.Integer, primary_key=True),
        sa.Column("email", sa.String(255), nullable=False, unique=True),
    )

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

• upgrade：把数据库升级到此版本；
• downgrade：把数据库降级到上一个版本。

3.3 环境配置（alembic.ini & env.py）

• alembic.ini：全局配置文件，包含数据库 URL、日志级别等；
• env.py：运行时环境脚本，负责加载 SQLAlchemy engine、metadata，以及决定是 offline 还是 online 模式。

4. 常见工作流示例

4.1 初始化项目

alembic init alembic

这会在项目根目录生成 alembic/ 目录和 alembic.ini。

4.2 创建第一次迁移

alembic revision -m "initial schema"

编辑生成的文件，写入 upgrade/downgrade 逻辑，或使用 --autogenerate 自动生成。

4.3 应用迁移

alembic upgrade head   # 将数据库升级到最新版本

4.4 回滚最近一次迁移

alembic downgrade -1

4.5 在分支上工作

假设 feature/login 分支需要新增 sessions 表：

# 在 feature/login 分支
alembic revision -m "add sessions table"
# 完成后提交迁移文件
git add alembic/versions/xxxx_add_sessions_table.py
git commit -m "Add sessions table migration"

当 feature/login 合并回 main 时，迁移文件会随代码一起合并，保持数据库结构同步。

5. 处理冲突的技巧

和 Git 合并冲突类似，Alembic 也可能出现 revision 冲突（两个分支各自生成了相同 down_revision 的迁移）。解决办法：

1. 手动编辑冲突的迁移文件，确保 down_revision 指向正确的前置版本；
2. 使用 alembic merge 命令创建一个合并迁移：

alembic merge -m "merge login and payment migrations" \
    <revision-id-1> <revision-id-2>

这会生成一个新的迁移文件，down_revision 为两个冲突的 revision，起到“合并节点”的作用。

6. 最佳实践

7. 小结

• Alembic 把数据库模式的演进抽象为 revision，让我们像使用 Git 管理代码一样管理数据库；
• 它提供 升级、降级、分支、合并 等完整的版本控制能力；
• 在团队协作、CI/CD、回滚容错等场景中，Alembic 能显著降低出错概率，提高开发效率。

如果你还在手动执行 ALTER TABLE，或者在部署时经常因为数据库结构不一致而卡住，那么现在就把 Alembic 加入你的技术栈吧——它会让你的数据库管理像代码一样可预测、可回溯、可协作。祝你迁移顺利！

Alembic：为你的数据库提供版本控制

问题

这是一个星期五的傍晚。你终于点击了 Deploy，部署了整整一周一直在开发的功能，应用上线了。一切看起来都很完美——大约两分钟后，错误日志开始亮起。

罪魁祸首？ 有人忘记在生产数据库上运行关键的 ALTER TABLE SQL 脚本。

开发者对代码一丝不苟：我们使用 Git 跟踪每一个字符的改动，审查 Pull Request，管理分支。而在 数据库模式 上，情况往往一团糟。我们往往：

• 依赖记忆
• 在 Slack 中复制粘贴查询语句
• 共享命名不规范的文件，如 db_update_final_v3.sql

如果你在 Python 生态系统中工作（尤其是使用 SQLAlchemy），有一种更好的方式：Alembic。

什么是 Alembic？

Alembic = 为你的数据库提供版本控制

与其手动登录数据库管理工具并手动修改表结构，Alembic 让你在 Python 脚本 中定义模式变更。

快速示例

想象你正在构建一个用户认证系统。

几个月后，产品团队希望添加一个 last_login_date 列。

没有 Alembic

• 手动运行 SQL 命令。
• 希望团队其他成员记得在本地机器上运行相同的命令。

使用 Alembic

1. 在终端生成一个新的迁移脚本：

   alembic revision -m "add last login date to users"

2. Alembic 会创建一个新文件，包含两个核心函数：

   def upgrade():
       # code to add the column
       pass
   
   def downgrade():
       # code to remove the column
       pass

3. 编写相应的 upgrade() 和 downgrade() 逻辑，然后像对待其他代码一样 commit 到 Git。

4. 当同事拉取分支后，只需运行：

   alembic upgrade head

   他们的本地数据库会自动更新为与你相同的状态——无需猜测，也不会出现环境破损。

好处

• 安心 – 清晰、一步步的数据库演进历史。
• “撤销”按钮 – 只需一条 downgrade 命令，即可瞬间回滚到之前的安全版本。
• 不再同步问题 – 消除经典的 “在我机器上可以运行” 争论。

常见的成长痛点

尽管有这些小障碍，一旦你开始对数据库进行版本控制，你会惊讶于自己以前是如何在没有它的情况下生存的。

Source: …

缅甸语版本

Alembic：为你的数据库提供 Git（为什么要使用） 🗄️

问题

假设在星期五晚上，你把一周辛苦写好的新功能部署了。应用启动后，两三分钟内就出现了错误日志。

问题出在哪里？ 生产数据库里忘记执行 ALTER TABLE 之类的 SQL 脚本。

很多开发者会用 Git 精确跟踪代码的改动、审查 PR、分支管理，然而 数据库模式 往往会变得异常混乱。

• 只靠记忆
• 在 Slack 上复制‑粘贴查询并发送
• 使用像 db_update_final_v3.sql 这样的文件名

Alembic 是什么？

Alembic = 你的数据库的版本控制

与其手动进入数据库管理工具逐个修改表结构，不如使用 Alembic 编写 Python 脚本 来描述想要的变更。

示例 – 用户认证系统

过了一段时间，产品团队想要添加 last_login_date 列…

如果没有 Alembic

• 手动运行 SQL 命令
• 其他团队成员可能忘记执行，导致不同步

如果使用 Alembic

1. 在终端生成新的迁移脚本：

   alembic revision -m "add last login date to users"

2. Alembic 会自动创建一个包含 upgrade() 与 downgrade() 两个函数的文件：

   def upgrade():
       # 添加列的代码
       pass
   
   def downgrade():
       # 删除列的代码
       pass

3. 在这两个函数里写入所需代码，然后像其他代码一样提交到 Git。

4. 团队成员拉取该分支后执行 alembic upgrade head，他们本地的数据库就会与目标数据库完全一致——无需手动估算，也不会出现本地环境被破坏的情况。

好处

• 安心 – 从数据库创建之初到现在的每一次变更都能清晰追溯。
• 可撤销 – 部署时如果新 schema 出现问题，只需执行 downgrade 命令即可回到之前的状态。
• 消除同步问题 – 再也没有 “我的数据库在我的机器上能跑” 这种借口。

面临的挑战

开始使用后的感受

克服这些挑战后，你就可以正式对 数据库进行版本控制。当有人问你 “你是怎么做到的？” 时，你将会惊喜地体会到这些收益带来的巨大价值。

摘要

• Rollback
  只需一行代码，即可立即回滚到之前安全的状态（Rollback）。

• Sync 问题消除
  “我的机器上的数据库工作正常”之类的拒绝将会彻底消失。

• 困难点
  确实，所有事物都会有一些小困难。

  • 初期需要花一点时间学习。
  • 为了轻松删除一列，需要学习 Alembic 的特定写法，可能会觉得工作量增加。

• Multiple Head Error
  如果两位开发者在同一时间从不同分支生成新的迁移脚本，合并时会出现 “multiple head” 错误。这类似于 Git 的合并冲突，需要手动解决。

• 结论
  尽管有这些细小的困难，但只要尝试对数据库进行版本控制，就会回想起以前是如何在没有这些工具的情况下工作的。