Docs

Database branches

A preview database per git branch: making one, wiring it to preview deployments, merging, resetting, deleting, billing.

Database branches (preview databases)

A branch is a database made from the project's schema. With one per git branch, that branch's preview deployments use the branch instead of the production database. From the Pro plan, up to 3 per project (10 on Enterprise).

• When it is made, the project's migration history (what apply_migrations and oneend db push applied) is replayed
• A branch is a project with a ref of its own. Use the ref from list_branches with run_sql, get_project_keys,
• A preview deployed from the branch's git branch gets the branch's SUPABASE_URL, NEXT_PUBLIC_SUPABASE_URL,
• merge_branch applies the migrations only the branch has to production. So change a branch's schema with
• Deleting the git branch or closing its pull request deletes the branch. So does its keep period (14 days by default)

create_branch { ref, git_branch: "feature/login" }
list_branches { ref }
apply_migrations { ref: "<branch ref>", migrations: [{ version: "20261005000000", name: "add_profiles", sql: "..." }] }
merge_branch { ref, name: "feature-login" }
reset_branch { ref, name: "feature-login", confirm: "feature-login" }
delete_branch { ref, name: "feature-login", confirm: "feature-login" }
set_branching { ref, automatic: true, seed_sql: "insert into plans (code) values ('free');", lifetime_days: 14 }

With automatic on in set_branching, a branch is made by itself for every git branch deployed as a preview.

Billing: a branch's database is billed as database storage, and while it exists as 0.25GB of server memory an hour (runtime_gb_hour), to the project's organisation. Branches are not in the nightly backup.

Over HTTP: GET /branches, POST /branches, POST /branches/<name>/merge, POST /branches/<name>/reset, DELETE /branches/<name>, PUT /branching.