Home

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 Branching works with Git. You can test changes in a separate, temporary environment 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.

You can run multiple Preview Branches for every Supabase project. Branches contain all the Supabase features with their own API credentials. Preview Environments pause automatically after 5 minutes of inactivity. Note that pg_cron executions will be impacted by inactivity related pausing.

Branching workflow

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 after we are confident that we can provide safe data masking.

Git providers

To manage code changes, your Supabase project must be connected to a Git repository. At this stage we only support GitHub. If you are interested in other Git providers, join the discussion for GitLab, BitBucket, 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 by default, if that file exists.

Supabase Branching follows the Trunk Based Development workflow, with one main Production branch and multiple development branches:

Production branch

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

Preview branches

After connecting your Supabase project to one of the supported Git providers, a corresponding Supabase Preview will be created whenever a new Git branch is created.

The Git integration can read files from your Git provider, watching every commit and pull request. Each time a commit is pushed with new migrations in the ./supabase/migrations directory, the migrations are run on the matching Supabase Preview environment:

Data changes

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

For security reasons, Preview Branches do not contain production data. Future versions of Branching may allow for automated data cloning after we are confident that we can provide safe data masking.

Merging production changes

When you merge your Git branch into the production branch, all new migrations will be applied to your Production environment.

Git providers

We currently support GitHub. If you are interested in other Git providers, join the discussion for GitLab, BitBucket, and non-Git based Branching.

How to use Supabase branching

Supabase Branching requires a hosted Git provider. Follow these steps to connect your Supabase project to a Git provider, and enable branching.

Preparing your Git repository

You can use the Supabase CLI to manage changes inside a local ./supabase directory:

1

Initialize Supabase locally

If you don't have a ./supabase directory, you can create one:


supabase init

2

Pull your database migration

Pull your database changes using supabase db pull. You can find your database URL in your database settings, under the URI tab of the Connection String settings panel. Make sure Use connection pooling is checked so you can use the IPv4-enabled connection pooler. (Without connection pooling, your database is only accessible over IPv6, which isn't yet supported by all network providers.)


supabase db pull --db-url <db_url>
# Your Database URL looks something like:
# postgres://postgres.xxxx:[email protected]:6543/postgres

3

Commit the `supabase` directory to Git

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


git add supabase
git commit -m "Initial migration"
git push

Enable Supabase branching

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

1

Inside your Supabase project, click `Enable branching`

2

Install the GitHub integration

When clicking Enable branching you will see the following dialog:

If you don't have the GitHub integration installed, click Add new project connection. 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.

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.

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.

Make changes to your branch

The Git integration watches for changes in the supabase directory. This includes:

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

You can create new migrations either locally or remotely. Local development is recommended.

The Supabase CLI provides two options: manual migrations and generated migrations using Supabase's local studio and the supabase db-diff command. Let's use the latter and push the change to our Preview Branch:

1

Make schema changes locally

Start supabase locally:


supabase start

Then proceed to localhost:54323 to access your local Supabase dashboard.

You can make changes in either the Table Editor or the SQL Editor.

2

Generate a migration file

Once you are finished making database changes, run supabase db diff to create a new migration file. For example:


supabase db diff -f "add_employees_table"

This will create a SQL file called ./supabase/migrations/[timestamp]add_employees_table.sql. This file will reflect the changes that you made in your local dashboard.

If you want to continue making changes, you can manually edit this migration file, then use the db reset command to pick up your edits:


supabase db reset

This will reset the database and run all the migrations again. The local dashboard at localhost:54323 will reflect the new changes you made.

3

Commit your changes and push.

Commit and push your migration file to your remote GitHub repository. For example:


git add supabase/migrations
git commit -m "Add employees table"
git push --set-upstream origin new-employee

The Supabase integration detects the new migration and runs it on the remote Preview Branch. 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 by closing, and reopening your pull request.

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.

Preventing migration failures

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.

Persistent branches

Persistent branches are the type of branches that will remain active even after the underlying PR is closed. You can change any branch to be persistent on Branches page by clicking triple dots icon next to the branch you want to modify, and selecting "Switch to persistent". All persistent branches can be toggled back to be an ephemeral branch in the exact same way.

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 by default. 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 by default.

The database is only seeded once, when the preview branch is created. To rerun seeding, delete the preview branch and recreate it by closing, and reopening your pull request.

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 these 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

Supabase automatically updates your Vercel project with the correct environment variables for the corresponding preview branches. The synchronization happens at the time of Pull Request being opened, not at the time of branch creation. As branching integration is tied to the Preview Deployments feature in Vercel, there are possible race conditions between Supabase setting correct variables, and Vercel running a deployment process. Because of that, Supabase is always automatically re-deploying the most recent deployment of the given pull request.

Other Git providers

There are multiple alternative Git providers under consideration. If you're interested in branching for GitLab, Bitbucket, or some other provider, join the GitHub discussion.

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.

Pricing

Branching is available on the Pro Plan and above. The price is:

  • Each Preview branch costs $0.32 per day
  • Each Preview branch is billed until it is removed

Prices listed are subject to change.

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.