处理分支

本指南讲解了如何高效使用 Supabase 分支，包括迁移管理、数据填充行为和开发工作流程。

🌐 This guide covers how to work with Supabase branches effectively, including migration management, seeding behavior, and development workflows.

订阅通知 #

🌐 Subscribing to notifications

当一个操作在持久分支上执行完成时，你可以订阅 webhook 通知。负载格式遵循 webhook 标准。

🌐 You can subscribe to webhook notifications when an action run completes on a persistent branch. The payload format follows the webhook standards.

1
{
2
  "type": "run.completed",
3
  "timestamp": "2025-10-17T02:27:18.705861793Z",
4
  "data": {
5
    "project_ref": "xuqpsshjxdecrwdyuxvs",
6
    "details_url": "https://supabase.nodejs.cn/dashboard/project/xuqpsshjxdecrwdyuxvs/branches",
7
    "action_run": {
8
      "id": "d5f8b4298d0a4d37b99e255c7837e7af",
9
      "created_at": "2025-10-17T02:27:10.133329324Z",
10
      "steps": [
11
        {
12
          "name": "clone",
13
          "status": "exited",
14
          "updated_at": "2025-10-17T02:27:10.788435466Z"
15
        },
16
        {
17
          "name": "pull",
18
          "status": "exited",
19
          "updated_at": "2025-10-17T02:27:11.701742857Z"
20
        },
21
        {
22
          "name": "health",
23
          "status": "exited",
24
          "updated_at": "2025-10-17T02:27:12.79205717Z"
25
        },
26
        {
27
          "name": "configure",
28
          "status": "exited",
29
          "updated_at": "2025-10-17T02:27:13.726839657Z"
30
        },
31
        {
32
          "name": "migrate",
33
          "status": "exited",
34
          "updated_at": "2025-10-17T02:27:14.97017507Z"
35
        },
36
        {
37
          "name": "seed",
38
          "status": "exited",
39
          "updated_at": "2025-10-17T02:27:15.637684921Z"
40
        },
41
        {
42
          "name": "deploy",
43
          "status": "exited",
44
          "updated_at": "2025-10-17T02:27:18.604193114Z"
45
        }
46
      ]
47
    }
48
  }
49
}

我们建议注册一个单一的 webhooks 处理器，根据负载类型将事件分发到下游服务。最简单的方法是部署一个 Edge Function。例如，下面的 Edge Function 会监听运行完成事件，以通知 Slack 通道。

🌐 We recommend registering a single webhooks processor that dispatches events to downstream services based on the payload type. The easiest way to do that is by deploying an Edge Function. For example, the following Edge Function listens for run completed events to notify a Slack channel.

1
// Setup type definitions for built-in Supabase Runtime APIs
2
import 'jsr:@supabase/functions-js/edge-runtime.d.ts'
3
4
console.log('Branching notification booted!')
5
const slack = Deno.env.get('SLACK_WEBHOOK_URL') ?? ''
6
7
Deno.serve(async (request) => {
8
  const body = await request.json()
9
  const blocks = [
10
    {
11
      type: 'header',
12
      text: {
13
        type: 'plain_text',
14
        text: `Action run ${body.data.action_run.failure ? 'failed' : 'completed'}`,
15
        emoji: true,
16
      },
17
    },
18
    {
19
      type: 'section',
20
      fields: [
21
        {
22
          type: 'mrkdwn',
23
          text: `*Branch ref:*\n${body.data.project_ref}`,
24
        },
25
        {
26
          type: 'mrkdwn',
27
          text: `*Run ID:*\n${body.data.action_run.id}`,
28
        },
29
      ],
30
    },
31
    {
32
      type: 'section',
33
      fields: [
34
        {
35
          type: 'mrkdwn',
36
          text: `*Started at:*\n${body.data.action_run.created_at}`,
37
        },
38
        {
39
          type: 'mrkdwn',
40
          text: `*Completed at:*\n${body.timestamp}`,
41
        },
42
      ],
43
    },
44
    {
45
      type: 'section',
46
      text: {
47
        type: 'mrkdwn',
48
        text: `<${body.data.details_url}|View logs>`,
49
      },
50
    },
51
  ]
52
  const resp = await fetch(slack, {
53
    method: 'POST',
54
    body: JSON.stringify({
55
      blocks,
56
    }),
57
  })
58
  const message = await resp.text()
59
  return new Response(
60
    JSON.stringify({
61
      message,
62
    }),
63
    {
64
      status: 200,
65
    }
66
  )
67
})

1
supabase secrets set --project-ref <branch-ref> SLACK_WEBHOOK_URL=<your-webhook-url>

1
supabase functions deploy --project-ref <branch-ref> --use-api notify-slack

1
supabase branches update <branch-ref> --notify-url https://<branch-ref>.supabase.co/functions/v1/notify-slack

完成以上步骤后，每当目标分支上的操作运行完成时，你应该会收到一条 Slack 消息。

🌐 After completing the steps above, you should receive a Slack message whenever an action run completes on your target branch.

迁移和播种行为 #

🌐 Migration and seeding behavior

迁移是按顺序进行的。每次迁移都是在上一次的基础上进行的。

🌐 Migrations are run in sequential order. Each migration builds upon the previous one.

预览分支继承了你基础项目的迁移历史，所以它只会应用那些还没运行过的迁移。这在回滚迁移时可能会产生问题。

🌐 The preview branch inherits the migration history of your base project, so it only applies migrations that haven't been run yet. This can create an issue when rolling back migrations.

分支的默认权限 #

🌐 Default privileges on branches

新分支默认是安全的。无论基础项目的设置如何，它们在 public 架构上创建时都没有默认权限。分支上的新表、函数和序列在 anon、authenticated 或 service_role 通过数据 API 访问之前，需要明确授予权限。

🌐 New branches are secure by default. They are created without default privileges on the public schema, regardless of the setting on your base project. New tables, functions, and sequences on a branch require explicit grants before anon, authenticated, or service_role can reach them through the Data API.

你的迁移控制了一个分支是否重新启用这些权限。如果你的基础项目已启用默认权限，并且你的迁移历史是由 Supabase 分支或 Supabase CLI 初始化的，那么初始迁移已经包含授予 public 访问权限的 alter default privileges 语句。在新分支上运行它会恢复你的基础项目拥有的相同访问权限，所以不需要做任何更改。

🌐 Your migrations control whether a branch re-enables these privileges. If your base project has default privileges enabled and your migration history was initialized by Supabase Branching or the Supabase CLI, the initial migration already contains the alter default privileges statements that grant access on public. Running it on a new branch restores the same access your base project has, so no changes are needed.

有两种情况需要人工干预：

🌐 Two cases require manual intervention:

• 你在 Supabase 之外管理迁移，并且想在分支上保持默认权限开启。
• 你使用 Supabase 托管迁移，并且想要在你的基础项目和分支上撤销默认权限。

保持默认权限启用 #

🌐 Keep default privileges enabled

如果你的迁移历史不是由 Supabase 分支或 Supabase CLI 初始化的，你的初始迁移不会授予默认权限，所以新分支启动时不会有这些权限。要恢复与基础项目相同的访问权限：

🌐 If your migration history was not initialized by Supabase Branching or the Supabase CLI, your initial migration doesn't grant default privileges, so new branches start without them. To restore the same access your base project has:

1
alter default privileges for role postgres in schema public grant usage, select, update on sequences to anon, authenticated, service_role;
2
alter default privileges for role postgres in schema public grant execute on functions to anon, authenticated, service_role;
3
alter default privileges for role postgres in schema public grant select, insert, update, delete on tables to anon, authenticated, service_role;

1
supabase migration repair --status applied <migration-timestamp>

撤销默认权限 #

🌐 Revoke default privileges

为了提高安全性，我们建议不要在你的基础项目上自动暴露 public 模式。如果你的初始迁移是由 Supabase 分支或 Supabase CLI 生成的，它在分支上运行时会重新授予默认权限。要在你的基础项目和分支上撤销这些权限:

🌐 For improved security, we recommend not exposing the public schema automatically on your base project either. If your initial migration was generated by Supabase Branching or the Supabase CLI, it re-grants default privileges when it runs on a branch. To revoke them on your base project and branches:

1
supabase migration new revoke_default_privileges

1
alter default privileges for role postgres in schema public revoke select, insert, update, delete on tables from anon, authenticated, service_role;
2
alter default privileges for role postgres in schema public revoke execute on functions from anon, authenticated, service_role, public;
3
alter default privileges for role postgres in schema public revoke usage, select, update on sequences from anon, authenticated, service_role;

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

🌐 Using ORM or custom seed scripts

如果你想使用自己的 ORM 来管理迁移和种子脚本，你需要在预览分支准备好之后在 GitHub Actions 中运行它们。可以使用以下示例 GHA 工作流来获取分支凭证。

🌐 If you want to use your own ORM for managing migrations and seed scripts, you will need to run them in GitHub Actions after the preview branch is ready. The branch credentials can be fetched using the following example GHA workflow.

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

回滚迁移 #

🌐 Rolling back migrations

你可能想回滚之前迁移中所做的更改。例如，你可能已经推送了一个包含你不再需要的模式更改的迁移文件。

🌐 You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.

要解决这个问题，先推送最新的更改，然后在 Supabase 中删除预览分支，再重新打开它。

🌐 To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.

新的预览分支是你基础项目的全新克隆，默认会从 ./supabase/seed.sql 文件重新生成。旧预览分支上的任何额外数据更改都会丢失。

🌐 The new preview branch is a fresh clone of your base project and is reseeded from the ./supabase/seed.sql file by default. Any additional data changes made on the old preview branch are lost.

如果你想重新运行基础项目已经应用的迁移，请改为从 Supabase 控制面板重置分支。重置会按顺序重新运行所有迁移，并清除分支上现有的数据。

🌐 To rerun migrations that your base project has already applied, reset the branch from the Supabase dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.

种子行为 #

🌐 Seeding behavior

你的预览分支已使用与本地播种行为相同的示例数据进行初始化。

🌐 Your Preview Branches are seeded with sample data using the same as local seeding behavior.

数据库只会在创建预览分支时初始化一次。要重新执行初始化，只需删除预览分支，然后通过关闭并重新打开你的 Pull Request 来重新创建它。

🌐 The database is only seeded once, when the preview branch is created. To rerun seeding, delete the preview branch and recreate it by closing, and reopening your pull request.

使用分支进行开发 #

🌐 Developing with branches

你可以使用本地或远程开发流程来用分支进行开发。

🌐 You can develop with branches using either local or remote development workflows.

本地开发工作流程 #

🌐 Local development workflow

1. 为你的功能创建一个新的 Git 分支
2. 使用 Supabase CLI 进行模式更改
3. 使用 supabase db diff 生成迁移文件
4. 在本地测试你的更改
5. 提交并推送到 GitHub
6. 创建一个拉取请求来生成预览分支

如果你的项目使用声明式模式，请在 supabase/schemas/ 中编辑你的文件，并使用 supabase db schema declarative sync 生成迁移，而不是 supabase db diff，因为在 pg-delta 上它从不将你的模式文件作为基线。如果你的项目还没有启用 pg-delta，请改为参考传统 migra 引擎上的声明式模式。分支操作只适用于已提交的迁移文件，所以请将模式文件和生成的迁移文件一起提交。

🌐 If your project uses declarative schemas, edit your files in supabase/schemas/ and generate migrations with supabase db schema declarative sync instead of supabase db diff, which on pg-delta never uses your schema files as its baseline. If your project hasn't enabled pg-delta, follow Declarative schemas on the legacy migra engine instead. Branching applies only committed migration files, so commit the schema files and the generated migrations together.

远程开发工作流程 #

🌐 Remote development workflow

1. 在 Supabase 仪表板里创建一个预览分支
2. 使用分支下拉菜单切换分支
3. 在仪表板中进行模式更改
4. 使用 supabase db pull 在本地拉取更改
5. 提交生成的迁移文件
6. 推送到你的 Git 仓库

管理分支环境 #

🌐 Managing branch environments

在分支之间切换 #

🌐 Switching between branches

在 Supabase 仪表板中使用分支下拉菜单在不同分支之间切换。每个分支都有自己的：

🌐 Use the branch dropdown in the Supabase dashboard to switch between different branches. Each branch has its own:

• 数据库实例
• API端点
• 身份验证设置
• 存储桶

正在访问分支凭证 #

🌐 Accessing branch credentials

每个分支都有独特的凭证，你可以在仪表板上找到：

🌐 Each branch has unique credentials that you can find in the dashboard:

1. 切换到你想要的分支
2. 导航到 设置 > API
3. 复制分支专用的 URL 和密钥

分支隔离 #

🌐 Branch isolation

各个分支是完全隔离的。在一个分支上做的修改不会影响其他分支，包括：

🌐 Branches are completely isolated from each other. Changes made in one branch don't affect others, including:

• 数据库模式和数据
• 存储对象
• 边缘函数
• 认证配置

下一步 #

🌐 Next steps

• 了解一下 分支配置
• 探索集成
• 查看 故障排除指南