分支管理

使用 Supabase 分支来测试和预览变更

使用分支功能安全地对您的 Supabase 项目进行变更实验。

Supabase 分支的工作方式类似于 Git 分支。它们允许您在独立的临时实例中创建和测试变更，例如新配置、数据库模式或功能，而不会影响生产环境设置。

当您准备好发布变更时，只需合并分支即可用新变更更新生产实例。

如果您了解 Git，您就已经理解了 Supabase 分支功能。

分支工作原理

• 独立环境：每个分支都是独立的环境，拥有自己的 Supabase 实例和 API 凭证。
• Git 集成：分支功能与 Git 协同工作，目前支持 GitHub 仓库。
• 预览分支：您可以创建多个预览分支用于测试。
• 迁移与数据填充：分支会从您的仓库运行迁移，并可以使用 seed.sql 文件填充数据。

先决条件

• Supabase 项目：您需要拥有一个现有的 Supabase 项目。
• GitHub 仓库：您的项目必须连接到一个包含 Supabase 目录的 GitHub 仓库。

您可以为每个 Supabase 项目运行多个预览分支。这些分支包含所有 Supabase 功能，并拥有各自的 API 凭证。

预览环境在5分钟无活动后将自动暂停。当收到对数据库或 REST API 的新请求时，暂停的分支将自动恢复以处理请求。这种架构意味着：

• pg_cron 任务不会在自动暂停的数据库中执行。
• 由于数据库冷启动，请求延迟可能出现较大波动。

如果您需要在预览环境中获得更高的性能保证，可以将单个分支切换为持久化模式，这样它们就不会自动暂停。

分支工作流程

预览分支实例默认不包含任何数据。在创建预览分支时，您必须包含一个种子文件来为预览实例填充示例数据。未来版本的分支功能可能会在我们确信能够提供安全的数据屏蔽后，支持自动数据填充和克隆功能。

Git 代码托管提供商#

为了管理代码变更，您的 Supabase 项目必须连接到 Git 代码仓库。当前阶段，我们仅支持 GitHub。如果您对其他 Git 提供商感兴趣，可以参与关于 GitLab、Bitbucket 以及非 Git 分支方案的讨论。

使用 GitHub 进行分支管理#

Supabase 分支功能通过 GitHub 集成读取您的 GitHub 仓库文件。该集成会监控您 GitHub 仓库的所有提交、分支和拉取请求。

您可以为仓库中的任何 Git 分支创建对应的预览分支。每当基于该分支上的 config.toml 配置创建并设置新的预览分支时，对应 Git 分支的迁移文件都会在该预览分支上运行。

默认情况下，如果存在 ./supabase/seed.sql 文件，预览分支还会使用该文件中的种子数据进行初始化。

Supabase 分支遵循主干开发(Trunk Based Development)工作流，包含一个主生产分支和多个开发分支：

当您将 Git 分支合并到生产分支时，所有新迁移都将应用到生产环境。如果在 config.toml 中声明了存储桶或边缘函数，它们也会自动部署。默认情况下，其他配置（包括 API、Auth 和种子文件）将被忽略。

准备您的 Git 仓库#

您可以使用 Supabase CLI 来管理本地 ./supabase 目录中的变更：

1
supabase init

1
2
3
4
supabase db pull --db-url <db_connection_string># 数据库连接字符串格式如下：# postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres

1
2
3
git add supabasegit commit -m "初始迁移"git push

启用 Supabase 分支功能#

当您的代码仓库准备就绪后，您可以从 Supabase 仪表板启用分支功能。

创建拉取请求

当您在 GitHub 上创建拉取请求时，Supabase 集成会自动检查是否存在匹配的预览分支。如果不存在，则会自动创建。

系统会在您的 PR 中添加一条评论，显示预览分支的部署状态。数据库、服务和 API 的状态会分别显示。

每次推送新提交并修改了 ./supabase/migrations 中的迁移文件时，新的迁移都会在预览分支上运行。您可以在评论的任务表中查看这些运行的执行状态。

防止迁移失败

我们强烈建议为 Supabase 集成开启"必需检查"功能。您可以在 GitHub 仓库设置中完成此操作。这可以防止在迁移检查失败时合并 PR，避免无效的迁移被合并到生产分支。

手动创建预览分支

预览分支会为每个拉取请求自动创建，但您也可以手动创建。

Git集成会监视supabase目录中的变更，包括：

• migrations子目录下的所有SQL迁移文件
• 可选的seed.sql文件，用于为预览实例填充示例数据

您可以通过本地开发或远程开发创建新迁移。推荐使用本地开发方式。

1
supabase start

1
supabase db diff -f "add_employees_table"

1
supabase db reset

1
2
3
git add supabase/migrationsgit commit -m "添加员工表"git push --set-upstream origin new-employee

禁用分支功能

您可以随时禁用分支功能。通过顶部导航栏中的"Branches"下拉菜单进入分支管理页面，然后点击菜单中的"Manage Branches"。在概览部分顶部点击"Disable branching"按钮即可禁用。

持久化分支

持久化分支是指即使底层PR关闭后仍保持活跃的分支类型。任何基于持久化分支的PR都会自动创建对应的预览分支。

您可以在分支管理页面上将任何分支改为持久化分支，只需点击目标分支旁边的三点图标，选择"Switch to persistent"即可。

所有持久化分支都可以通过完全相同的方式切换回临时分支。

迁移与种子数据行为

迁移会按顺序执行。每个迁移都建立在前一个迁移的基础上。

预览分支会记录已应用的迁移，并且只为每个提交应用新的迁移。这在回滚迁移时可能会产生问题。

使用 ORM 或自定义种子脚本#

如果您希望使用自己的 ORM 来管理迁移和种子脚本，需要在 GitHub Actions 中等待预览分支准备就绪后运行它们。可以通过以下示例 GHA 工作流获取分支凭证。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
on:  pull_request:    types:      - opened      - reopened      - synchronize    branches:      - main    paths:      - 'supabase/**'jobs:  wait:    runs-on: ubuntu-latest    outputs:      status: ${{ steps.check.outputs.conclusion }}    steps:      - uses: fountainhead/action-wait-for-check@v1.2.0        id: check        with:          checkName: Supabase Preview          ref: ${{ github.event.pull_request.head.sha }}          token: ${{ secrets.GITHUB_TOKEN }}  migrate:    needs:      - wait    if: ${{ needs.wait.outputs.status == 'success' }}    runs-on: ubuntu-latest    steps:      - uses: supabase/setup-cli@v1        with:          version: latest      - run: supabase --experimental branches get "$GITHUB_HEAD_REF" -o env >> $GITHUB_ENV      - name: Custom ORM migration        run: psql "$POSTGRES_URL_NON_POOLING" -c 'select 1'

通过远程配置分支

当启用分支功能时，您的 config.toml 设置会通过 Git 分支与 Supabase 分支的一对一映射自动同步到所有临时分支。

基础配置

要更新 Supabase 分支的配置，只需修改 config.toml 并推送到 git。Supabase 集成将检测变更并将其应用到对应的分支。

远程特定配置

对于需要特定设置的持久分支，您可以在 config.toml 中使用 [remotes] 块。每个远程配置必须引用一个已存在的项目ID。

以下是为暂存环境配置独立种子脚本的示例：

1
2
3
4
5
[remotes.staging]project_id = "your-project-ref"[remotes.staging.db.seed]sql_paths = ["./seeds/staging.sql"]

由于 project_id 字段必须引用已存在的分支，您需要先创建持久分支再添加其配置。首先使用CLI创建持久分支：

1
2
3
supabase --experimental branches create --persistent# 是否要创建名为 develop 的分支？[Y/n]

配置合并

当将PR合并到持久分支时，Supabase集成会：

1. 检查配置变更
2. 记录变更
3. 将变更应用到目标远程

如果未声明远程或项目ID不正确，则跳过配置步骤。

可用配置选项

所有标准配置选项都可在 [remotes] 块中使用，包括：

• 数据库设置
• API配置
• 认证设置
• 边缘函数配置
• 以及其他更多选项

您可以使用此功能为不同环境维护不同的配置，同时将它们都保留在版本控制中。

回滚迁移

您可能需要回滚早期迁移变更。例如，您可能推送了包含不再需要的模式变更的迁移文件。

要解决此问题，推送最新变更后，在Supabase中删除预览分支并重新打开它。

新的预览分支默认会从您的 ./supabase/seed.sql 文件重新种子化。您在旧预览分支上所做的任何额外数据变更都将丢失。这相当于在本地运行 supabase db reset。所有迁移都会按顺序重新运行。

种子数据行为

您的预览分支会使用与本地种子数据行为相同的方式填充示例数据。

数据库仅在创建预览分支时进行一次种子数据填充。如需重新运行种子填充，请删除预览分支并通过关闭并重新打开您的拉取请求来重新创建它。

分支与托管服务提供商

分支功能适用于支持预览部署的托管服务提供商。

通过Supabase分支集成，您可以将托管服务提供商使用的Git分支与相应的Supabase预览分支同步。这意味着由托管服务提供商构建的预览部署会匹配正确的数据库模式、边缘函数和其他Supabase配置。

Vercel#

安装Vercel集成：

• 通过Vercel应用市场或
• 点击Supabase示例应用README文件中的蓝色Deploy按钮

并确保您已连接Supabase项目到Vercel项目。

Supabase会自动为相应的预览分支更新Vercel项目中的环境变量。同步操作发生在拉取请求打开时，而非分支创建时。

由于分支集成与Vercel的预览部署功能相关联，在Supabase设置正确变量与Vercel运行部署过程之间可能存在竞态条件。因此，Supabase总是会自动重新部署给定拉取请求的最新部署。

其他Git提供商#

我们正在考虑多种替代的Git提供商方案。如果您对GitLab、Bitbucket或其他提供商的分支功能感兴趣，请加入GitHub讨论。

分支的替代方案

从底层来看，您可以将Supabase分支视为通过git流程以编程方式"复制"您的Supabase项目的方法。这允许生成一个新的数据库实例及相关的Supabase服务（存储桶、边缘函数等），这些实例都经过config.toml配置并预填充了数据。

1. 如果分支尚不存在，Supabase会代表用户部署一个新项目作为"分支"。这包括数据库、存储、边缘函数和所有Supabase相关服务。
2. 分支被克隆，新项目基于提交到该分支的config.toml进行配置。
3. 迁移脚本会被应用，种子脚本会首次为该分支运行。

您可以为每个环境创建类似但独立的项目设置。或者只需维护两个环境：本地开发环境和生产环境。

定价

分支功能在Pro计划及以上版本可用。具体价格为：

• 每个预览分支每天花费$0.32
• 每个预览分支会持续计费直到被删除

故障排除

回滚迁移

您可能需要回滚早期迁移中所做的更改。例如，您可能推送了一个包含不再需要的模式变更的迁移文件。

要解决此问题，请推送最新更改，然后在Supabase中删除预览分支并重新打开它。

新的预览分支默认会从./supabase/seed.sql文件重新填充数据。旧预览分支上所做的任何额外数据更改都将丢失。这相当于在本地运行supabase db reset命令。所有迁移将按顺序重新运行。

部署失败

部署可能因多种原因失败，包括迁移中的无效SQL语句和模式冲突、config.toml配置中的错误，或其他问题。

要查看错误信息，请在查看日志部分检查您分支的Supabase工作流运行情况。

网络限制

如果在项目中启用了网络限制，默认情况下分支集群将被阻止连接到您的项目。这通常会导致在合并开发分支后迁移生产项目时出现数据库连接失败。

解决方法是在项目的数据库设置页面明确允许分支集群的IPv6 CIDR范围：2600:1f18:2b7d:f600::/56

预览分支间的模式漂移

如果存在多个预览分支，每个预览分支可能包含不同的模式变更。这与Git分支类似，每个分支可能包含不同的代码变更。

当预览分支合并到生产分支时，会在生产分支与尚未合并的预览分支之间产生模式漂移。

这些冲突可以通过与普通Git冲突相同的方式解决：从生产Git分支合并或变基到预览Git分支。由于迁移是按顺序应用的，请确保在变基后正确时间戳迁移文件。基于早期变更的更改应始终具有更晚的时间戳。

更改生产分支

在 Supabase 分支功能中，无法直接更改用作生产分支的 Git 分支。唯一的方法是先禁用再重新启用分支功能。具体操作请参考禁用分支部分。

反馈

Supabase 分支功能是 Supabase 开发生态系统中令人兴奋的新特性。我们欢迎您提供宝贵意见。

您可以参与GitHub 讨论区的对话。