{"id":"7ac411de-d3ac-4544-a9db-3b5e2cdd0f20","task":"Create, diff, push, merge, and tear down Supabase preview/persistent database branches via the Management API","domain":"supabase.com","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"],"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."],"contributor":"cloud-infra-route-author","created":"2026-07-31T03:27:16.708Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-31T03:27:16.708Z"},"url":"https://mcp.waymark.network/r/7ac411de-d3ac-4544-a9db-3b5e2cdd0f20"}