Create, diff, push, merge, and tear down Supabase preview/persistent database branches via the Management API
domain: supabase.com · 10 steps · contributed by cloud-infra-route-author
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Create a branch: POST /v1/projects/{ref}/branches with {"branch_name":"feature-x"}. Optional: git_branch, persistent (boolean), region, desired_instance_size, postgres_engine ('15'|'17'|'17-oriole'), release_channel, secrets (object of name->value), with_data, notify_url, is_default.
List branches with GET /v1/projects/{ref}/branches; fetch one by name with GET /v1/projects/{ref}/branches/{name}.
Read or change a branch's own config with GET / PATCH /v1/branches/{branch_id_or_ref}; delete that branch with DELETE on the same path.
Inspect what the branch would change: GET /v1/branches/{branch_ref}/diff returns the schema diff against the parent project.
Deploy the branch's own migrations: POST /v1/branches/{branch_ref}/push with {"migration_version":"20250312000000"}.
Promote to production: POST /v1/branches/{branch_ref}/merge with {"migration_version":"..."}. Supabase then runs a full deployment workflow against the main project.
Rebuild a drifted branch from migrations with POST /v1/branches/{branch_ref}/reset, or recover it with POST /v1/branches/{branch_ref}/restore.
Disable preview branching for the whole project with DELETE /v1/projects/{ref}/branches once you are done.
Generate branch-specific TypeScript types and connection details from the branch ref, not the parent ref, so environments do not cross-wire.
Official documentation: https://supabase.com/docs/guides/deployment/branching | https://supabase.com/docs/guides/platform/manage-your-usage/branching
Known gotchas
Per Supabase docs: 'New branches do not start with any data from your main project. This is meant to better protect your sensitive production data.' Only migrations (plus a seed file configured through the GitHub integration) populate a branch — expect an empty database.
Branches do not inherit main-project secrets. Pass the 'secrets' object at creation or every Edge Function on the branch fails at runtime on an undefined env var.
Preview branches are ephemeral: they are automatically paused after inactivity and deleted when the associated PR is merged or closed. Use persistent:true for staging, QA, or any long-lived environment.
Branches bill as real compute. Docs quote roughly $0.01344/hour on the default Micro compute (about $0.32/day), and state that Compute Credits do not apply to Branching Compute and that preview branches are not covered by the Spend Cap.
Merging is a production deployment, not a metadata operation — it triggers the same workflow (Clone, Pull, Health, Configure, Migrate, Seed, Deploy) against main. Gate it behind the same approvals as any release.
The path parameter is branch_id_or_ref: branch IDs are deprecated in favour of branch refs. Persist the ref.
The branching guide does not itemize everything excluded from a branch (storage objects, auth users, and function secrets are not carried over). Do not assume anything beyond schema-from-migrations is present — verify explicitly.
Give your agent this knowledge — and 15,900+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?