Branching

Use Supabase Branches to test and preview changes

Use branching to safely and easily experiment with changes to your Supabase project.

Supabase branches work like Git branches. They let you create and test changes like new configurations, database schemas, or features in a separate, temporary instance without affecting your production setup.

When you're ready to ship your changes, merge your branch to update your production instance with the new changes.

If you understand Git, you already understand Supabase Branching.

How branching works#

Supabase projects can consist of multiple Preview Branches. All Preview Branches are backed by an isolated Supabase instance. Each instance contains all Supabase features, and has its own API credentials.

Supabase branching works like Git branching, with one main Production branch. Preview Branches branch off your Production branch and contain proposed changes. These changes can then be merged into Production.

When you create a Preview Branch, the SQL migration files from your Production branch are run on the new Preview Branch. The Preview Branch then reflects your current Production branch schema.

The Preview Branch will also be seeded with sample data if a seed file exists.

By creating new SQL migrations in a Preview Branch to propose schema changes, those changes can then be merged into your Production branch. These changes then run the new migrations on your Supabase Production branch. This is exactly how Git branches work: experiment on a feature branch and merge back into Production when you're finished.

Git providers#

To facilitate Supabase Branching, your Supabase project will be connected to a Git repository via an integration.

Supabase Branching works with GitHub. Future iterations may support other Git providers. If you are interested in other Git providers or a non-Git-based workflow, join the discussions for GitLab Branching, BitBucket Branching, and non-Git based Branching.

Branching with GitHub#

Supabase Branching uses the Supabase GitHub integration to read files from your GitHub repository. With this integration, Supabase watches all commits, branches, and pull requests of your GitHub repository.

In Git, you have a Production Branch (typically this is main, master, prod, etc). This should also be your Supabase project's Production Branch.

You can create a corresponding Preview Branch for any Git branch in your repository. Each time a new Preview Branch is created, the migrations in the Git branch of that Preview Branch are run on the Preview Branch.

The Preview Branch is also seeded with sample data based on ./supabase/seed.sql, if that file exists.

Each time a commit is pushed with new migrations in the ./supabase/migrations directory, the migrations are run on the matching preview instance.

Alternatives to branching#

If you don’t turn on branching, your Supabase project continues to work as a single branch, on a single instance. You have a single set of API keys for each project, and no preview instances are created. It's the Git equivalent of working directly on the main branch.

If you prefer not to use branching, you can manage your environments and tests in other ways:

1. Host a project per environment, and test against a staging project

   Create multiple projects on Supabase with the same schema. Use one project as a staging environment to test any changes. Then migrate tested changes to the production project.

2. Host a single production project, and test locally

   Create a single project to host your production instance. Test any changes locally, then run the migrations against your hosted production project.

You can also combine both strategies to perform both local and staging tests.

How to use Supabase Branching#

Preparing your GitHub repository#

You need a GitHub repository to use Supabase branching. The ./supabase directory in your repository contains your SQL migration files and your database seed file.

To start:

• If you don't have a new project, set one up using the example template.
• If you have an existing project, make sure your database-related files are up to date.

Set up a new project with the example template#

Use the Next.js example template to try out branching. This template includes sample migration and seed files to get you started.

Run the following command in your terminal to clone the example:

Push your new project to a GitHub repo. For more information, see the GitHub guides on creating and pushing code to a new repository.

Set up an existing project for branching#

Before enabling branching on an existing project, make sure your database-related files are up to date. You need a current snapshot of your existing database, so newer migration files have a foundation to run on top of.

If your migration files are already in GitHub, under ./supabase/migrations:

If your migration files are up to date with your production database, you don’t need to do anything. You can now turn on branching.

If you don't have migration files in GitHub:

You need to take a snapshot of your database. Log into Supabase from the command line client and pull the relevant files. Then commit them to GitHub:

1. Inside your project directory, initialize your configuration for Supabase local development:

   
   

   _10

   supabase init

   
   

2. Pull down database-related files. You can find your database URL in your database settings, under the URI tab of the Connection String settings panel. It will look something like postgresql://username:password@db.ref.supabase.co:5432/postgres

   
   

   _10

   supabase db pull --db-url <db_url>

   
   

3. Commit the supabase directory to Git, and push your changes to your remote repository.

   
   

   _10

   git add supabase

   _10

   git commit -m "Initial migration"

   _10

   git push

   
   

Enable Supabase branching#

Once your repository is correctly prepared, you can enable branching from the Supabase dashboard.

1. Select the project you want to use, then click Enable branching. If you’re prompted to join the waitlist, click Join waitlist. Access will be expanded as branching graduates from alpha testing.

2. If you see the following dialog, you’re in the alpha testing group.

   If you don’t have the GitHub integration installed, click Install GitHub Integration. The integration is required to run migration files and the optional database seed file.

   You’re taken to the GitHub integration page. Click Install.

   Follow the instructions to link your Supabase project to its GitHub repository.

   Return to your project and re-click Enable branching.

3. You should now see a popover with the GitHub Connection details shown.

   Type in the branch you want to use for production. The name of the branch will be validated to make sure it exists in your GitHub repository.

   caution

   Your production branch can’t be changed while branching is enabled. To change your production branch, you need to disable branching and re-enable it with a different branch.

4. Click I understand, enable branching. Branching is now enabled for your project.

Create your first preview branch#

Preview branches are automatically created for each pull request, but you can also manually create one.

1. Create a new Git branch in your GitHub repository

   You need at least one other branch aside from your Supabase production branch.

   You can use the GitHub dashboard or command line to create a new branch. In this example, the new branch is called feat/add-members.

2. Navigate to the Branches page in your Supabase dashboard.

   In the Supabase dashboard, look for the branch dropdown on the right-hand side of the top bar. It should be set to your production branch by default. Open the dropdown and click Manage branches.

3. Create a Supabase preview branch

   Click Create preview branch.

   Type in the branch name you want to add. Click Create branch to confirm.

   note

   Only branches from the repository can be used to create a Preview Branch

   Git branches from external contributors currently can’t support a Preview Branch

Develop your app with Supabase branches#

Supabase branching uses the state of your GitHub repository to apply migrations and seed preview instances. It checks the supabase directory at the top level of your repository.

The supabase directory should include:

• All SQL migration files, under the subdirectory migrations
• An optional seed.sql file, used to seed preview instances with sample data

The GitHub integration watches for changes in the migrations directory. When it detects a new migration file, it runs the new migration against the matching preview instance.

You can create new migrations either locally or remotely.

Local development is recommended for developers familiar with the Supabase CLI, who want to test changes on their local machine. Remote development is recommended if you don’t want to run Supabase locally, or if you want to collaborate with team members via the dashboard interface.

Develop locally#

You can develop locally by running Supabase on your local machine. You’ll have a database running locally, and another database running remotely on the preview branch.

You can experiment on your local database by writing SQL migrations yourself. You can also auto-generate migration files by using Supabase’s local studio and the supabase db-diff command.

Once you’re confident in your migration files, push your changes to your remote GitHub repository to update the preview branch.

To create and push local migrations:

1. Create a new migration file.

   
   

   _10

   supabase migration new "new_feature"

   
   

2. Add SQL statements to your new migration file.

   You can manually edit the new migration file, or use local studio and diff the changes.

   
   

   _10

   create table employees (

   _10

   id integer primary key generated always as identity,

   _10

   name text

   _10

   )

   
   

3. Commit and push your migration file.

   
   

   _10

   git add supabase/migrations

   _10

   git commit -m "Add employees table"

   _10

   git push --set-upstream origin new-employee

   
   

Supabase’s GitHub integration detects the new migration and runs it against the branch instance.

It can take up to 10 minutes for migrations to be applied. If you have a PR for your branch, errors are reflected in the GitHub check run status and in a PR comment.

If you need to reset your database to a clean state (that is, discard any changes that aren’t reflected in the migration files), run supabase db reset locally. Then, delete the preview branch and recreate it.

Develop remotely#

As an alternative to developing locally, you can make changes on your remote Supabase dashboard. You can then pull these changes to your local machine and commit them to GitHub.

1. Click on the active branch in the top bar to open the dropdown menu. Select the branch you want to use.

2. Make changes to your database schema from the Supabase dashboard.

3. Reset database password for the branch. To do this, navigate to https://supabase.com/dashboard/project/[branch-ref]/settings/database and click Reset database password. Save the new password for use in the next step.

4. In your terminal, navigate to the directory for your Supabase project. Use the Supabase client to pull changes from your branch to your local migrations directory. Make sure to use the database URL for your branch.

   
   

   _10

   supabase db pull --db-url "postgres://postgres:[password]@db.[branch-ref].supabase.co:5432/postgres"

   
   

5. Commit and push your migration file. No new migrations are run. This is expected, because your database is already up-to-date, based on the changes you made in the dashboard. But this ensures that your migration files are in GitHub, so they can be correctly merged into production.

Open a pull request#

When you open a pull request on GitHub, the Supabase integration automatically checks for a matching preview branch. If one doesn’t exist, it gets created.

A comment is added to your PR with the deployment status of your preview branch. Statuses are shown separately for Database, Services, and APIs.

Every time a new commit is pushed that changes the migration files in ./supabase/migrations, the new migrations are run against the preview branch. You can check the status of these runs in the comment’s Tasks table.

GitHub required check setting#

We highly recommend turning on a ‘required check’ for the Supabase integration. You can do this from your GitHub repository settings.

This prevents PRs from being merged when migration checks fail, and stops invalid migrations from being merged into your production branch.

Disable branching#

You can disable branching at any time. Navigate to the Branches page, which can be found via the Branches dropdown menu on the top navigation, then click "Manage Branches" in the menu. Click the 'Disable branching' button at the top of the Overview section.

Migration and seeding behavior#

Migrations are run in sequential order. Each migration builds upon the previous one.

The preview branch has a record of which migrations have been applied, and only applies new migrations for each commit. This can create an issue when rolling back migrations.

Rolling back migrations#

You might want to roll back changes you’ve made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.

To fix this, push your latest changes, then delete the preview branch in Supabase and reopen it.

The new preview branch is reseeded from your ./supabase/seed.sql file. Any additional data changes you made on the old preview branch are lost. This is equivalent to running supabase db reset locally. All migrations are rerun in sequential order.

Seeding behavior#

Your Preview Branches are seeded with sample data from the file ./supabase/seed.sql.

The database is only seeded once, when the preview branch is created. To rerun seeding, delete the preview branch and recreate it.

Troubleshooting#

Migrations are failing#

The GitHub integration automatically checks for new migrations on every commit. It runs any new migrations found in ./supabase/migrations.

A migration might fail for various reasons, including invalid SQL statements, and schema conflicts. If a migration fails, the Supabase integration check is shown as failing.

To check the error message, see the Supabase integration comment on your PR.

Schemas drift between preview branches#

If you have multiple preview branches, each preview branch might contain different schema changes. This is similar to Git branches, where each branch might contain different code changes.

When a preview branch is merged into the production branch, it creates a schema drift between the production branch and the preview branches you haven’t merged yet.

You can solve thse conflicts the way you would solve normal Git Conflicts: merge or rebase from your production Git branch to your preview Git branch. Since migrations are applied sequentially, ensure that migration files are timestamped correctly after the rebase. Changes that build on top of earlier changes should always have later timestamps.

Changing Production Branch#

It’s not possible to change the Git branch used as the Production branch for Supabase Branching. The only way to change it is to disable and re-enable branching. See Disable Branching.

Branching and hosting providers#

Branching works with hosting providers that support preview deployments.

With the Supabase branching integration, you can sync the Git branch used by the hosting provider with the corresponding Supabase preview branch. This means that the preview deployment built by your hosting provider is matched to the correct database schema, edge functions, and other Supabase configurations.

Vercel#

Install the Vercel integration:

• From the Vercel marketplace or

• By clicking the blue Deploy button in a Supabase example app’s README file

  note

Supabase automatically updates your Vercel project with the correct environment variables for the corresponding preview branches.

Netlify#

A Netlify integration is under consideration. If you’re interested in branching with Netlify, join the GitHub discussion.

Feedback#

Supabase branching is a new and exciting new part of the Supabase development ecosystem. We’re monitoring its success and open to any feedback.

You can join the conversation over in GitHub discussions.