Supabase 怎么用持久化分支Branching管理迁移与开发工作流【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase这篇文章解决一个具体任务在 Supabase 上为项目建一个长期运行的持久化分支persistent branch作为 staging / QA / 开发环境把数据库迁移migration和服务配置放进 Git 版本控制通过 GitHub 集成自动同步到分支上并在合并回生产前完成验证与回滚。适用前提你已有一个连接到 GitHub 仓库的 Supabase 项目——Supabase 在任意套餐上都支持直接从 GitHub 部署Branching 在此之上为每个 pull request 增加隔离的预览环境参见 Branching 总览。持久化分支和预览分支是什么关系Branching 文档把两种分支区分得很明确预览分支Preview branches临时性环境适合聚焦测试在 PR 合并或关闭时会被自动删除。持久化分支Persistent branches长期运行文档推荐用于 staging、QA 或 development 环境。它们不会因为不活跃而被自动暂停也不会在 PR 合并或关闭时被删除。两者都是从主项目克隆出来的独立环境有自己的 Supabase 实例和 API 凭据并且都携带主项目已部署的 Edge Functions 与配置。默认都不带主项目的数据或存储对象这是为了隔离生产数据需要数据时可用 seed 文件或 dashboard 的Include data选项补充。准备条件连接 GitHub 并初始化 supabase 目录按 GitHub integration 文档 的顺序执行在 Supabase Dashboard 进入Project SettingsIntegrations在GitHub Integration下点击Authorize GitHub在跳转的页面点击Authorize Supabase。回到 Integrations 页选择要连接项目所用的 GitHub 仓库。设置Working directory它表示从仓库根目录到包含supabase/文件夹所在目录的路径。supabase/在仓库根目录时填.例如目录结构是apps/web/supabase/时填apps/web。点击Enable integration并启用Automatic branching选项让 GitHub 分支与 Supabase 分支自动同步可选启用Supabase changes only仅当 Supabase 文件变化时才创建分支。在 GitHub 仓库设置中为 Supabase 集成开启 required check。这样迁移检查失败时 PR 无法合并可以阻止无效迁移进入生产分支。然后初始化仓库中的supabase/目录如果你还没有该目录# 初始化本地 supabase 目录 supabase init # 拉取数据库迁移。--db-url 需要替换为 Session pooler 连接串 # 在项目 Dashboard 的 Connect 页面获取 supabase db pull --db-url db_connection_string # 提交 supabase 目录到 Git git add supabase git commit -m Initial migration git push文档中给出的连接串示例格式如下仅示例你的值以 Connect 页面为准postgres://postgres.xxxx:passwordxxxx.pooler.supabase.com:5432/postgres这一步很关键新分支的数据库 schema 不是克隆出来的而是由你提交到仓库的迁移文件构建的。migrations子目录中的迁移在分支创建时自动执行之后的每次提交只会执行尚未应用的迁移。创建持久化分支并获取它的 project ID使用 CLI 创建持久化分支命令来自 Configuration 文档supabase --experimental branches create --persistent # 提示输入分支名例如 # Do you want to create a branch named develop? [Y/n]创建后查询分支对应的 project IDsupabase --experimental branches list命令输出是一张包含所有分支的表格BRANCH PROJECT ID列的值就是下一步写入config.toml的project_id。在 config.toml 中为持久化分支写入配置config.toml的[remotes]块用于给特定持久化分支设置独立配置。注意顺序限制project_id必须引用一个已存在的分支所以要先创建分支再添加它的配置这也是上一节先执行branches create的原因。文档给出的示例是为 staging 环境配置独立的 seed 脚本[remotes.staging] project_id your-project-ref [remotes.staging.db.seed] enabled true sql_paths [./seeds/staging.sql]其中your-project-ref需替换为branches list输出中该分支的BRANCH PROJECT ID。修改config.toml后推送到 Git集成会检测到变更并应用到对应分支[remotes]块中所有标准配置项都可用包括数据库、API、Auth 和 Edge Functions 配置。有一个明确的失败条件如果没声明对应 remote、或project_id写错部署工作流中的配置步骤会被跳过。敏感配置用 CLI 按分支单独设置# 从 .env 文件批量设置 supabase secrets set --env-file ./supabase/.env # 或逐个设置 supabase secrets set SMTP_HOSTsmtp.example.com supabase secrets set SMTP_USERyour-username supabase secrets set SMTP_PASSWORDyour-password然后在config.toml中通过env()语法引用[auth.smtp] host env(SMTP_HOST) user env(SMTP_USER) password env(SMTP_PASSWORD)secrets 是按分支隔离的为一个分支设置的 secret 不会自动出现在其他分支需要的分支要分别设置。日常开发工作流迁移如何同步到分支Working with branches 文档给出两种工作流。本地开发工作流为功能创建新的 Git 分支使用 Supabase CLI 做 schema 变更用supabase db diff生成迁移文件本地测试提交并推送到 GitHub打开 pull request 创建预览分支。远端开发工作流在 Supabase dashboard 创建预览分支用顶栏的分支下拉框切换到该分支在 dashboard 中做 schema 变更本地用supabase db pull拉回变更提交生成的迁移文件推送到 Git 仓库。几个影响判断的事实迁移按顺序执行每条迁移建立在前面之上预览分支继承基础项目的迁移历史只执行尚未跑过的迁移。每个分支有自己的数据库实例、API 端点、Auth 配置和存储桶。切换分支用 dashboard 顶栏的分支下拉框分支专属的 URL 和 key 在切换到该分支后从Settings API复制。分支之间完全隔离一个分支上的 schema、数据、存储对象、Edge Functions、Auth 配置变更不影响其他分支。如果迁移要由自己的 ORM 管理文档的做法是在 GitHub Actions 中等预览分支就绪后用supabase --experimental branches get $GITHUB_HEAD_REF -o env输出分支凭据再用psql $POSTGRES_URL_NON_POOLING执行迁移完整 workflow 示例含SUPABASE_ACCESS_TOKEN、SUPABASE_PROJECT_ID两个 secret 和等待Supabase Previewcheck 的步骤见 Working with branches 文档。合并到生产时实际发生什么把任何分支合并进主项目时Supabase 自动执行部署工作流文档将其表示为有向无环图节点依次为Clone— 检出指定 git 分支dashboard 方式创建分支时可选Pull— 从主项目拉取数据库迁移dashboard 方式时同时初始化迁移历史表Health— 最长等待 2 分钟直到 Auth、API、Database、Storage、Realtime 全部健康Configure— 按config.toml更新服务配置仅 GitHub 集成方式Migrate— 应用待处理的数据库迁移和 vault secretsSeed— 运行 seed 文件填充初始数据对持久化分支必须在config.toml中启用即上一节的[remotes.branch.db.seed]Deploy— 部署变更的 Edge Functions 并更新函数 secrets。父步骤失败时所有依赖它的子步骤会被跳过——例如 Migrate 失败Seed 不会执行。使用 GitHub 集成时推送到该 git 分支的每次提交都会重新跑这套工作流。另外启用Deploy to production选项后推送或合并到生产分支时自动部署的变更范围是新迁移被应用、config.toml声明的 Edge Functions 被部署、config.toml声明的存储桶被部署API、Auth、seed 等其他配置默认被忽略。如何验证部署结果与迁移是否正确PR 状态GitHub 集成为 PR 添加部署状态评论预览分支的部署状态直接可见在 PR 上。分支日志dashboard 进入Manage Branches点击分支查看部署日志View logs区域有详细错误信息。本地预演迁移文件改动后文档给出的调试命令是先本地验证再推上去# 在本地测试迁移 supabase db reset失败拦截前面开启的 required check 会在迁移检查失败时阻止 PR 合并文档还建议订阅分支的邮件通知常见错误包括迁移冲突、函数部署失败、无效配置文件。Webhook可选持久化分支可以订阅 action run 完成后的 webhook 通知payload 遵循 standard webhooks 标准事件类型为run.completed文档给出了把它接到一个 Edge Function 再转发到 Slack 的完整做法见 Working with branches 文档。部署失败时按 Troubleshooting 文档 核对三类原因迁移中的无效 SQL 或 schema 冲突、config.toml配置错误、以及迁移文件依赖的对象不存在或权限问题。迁移顺序类问题时间戳冲突、Git rebase 后时间戳乱序的排查方式下一节说明。回滚迁移与修复顺序问题撤掉一条不想要的迁移推送到基础分支时如果带上了不想保留的 schema 变更做法是推送最新修改后在 Supabase 中删除该预览分支并重新打开 PR。新预览分支是基础项目的全新克隆默认从./supabase/seed.sql重新填充旧预览分支上的额外数据变更会丢失。重跑基础项目已应用过的迁移改用 dashboard 对该分支执行 reset。reset 会按顺序重跑所有迁移并丢弃分支上的现有数据。rebase 后迁移乱序迁移按时间戳顺序应用构建在较早变更之上的迁移必须使用更晚的时间戳。文档给出的修复方式是重命名迁移文件再本地验证# 重命名迁移文件以修复时间戳顺序 mv 20240101000000_old.sql 20240102000000_old.sql # 重置本地数据库测试 supabase db reset多个预览分支之间的 schema 漂移某个预览分支合并进生产后与尚未合并的预览分支之间会产生 schema 差异处理方式与普通 Git 冲突相同——从生产 Git 分支 merge 或 rebase 到预览 Git 分支并确保 rebase 后迁移文件时间戳正确。已知限制预览分支数据是临时的分支删除时数据丢失数据不会在分支之间迁移删除重建后数据不保留分支创建时只 seed 一次重跑 seed 需要删除并重建分支关闭再重新打开 PR。预览分支不活跃后会自动暂停暂停后的首次请求可能超时分支会在第一个请求后唤醒常用分支建议转为持久化分支持久化分支不会因不活跃被暂停或删除。通过 dashboard 管理分支目前处于 public alpha且有明确限制分支只能合并到 main不支持预览分支之间互合并通过 dashboard 创建的自定义角色不会被分支捕获分支Include data选项要求项目有 Point-in-Time Recovery 附加组件且分支使用更大磁盘并与项目计算规格一致会增加成本功能分支上过期时拉取 main 的变更会覆盖已有 Edge Functions新创建的函数保留。不能更改哪个分支充当生产分支——所有分支克隆来源的基础项目永远是生产分支但可以修改生产分支关联的 GitHub 分支名在 Integrations 页面。config.toml改了不生效时文档列出的检查项是TOML 语法、变更是否已提交并推送、删除并重建分支。分支的用量与计费细节见 Branching 计费文档更多故障场景见 Troubleshooting 文档。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
