The answer. Branching connects a project to a Git repository and creates a database per pull request: an empty Postgres that replays your supabase/migrations, runs seed.sql, applies the services configuration from config.toml, and deploys the Edge Functions that are in the branch. What it does not do is copy production: no rows, no storage objects, no secrets, which is the point, since a preview should never hold customer data. Each branch gets its own URL and keys for the preview deploy to use, it is deleted when the PR merges or closes, and merging into the production branch applies only the migrations production has not seen. That last sentence is the contract to design around: migrations are append-only files with stable names, the remote decides what to apply from the list of names it has already run, and a file edited after it ran is never re-applied.
The pattern.
npx supabase migration new add_ticket_priority # new file, never edit an applied one
npx supabase db reset # replay everything locally, exactly as the branch will
git push origin feat/priority # PR opens → preview branch builds from migrations + seed
npx supabase migration list --linked # remote vs local name list
npx supabase migration repair --status applied 20260907120000 --linked # only when the lists diverge on purpose
# supabase/config.toml — what a branch replays
[db.seed]
enabled = true
sql_paths = ["./seed.sql"]
Watch out.
- Persistent branches (staging, QA) are the same mechanism kept alive; they still start without data, so seed them with realistic anonymized rows.
- A migration that depends on data (
update … set …on existing rows) is a no-op on a fresh branch and a surprise in production; keep data fixes in separate, clearly named migrations. - Hand edits on the production database (a column added in Studio) are invisible to branching and to
db push; pull them into a migration the same day.
Related: tracked-migration-ledger-checksum-same-transaction · local-stack-supabase-start-link-push-gen-types · pgtap-tests-run-inside-a-transaction