Platform
Database branching
Separate database environments for testing and previews — schema only or with data, migrations merged back to production.
A branch is a full, isolated clone of a project — its own Postgres, Auth, Storage, Realtime and Edge Functions, with its own API keys — created from the production project. Use branches to test migrations, power preview deployments and experiment without risking production. Branches are in the environment switcher in the top bar (main PRODUCTION) and on the Branches page.
Modes
| Mode | What is copied | When to use |
|---|---|---|
schema | Database structure: tables, functions, triggers, RLS policies, extensions — no data | Testing migrations, CI environments, previews |
data | Schema and data, including Auth users and Storage metadata | Debugging on real data, analysis |
A branch runs in the same region and on the same server as its parent, with its own ref, URL https://<branch-ref>.host.ulewicz.space and database password. It's a separate stack, so it uses its own resources — delete branches you don't need. Deleting the main project deletes all its branches.
| Plan | Branches per project |
|---|---|
| Free | 0 |
| Pro | 3 |
| Team | 20 |
| Enterprise | 100 |
Branches don't count toward your plan's project limit — they have their own limit above.
Merging
Schema changes go from a branch to production through migrations: the dashboard compares supabase_migrations.schema_migrations in both environments and shows the migrations that exist only on the branch (the merge plan). Merge replays them on production in order, in a single transaction — a failure in any of them rolls everything back. The format is compatible with supabase db push / supabase migration list.
- Conflicts: if production has migrations the branch doesn't (the branch is stale), the merge plan lists them — reset the branch or bring those migrations over.
- Reset: rebuilds the branch from the current production state (same
ref, keys and URL). - Data is not merged — only schema captured in migrations.
API
# new branch (schema only)
curl -X POST -H "Authorization: Bearer hb_pat_..." -H "content-type: application/json" \
-d '{"name":"feature-login","mode":"schema"}' https://host.ulewicz.space/api/v1/projects/<ref>/branches
# merge plan, then merge
curl -H "Authorization: Bearer hb_pat_..." https://host.ulewicz.space/api/v1/projects/<ref>/branches/feature-login/merge
curl -X POST -H "Authorization: Bearer hb_pat_..." https://host.ulewicz.space/api/v1/projects/<ref>/branches/feature-login/mergeMCP
Tools list_branches, create_branch, delete_branch and merge_branch (with dry_run returning just the plan) — an AI agent can create a branch, test a migration on it, show you the plan and merge after your approval.