Supabase Branching
Tags: webdev, programming, devops, database
Published: 2023-12-13 20:27:02

A few months ago we mentioned that we were working on Branching with a (somewhat ambitious) early-access form.

Today we are rolling out access to early-access subscribers. Internally, we were hoping to make this public access for this Launch Week but, well, _[we did say this was hard.](https://supabase.com/blog/supabase-local-dev#supabase-branching-is-hard)_

We're operating on a first-signed-up, first-served basis, rolling it out in batches to paid orgs in who registered for early access.

![New Branching UI in the Supabase dashboard
](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x0owdln4g4ea0t4acsea.jpg)

## What's Branching?

At some point during development, you will probably need to experiment with your Postgres database. Today that's possible on your local development machine using the Supabase CLI. When you run `supabase start` with the CLI to get the entire Supabase stack running locally. You can play around with ideas and run `supabase db reset` whenever you want to start again. When you want to capture your changes in a database migration, you can run `supabase db diff`.

Branching is a natural extension of this, but instead of experimenting with a just a local database you also get remote database. You continue to use the workflow above, and then when you commit your changes to Git we'll run them on a Supabase Preview Branch.

![Each Git branch has a corresponding Supabase Preview.
](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/in28njh281i2au5d7vyz.jpg)

Each Git branch has a corresponding Supabase Preview, which automatically updates whenever you push an update. The rest of the workflow should feel familiar: when you merge a Pull Request into your main Git branch, Supabase will run your database migrations inside your Production database.

Your project's Preview Branches are designed with safety in mind. They are isolated instances, each with a distinct set of API keys and passwords. Each instance contains every Supabase feature: a Postgres database, Auth, File Storage, Realtime, Edge Functions, and Data APIs.

![Every Supabase Preview is a dedicated instance, with a full suite of Supabase services.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r9oq4jdxlywppsh1cvmi.jpg)

Even in relaxed developer environments, if one of your team accidentally leak a key it won't affect your Production branch.

## Support for Vercel Previews

We've designed Supabase Branching to work perfectly with Vercel's [Preview](https://vercel.com/features/previews) deployments. This means that you get an _entire stack_ with Branching.

![Vercel will build your preview deployments, and your preview deployment can connect to the Supabase services on your Preview Branch.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2qnhpvq8kvy4ft3osgvc.jpg)

We've made several improvements to our [Vercel Integration](https://vercel.com/integrations/supabase-v2) to make the Vercel experience seamless. For example, since we provide distinct, secure database credentials for every Supabase Preview Branch, we automatically populate the environment variables on Vercel with the connection secrets your app needs to connect to the Preview Branch.

![Vercel environment variables settings page, showing the Git branch based env vars.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oakrkkhlqkak1ap7t1uz.jpg)

## Developing on the hosted Preview Branch

One of the most-loved features of Supabase is the dashboard. Even if we [beg](https://supabase.com/docs/guides/platform/maturity-model#in-production), it seems that developers simply want to use it for everything - even in production.

The cool thing about Branching is that every Supabase Preview can be managed from the Dashboard. You can make schema changes, access the SQL Editor, and use the [new AI Assistant](https://supabase.com/blog/studio-introducing-assistant). Once you're happy with your changes, you simply run `supabase db diff` on your local maching to pull the changes and you can commit them to Git.

Just note that we _still_ want you to develop locally! You should treat the Preview Branches [like cattle, not pets](https://devops.stackexchange.com/questions/653/what-is-the-definition-of-cattle-not-pets). Your Preview changes can be wiped at any time if one of your team pushes a destructive migration.

## Database migrations

We've developed Branching to work with a Git provider, starting with GitHub.

Our [GitHub app](https://github.com/apps/supabase) observes changes within a connected GitHub repository. When you open a Pull Request, it launches a Preview Branch and runs the migrations in `./supabase/migrations`. If there are any errors they are logged to the [Check Run](https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28) associated with that git commit. When all checks turn green, your new Preview Branch is ready to use.

When you push a new migration file to the Git branch, the app runs it incrementally in your Preview Branch. This allows you verify schema changes easily on existing seed data.

Finally, when you merge that PR, the app runs the new migrations on your Production environment. If you have other PRs already open, make sure to update those migration files to a later timestamp than the ones in Production branch following a [standard migration practice](https://supabase.com/docs/guides/cli/managing-environments).

## Data seeding

You can seed your Preview branch in the same way that you [seed your local development environment](https://supabase.com/docs/guides/cli/seeding-your-database). Just add `./supabase/seed.sql` in your repo and the seed script will run when the Preview Branch is created.

Optionally, you can reset the database by running `supabase db reset --db-url <branch-connection-string>`. The branch connection string can be retrieved using your Personal Access Token with Supabase CLI's [branch management](https://supabase.com/docs/reference/cli/supabase-branches-get) commands.

We're investigating data masking techniques with a copy-on-write system so that you can emulate a production workload inside your Preview Branches. We plan for this to work with File Storage too.

> _Testing with product workloads today?_
If you need to test with production workloads today, check out [Snaplet](https://www.snaplet.dev/) and [Postgres.ai](http://postgres.ai/). Both are great partners of Supabase.

## Future considerations

That's already a lot for Branching v0. Branching will be a core part of the developer workflow in the future. These are the themes we'll explore next:

**Declarative config**
We're still working on “configuration in code”. For example, you might want to try a different Google Auth in your Preview Branch than the one you use in Product. This would be a lot easier if the code was declarative, inside the [config.toml ](https://supabase.com/docs/guides/cli/config)file.

**Automatic dashboard commits**
In the current version, when you use the dashboard to create a change on a Preview Branch, you need to run `db diff` locally to pull that change into your Git repository. We plan to work on a feature to automatically capture your changes in a Git repo that you've connected.

**Extended seeding behavior**
There are a multitude of different strategies for populating seed data. We've dabbled with AI to generate a seed data, which was fun. We also like the approach of [postgresql-anonymizer](https://postgresql-anonymizer.readthedocs.io/en/stable/) and [Snaplet](https://docs.snaplet.dev/recipes/supabase), who specialize in cloning production data while anonymizing the data for safe development.

**Copy-on-write**
We have something in development :). CoW means you can branch from database snapshot and then run tests on “production-like” workloads. This is the approach that [Postgres.ai](http://postgres.ai/) uses. As we mention above, we need to figure out an approach that also works with [File Storage.](https://supabase.com/storage)

## Interested in using Branching?

We still have our early-access form open, and we'll be onboarding organizations in batches over the next few weeks, and working with these early users on Pricing.

Check out the [Branching docs](https://supabase.com/docs/guides/platform/branching) and also if you have any feedback, [you can join the discussion.](https://github.com/orgs/supabase/discussions/18937)

## More Launch Week X

- [Day 1 - Supabase Studio update: AI Assistant and User Impersonation](https://supabase.com/blog/studio-introducing-assistant)
- [Day 2 - Edge Functions: Node and native npm compatibility
](https://supabase.com/blog/edge-functions-node-npm)
- [Postgres Language Server: implementing the Parser](https://supabase.com/blog/postgres-language-server-implementing-parser)
- [The Supabase Album](https://www.youtube.com/watch?v=r1POD-IdG-I)
- [Supabase Launch Week X Hackathon](https://supabase.com/blog/supabase-hackathon-lwx)
- [Launch Week X Community Meetups](https://supabase.com/blog/community-meetups-lwx)

{% cta http://supabase.com?utm_source=devto&utm_medium=referral&utm%5C_term=devtocta %} 🚀 Learn more about Supabase {% endcta %}