Use Supabase Branches to test and preview changes
Branching is only available on the Pro Plan and above.
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.
Branching is in Alpha
It is not recommended to use Branching in a production environment.
Branching is an Alpha feature. To try out branching for non-production experiments, request access here.
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.
Only schema changes are captured in preview branches.
Preview Branch instances contain no data by default. You must include a seed file to seed your preview instance with sample data when the Preview Branch is created. Future versions of Branching may allow for automated data seeding and cloning.
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
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
If you prefer not to use branching, you can manage your environments and tests in other ways:
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.
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#
Github integration required
Supabase branching requires the GitHub integration. Your application must be developed in a GitHub repository.
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.
- 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:
_10npx create-next-app -e with-supabase
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.
Get set up before turning on branching
Setting up the initial state incorrectly can cause migrations to be wrongly applied.
Follow the instructions below before turning on Supabase branching.
If your migration files are already in GitHub, under
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:
Inside your project directory, initialize your configuration for Supabase local development:_10supabase init
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:email@example.com:5432/postgres_10supabase db pull --db-url <db_url>
supabasedirectory to Git, and push your changes to your remote repository._10git add supabase_10git commit -m "Initial migration"_10git push
Enable Supabase branching#
Once your repository is correctly prepared, you can enable branching from the Supabase dashboard.
Prepare your repo before enabling Branching
Before turning on branching, make sure your GitHub repository is prepared. If your repository doesn’t have all the migration files, your production branch could run an incomplete set of migrations.
Branching is early access only
Sign up for early access (here)[https://forms.supabase.com/branching-request].
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.
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
Follow the instructions to link your Supabase project to its GitHub repository.
Return to your project and re-click
If you see the following dialog, you’re in the alpha testing group
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.
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.
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.
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
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
Create a Supabase preview branch
Create preview branch.
Type in the branch name you want to add. Click
Create branch to confirm.
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.
supabase directory should include:
- All SQL migration files, under the subdirectory
- An optional
seed.sqlfile, 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.
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.
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:
Create a new migration file._10supabase migration new "new_feature"
Add SQL statements to your new migration file.
You can manually edit the new migration file, or use local studio and diff the changes._10create table employees (_10id integer primary key generated always as identity,_10name text_10)
Commit and push your migration file._10git add supabase/migrations_10git commit -m "Add employees table"_10git 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.
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.
Changes must be locally pulled and committed to keep your GitHub repository state in sync.
Dashboard changes aren’t automatically reflected in your repository. If you’d like to see automatic syncing in a future release, join the discussion.
Click on the active branch in the top bar to open the dropdown menu. Select the branch you want to use.
Make changes to your database schema from the Supabase dashboard.
Reset database password for the branch. To do this, navigate to
https://supabase.com/dashboard/project/[branch-ref]/settings/databaseand click Reset database password. Save the new password for use in the next step.
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._10supabase db pull --db-url "postgres://postgres:[password]@db.[branch-ref].supabase.co:5432/postgres"
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.
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.
Your Preview Branches are seeded with sample data from the file
The database is only seeded once, when the preview branch is created. To rerun seeding, delete the preview branch and recreate it.
Migrations are failing#
The GitHub integration automatically checks for new migrations on every commit. It runs any new migrations found in
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 Branching support is in development.
The Vercel Integration for Supabase branching is under development. To express your interest, join the discussion on GitHub discussions.
Install the Vercel integration:
- From the Vercel marketplace or
- By clicking the blue
Deploybutton in a Supabase example app’s
For branching to work with Vercel, you also need the Vercel GitHub integration.
Supabase automatically updates your Vercel project with the correct environment variables for the corresponding preview branches.
A Netlify integration is under consideration. If you’re interested in branching with Netlify, join the GitHub discussion.
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.