Gel `branch rebase` 详解：基于目标分支重建当前分支的数据库迁移工作流-平芜编程栈

数据库
图数据库
关系型数据库

【免费下载链接】edgedb

Gel supercharges Postgres with a modern data model, graph queries, Auth & AI solutions, and much more.

项目地址：https://gitcode.com/gh_mirrors/ed/edgedb

导读

gel branch rebase是 Gel 分支管理命令组（gel branch）中的核心命令之一，用于以目标分支为基础、叠加当前分支上的新迁移来重建当前分支，从而让特性分支与主线分支在迁移历史上重新对齐。本文基于 gel_branch_rebase.rst 参考文档展开，并结合仓库中的迁移指南与分支入门指南剖析其底层实现机制。读完本文，你将掌握该命令的完整语义、参数用法、与git rebase配对的实战流程，以及它为快速合并（fast-forward merge）铺路的设计原理。

命令概览与语法

gel branch rebase在当前连接的 Gel 实例上执行，其 synopsis 如下：

gel branch rebase [<options>] <name>

<name>：目标分支的名称。命令会以该目标分支为基础，重新应用当前分支上的新迁移，生成重建后的当前分支。
<options>：用于指定连接目标的选项。该命令运行在它连接到的 Gel 实例上，连接目标的指定方式请参考 connection options（连接选项）所指向的 CLI 连接选项文档。

从命令组定位来看，gel branch rebase属于 gel branch 命令组的八个子命令之一（create / drop / list / merge / rebase / rename / switch / wipe），该组用于分支的创建、销毁、罗列、合并、重建、重命名、切换与清空。

核心语义：Schema、迁移与数据三者如何取舍

参考文档给出了一段关键说明（原文 note）：

当执行 rebase 时，目标分支的数据会被保留。也就是说，如果你切换到feature分支并运行gel branch rebase main，最终你会得到一个：schema 来自main、新增迁移来自feature、数据来自main的分支。

这句话需要仔细拆解——它与branch merge恰好形成镜像：

操作	当前分支	目标分支	结果
`gel branch rebase main`（在`feature`上执行）	`feature`（新迁移）	`main`（schema + 数据）	schema 与数据来自`main`，叠加`feature`的新迁移
`gel branch merge feature`（在`main`上执行）	`main`（schema + 数据）	`feature`（新迁移）	schema 与数据来自`main`，叠加`feature`的新迁移

可以看到，两种操作最终都得到“目标分支的 schema/数据 + 当前分支的新迁移”，区别只在于操作后哪个分支存续：merge原地演进当前分支，rebase则是用重建结果替换当前分支。

需要强调的是，“数据来自目标分支”意味着 rebase不是把当前分支的数据搬运过去——当前分支上那些不在目标分支迁移历史中的数据修改不会随重建保留。这一点对数据敏感的场景（例如在feature上写入了仅供测试的数据）非常重要，必要时应在 rebase 前先备份或导出相关数据。

底层机制：一条命令背后的四步操作

参考文档将底层原理的详细拆解指向迁移指南中的 "How rebasing works" 一节。gel branch rebase main看似只有一条命令，实则完成了相当复杂的工作，其内部流程为：

克隆目标分支：CLI 先把main分支连同其数据克隆到一个临时分支（记为temp）。
对比迁移历史：内省temp与feature两个分支的迁移历史（migration history），确定二者在迁移链上的分叉点（divergence）。
应用分叉迁移：把feature分支上所有分叉的（divergent）迁移，逐个应用（apply）到temp分支之上。
替换分支：若上述操作全部成功，则删除feature分支，并将temp重命名为feature。

通过这四步，feature的迁移链被“移植”到了main的最新 schema 之上。这一步成功后，后续的合并就变成了纯粹的快速前进（fast-forward），正如迁移指南所述："With the deceptively complicated rebase completed with just that single command, you've stacked the dominoes perfectly for your merge to succeed!"（一条看似简单实则复杂的 rebase 命令，已为你的合并成功完美铺好了多米诺骨牌。）

从数据模型视角看，Gel 的分支（branches）与 PostgreSQL 的数据库（databases）一一对应并直接映射（见 branches.rst）。第 1 步的“克隆分支含数据”在底层 DDL 上等价于create data branch <new> from <old>（创建时复制源分支的 schema 与数据），第 4 步的“删除并重命名”则对应drop branch与alter branch … rename to …。如果想在 REPL 中手动复现 rebase 的语义，可以按此顺序组合使用这些 DDL 语句，但建议优先使用 CLI 命令，因为它会帮你完成迁移历史的对比与重放。

实战工作流：与 Git 分支配对使用

gel branch rebase的典型用法，是与 VCS（以 Git 为例）的特性分支协作。仓库中的分支入门指南给出了完整的五步流程，其中 rebase 是第 4 步：

1. 创建特性分支（VCS + Gel 同步创建）

$ git switch -c feature # 或者 git checkout -b feature $ gel branch create feature Creating branch 'feature'... OK: CREATE BRANCH $ gel branch switch feature Switching from 'main' to 'feature'

也可以一步完成 Gel 侧的创建并切换：gel branch switch -c feature。

2. 开发特性：编写代码，并做特性所需的 schema 修改（通过gel migration create/gel migrate生成并应用迁移）。

3. 拉取主线变更（可选步骤）：切回main代码分支执行git pull；若拉取的内容包含 schema 变更，则切回main数据库分支并执行gel migrate应用新 schema。

提示：如果确认main代码分支是最新的、且其中的迁移都已应用到main数据库分支，第 3 步可以跳过，相应地第 4 步也可跳过。

4. 在feature上执行 rebase（本文核心）：先在 VCS 侧对齐代码，再对齐数据库。

$ git rebase main $ gel branch rebase main

此时 Gel 侧完成上文所述的四步重建：以main为基础、叠加feature的新迁移、保留main的数据。

5. 合并回主线：

$ git switch main && git merge feature $ gel branch switch main Switching from 'feature' to 'main' $ gel branch merge feature

由于第 4 步已经让feature的迁移链以main为基，第 5 步的gel branch merge feature就是一次无冲突的快速前进合并。关于 merge 的细节可参阅 gel_branch_merge.rst：merge 采用 fast-forward 策略，不做冲突解决；因此“如果你想合并但可能存在冲突，应先从目标分支执行gel branch rebase再合并”——这正是 rebase 在整个分支生命周期中的价值所在：在合并前提前消解迁移链分歧。

该工作流在迁移指南的 Branches 一节中被总结为：create → 开发 → 拉取 main 变更 → rebase → merge，且特别说明 branches 是开发新特性或原型实验性功能时隔离 schema 变更的利器——即使这些特性最终不会发布，也可以随时 merge 或 drop 而不影响主线 schema。

选项与连接目标

gel branch rebase的唯一位置参数是目标分支名<name>，即“以哪个分支为基底重建当前分支”。除此之外，命令的可用选项主要来自 CLI 通用的连接参数：

指定实例：--instance <name>（或在项目目录下自动使用项目实例）；
指定用户/数据库/端口/TLS 等连接细节：使用 connection options 中列出的通用连接选项。

由于命令运行在“当前连接到的实例”上，rebase 只能作用于同一实例内的分支；跨实例的迁移对齐不在该命令职责范围内。

边界情况与使用建议

综合参考文档与相关源码文档，使用gel branch rebase时有几点值得注意：

数据以目标分支为准：rebase 保留的是目标分支的数据，当前分支上非迁移产生的数据变化不会保留。执行前请确认当前分支是否有需要留存的数据。
为合并铺路：rebase 的典型前置场景是“main有新迁移、feature也想合并回main”。先在feature上 rebase，可以让随后的branch merge变为快速前进，避免冲突。
与迁移纪律配合：Gel 默认在完成迁移流程后禁止裸 DDL（allow_bare_ddl默认NeverAllow），schema 变更应通过gel migration create/gel migrate纳入迁移历史——因为 rebase 的迁移对比与重放完全依赖规范的迁移历史，绕过迁移体系的手工 DDL 会破坏这一前提（详见迁移指南中的相关讨论，见 guide.rst）。
失败即中止：底层四步流程中，只有全部迁移应用成功才会执行“删除旧分支 + 重命名临时分支”，因此失败不会留下半成品分支覆盖原分支。