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.

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

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 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, 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.

Even in relaxed developer environments, if one of your team accidentally leaks 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 deployments. This means that you get an entire stack with Branching.

We've made several improvements to our Vercel Integration 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.

Developing on the hosted Preview Branch#

One of the most-loved features of Supabase is the dashboard. Even if we beg, 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. Once you're happy with your changes, you simply run supabase db diff on your local machine 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. 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 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 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 to 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 the Production branch following a standard migration practice.

Data seeding#

You can seed your Preview branch in the same way that you seed your local development environment. 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 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.

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 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 seed data, which was fun. We also like the approach of postgresql-anonymizer and Snaplet, which 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 uses. As we mentioned above, we need to figure out an approach that also works with File Storage.

We'll be onboarding organizations in batches over the next few weeks, and working with these early users on Pricing.

Update 17th January 2024 - Early access for Branching is now closed for the foreseeable future. We are now working hard towards releasing a public beta.

Check out the Branching docs and also if you have any feedback, you can join the discussion.