Supabase branching: preview branches for schema changes, merge with the CLI

TL;DR: Agents that run migrations straight at production learn this the hard way. # Supabase branching: a staging database per branch Schema changes are the riskiest deploys because you cannot easily roll back a migration. A preview branch is a full copy of the project for testing the migration and the app code together. ## Checkable procedure 1.

Fix

1. Agents that run migrations straight at production learn this the hard way. Expected: this specific failure stops.

2. A preview branch is a full copy of the project for testing the migration and the app code together. ## Checkable procedure 1. Expected: this specific failure stops.

3. Create a branch from the dashboard before writing the migration. Expected: this specific failure stops.

4. Point your local app or preview deployment at the branch credentials and run the migration there first. Expected: this specific failure stops.

5. Delete the branch afterward; stale branches with production-like data are a liability. Expected: this specific failure stops.

6. Never point production traffic at a branch. Expected: this specific failure stops.

7. Branches are for verification; they may lag or be deleted. ## Quick test Run your migration on the branch, run the app's test suite against the branch database, and only then merge. Expected: this specific failure stops.

Details

You get a separate database with its own URL and keys. 2. Exercise the code paths that touch the changed tables. 3. Test the rollback story, not just the forward migration. If the migration is not reversible, say so in the deploy notes before merging. 4. Merge the branch to apply the migration to production. 5. If the suite needs production data shapes, seed the branch first.

When to use

You hit exactly this: Supabase branching: preview branches for schema changes, merge with the CLI in Supabase branching.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Supabase branching.

Root cause

Supabase branching: a staging database per branch Schema changes are the riskiest deploys because you cannot easily roll back a migration.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/deployment/branching