Branching

A branch is a separate copy of a project that you can break without consequences. Use one to try a migration on real data, to give a pull request its own backend, or to rehearse a risky change before running it on production.

Branching is available on Pro, Business and Enterprise. Only the owner can create or delete branches.

How branches work on SupaHost

A branch is a full project in its own right. It has its own database, URL, Auth, Storage and keys, and it counts toward your plan's project allowance like any other project (and toward the 3-project limit during the trial). A branch of app-one named app-one-orders lives at https://app-one-orders.acme.supahost.space.

You can only branch from a main project, not from another branch. The branch name is the parent's name, a dash and your suffix, and the whole name can be at most 30 characters.

There's no merge. A branch is a place to test; you ship changes by applying the same migration to the parent. More on that below.

Create a branch

1. Open Dashboard → your project → Branches.
2. Enter a suffix, for example orders, to create app-one-orders.
3. Choose whether to keep Copy data, users and files on (the default).
4. Create the branch.

The parent stays online the whole time. SupaHost copies its database with pg_dump and pg_restore into the new branch database.

What's copied

Never copied, either way:

• Edge Functions and their secrets.
• Cron jobs. They're stored outside the project database, so a new branch starts with none.
• Auth settings (such as Site URL and redirect URLs) and OAuth providers.
• Custom domains.

The branch also gets its own keys. Your app needs the branch's URL and anon key to talk to it, which you'll find on the branch's Connect tab as usual.

A note on real user data

With data copied, the branch has your real users and their emails. Auth settings aren't copied, so the branch starts with a Site URL of http://localhost:3000 and no OAuth providers. Be careful testing anything that sends email from a branch, and delete branches holding production data when you're done. Choose schema only when you don't need the data.

Testing a migration on a branch

Say you want to add a status column to orders and backfill it.

1. Create app-one-orders with data copied.
2. Run the migration on the branch, from Studio's SQL editor or through an AI agent with the MCP apply_migration tool:

alter table public.orders
  add column status text not null default 'pending'
  check (status in ('pending', 'paid', 'refunded'));

update public.orders set status = 'paid' where paid_at is not null;

create index orders_status_idx on public.orders (status);

3. Point a preview build of your app at the branch and check it works.
4. Check timing. If the update was slow on the branch's copy of the data, it will be about as slow on production.

Shipping the change

Because there's no merge, you apply the same migration to the parent:

1. Keep the migration as a file in your repo, for example supabase/migrations/20261111093000_add_order_status.sql.
2. Apply that exact file to the parent project, the same way you did on the branch.
3. Delete the branch from the Branches tab.

Keeping migrations in files is what makes this reliable. See SQL migrations and Migrations workflow: local to SupaHost.

Branches for pull requests

A branch per pull request works, with two limits to keep in mind: each branch counts as a project while it exists, and creating one is a dashboard action by the owner. Schema-only branches hold no user data, so they are the safer choice for previews. See Can I get a database per pull request?.

Related

• Projects
• Plans and limits
• Stopping cron jobs on a restored project or branch