Supabase Branching

13 Dec 2023 · 8 minute read

Supabase Branching is now rolling out to early-access subscribers on a first-signed-up, first-served basis for paid organizations.

What's Branching?

Branching extends local development workflows to include remote databases. Instead of experimenting only locally with supabase start and supabase db reset, you now get a remote Supabase Preview Branch for each Git branch.

Each Git branch has a corresponding Supabase Preview that automatically updates when you push changes. When you merge a Pull Request into your main Git branch, Supabase runs your database migrations in your Production database.

Preview Branches are isolated instances with:

• Distinct API keys and passwords
• Full suite of Supabase services: Postgres, Auth, File Storage, Realtime, Edge Functions, and Data APIs
• Safety features so leaked keys won't affect Production

Support for Vercel Previews

Supabase Branching integrates seamlessly with Vercel Preview deployments, giving you an entire stack with proper branching support.

The improved Vercel Integration automatically populates environment variables with connection secrets for each Preview Branch.

Developing on the hosted Preview Branch

Every Supabase Preview can be managed from the Dashboard. You can:

• Make schema changes
• Access the SQL Editor
• Use the new AI Assistant

Once happy with changes, run supabase db diff locally to pull changes and commit to Git.

Note: Treat Preview Branches like cattle, not pets. They can be wiped if team members push destructive migrations.

Database migrations

The Supabase GitHub app observes changes in connected repositories:

• Opens a Pull Request → launches a Preview Branch and runs migrations in ./supabase/migrations
• Errors are logged to the Check Run
• New migrations run incrementally in Preview Branches
• Merging a PR → migrations run on Production

Data seeding

Seed Preview Branches the same way you seed local development. Add ./supabase/seed.sql to your repo and it runs when the Preview Branch is created.

Optionally reset with: supabase db reset --db-url <branch-connection-string />

Supabase is investigating data masking with copy-on-write systems to emulate production workloads in Preview Branches.

Future considerations

Declarative config

Working on configuration in code via config.toml for different external services (e.g., different Google Auth for Preview vs Production).

Automatic dashboard commits

Plan to automatically capture dashboard changes to Git instead of requiring manual db diff runs.

Extended seeding behavior

Exploring AI-generated seed data and approaches like postgresql-anonymizer and Snaplet for cloning anonymized production data.

Copy-on-write

In development to allow branching from database snapshots and running tests on production-like workloads. Also planned for File Storage.

Getting Started

Check out the Branching docs.

Update 17th January 2024: Early access for Branching is now closed. Working towards a public beta.