dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 17:35:10 +03:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update branching docs (#30977)

Browse Source 
* chore: update docs branching

* chore: update docs

* chore: update titles casing

* chore: update casing title

* chore: casing

* chore: nitpicks

* chore: more reviedog comments

* Update apps/docs/content/guides/deployment/branching.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* chore: merge images

* chore: reword and simplify docs

---------

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
This commit is contained in:
Andrew ValleteauandCharis authored and GitHub committed 2025-01-08 03:12:18 +00:00
1 parent 1969be0908
commit 541cc205a9
1 file changed
+83 -125
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/guides/deployment/branching.mdx
+83 -125
View File
@@ -14,7 +14,15 @@ 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.
- **Separate Environments**: Each branch is a separate environment with its own Supabase instance and API credentials.
- **Git Integration**: Branching works with Git, currently supporting GitHub repositories.
- **Preview Branches**: You can create multiple Preview Branches for testing.
- **Migrations and Seeding**: Branches run migrations from your repository and can seed data using a `seed.sql` file.
## Prerequisites
- **Supabase Project**: You need an existing Supabase project.
- **GitHub Repository**: Your project must be connected to a GitHub repository containing your Supabase directory.
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 <SharedData data="config">branching.inactivity_period_in_minutes</SharedData> minutes of inactivity. Note that `pg_cron` executions will be impacted by inactivity related pausing.
@@ -35,17 +43,15 @@ Preview Branch instances contain no data by default. You must include a seed fil
## Git providers
To manage code changes, your Supabase project must be connected to a Git repository. At this stage we only support [GitHub](#branching-with-github). If you are interested in other Git providers, join the [discussion](<(https://github.com/orgs/supabase/discussions/18936)>) for GitLab, BitBucket, and non-Git based Branching.
To manage code changes, your Supabase project must be connected to a Git repository. At this stage, we only support [GitHub](#branching-with-github). If you are interested in other Git providers, join the [discussion](https://github.com/orgs/supabase/discussions/18936) 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 and configured based on the [`config.toml`](/docs/guides/local-development/cli/config) configuration on this branch, the migrations from the corresponding Git branch are run on the Preview 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.
The Preview Branch is also [seeded](/docs/guides/local-development/seeding-your-database) with sample data based on `./supabase/seed.sql` by default, if that file exists.
Supabase Branching follows the [Trunk Based Development](https://trunkbaseddevelopment.com/) workflow, with one main Production branch and multiple development branches:
@@ -60,47 +66,10 @@ Supabase Branching follows the [Trunk Based Development](https://trunkbaseddevel
}}
/>
### 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](#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:
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt="New migration files trigger migrations on the preview instance."
caption="New migration files trigger migrations on the preview instance."
src={{
dark: '/docs/img/guides/platform/branching/github-workflow-commit-migration.jpg?v=1',
light: '/docs/img/guides/platform/branching/github-workflow-commit-migration--light.jpg?v=1',
}}
/>
### 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.
When you merge your Git branch into the production branch, all new migrations will be applied to your Production environment based on the changes made to your [`config.toml`](/docs/guides/local-development/cli/config).
<Admonition type="note" label="Data changes are not merged into production." />
### 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](#branching-with-github). If you are interested in other Git providers, join the [discussion](<(https://github.com/orgs/supabase/discussions/18936)>) for GitLab, BitBucket, and non-Git based Branching.
## How to use Supabase branching
Supabase Branching requires a hosted [Git provider](#git-providers). 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](/docs/guides/cli) to manage changes inside a local `./supabase` directory:
@@ -197,11 +166,9 @@ If your repository doesn't have all the migration files, your production branch
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Inside your Supabase project, click `Enable branching`" fullWidth>
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-opt-in-popover.jpg?v=1" />
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-opt-in-popover.jpg?v=1" />
</figure>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
@@ -253,14 +220,40 @@ If your repository doesn't have all the migration files, your production branch
<StepHikeCompact.Step step={4}>
<StepHikeCompact.Details title="Click `I understand, enable branching`. Branching is now enabled for your project." fullWidth>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
</StepHikeCompact>
### Create your first preview branch
### 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.
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt="GitHub view of the deployment status of your preview branch"
caption="Supabase GitHub integration will comment on your PR with the status of your Preview Branch, including whether migrations have successfully run."
src="/docs/img/guides/platform/branching/develop-your-app-open-pull-request-github.jpg?v=1"
/>
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.
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt='Check the "Require status checks to pass before merging" option.'
caption='Check the "Require status checks to pass before merging" option.'
src="/docs/img/guides/platform/branching/github-required-check.jpg?v=1"
/>
### Manually create a preview branch
Preview branches are automatically created for each pull request, but you can also manually create one.
@@ -274,15 +267,12 @@ Preview branches are automatically created for each pull request, but you can al
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-first-preview-branch-github.jpg?v=1" />
<figcaption>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`.</figcaption>
</figure>
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`.
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Navigate to the Branches page in your Supabase dashboard." fullWidth>
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`.
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`](/dashboard/project/_/branches).
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-first-preview-branch-branch-dropdown.jpg?v=1" />
@@ -309,7 +299,7 @@ Preview branches are automatically created for each pull request, but you can al
</Admonition>
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-first-preview-branch-choose-branch.jpg?v=1" />
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-first-preview-branch-choose-branch.jpg?v=1" />
</figure>
</StepHikeCompact.Details>
@@ -317,8 +307,6 @@ Preview branches are automatically created for each pull request, but you can al
</StepHikeCompact>
### 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`
@@ -442,15 +430,15 @@ Dashboard changes aren't automatically reflected in your Git repository. If you'
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Make changes to your database schema." fullWidth>
Make changes to your schema with either with the [Table Editor](https://supabase.com/dashboard/project/_/editor) or the [SQL Editor]((https://supabase.com/dashboard/project/_/sql)).
Make changes to your schema with either the [Table Editor](https://supabase.com/dashboard/project/_/editor) or the [SQL Editor]((https://supabase.com/dashboard/project/_/sql)).
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3}>
<StepHikeCompact.Details title="Check you have the password for the Preview Branch database." fullWidth>
<StepHikeCompact.Details title="Check you have the password for the preview branch database." fullWidth>
If you don't know the password, you must Reset the database password so you know the password. Go to the [database setting page](https://supabase.com/dashboard/project/_/settings/database) and click `Reset database password`.
If you don't know the password, you must reset the database password so you know the password. Go to the [database setting page](https://supabase.com/dashboard/project/_/settings/database) and click `Reset database password`.
Save the new password securely for future use.
@@ -488,34 +476,6 @@ Dashboard changes aren't automatically reflected in your Git repository. If you'
</TabPanel>
</Tabs>
### 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.
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt="GitHub view of the deployment status of your preview branch"
caption="Supabase GitHub integration will comment on your PR with the status of your Preview Branch, including whether migrations have successfully run."
src="/docs/img/guides/platform/branching/develop-your-app-open-pull-request-github.jpg?v=1"
/>
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.
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt='Check the "Require status checks to pass before merging" option.'
caption='Check the "Require status checks to pass before merging" option.'
src="/docs/img/guides/platform/branching/github-required-check.jpg?v=1"
/>
### Disable branching
You can disable branching at any time. Navigate to the [Branches](/dashboard/project/_/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.
@@ -523,7 +483,7 @@ You can disable branching at any time. Navigate to the [Branches](/dashboard/pro
### 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](/dashboard/project/_/branches) page by clicking triple dots icon next to the branch you want to modify, and selecting "Switch to persistent".
You can change any branch to be persistent on the [Branches](/dashboard/project/_/branches) page by clicking the 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
@@ -593,32 +553,10 @@ The new preview branch is reseeded from your `./supabase/seed.sql` file by defau
### Seeding behavior
Your Preview Branches are seeded with sample data from the file `./supabase/seed.sql` by default.
Your Preview Branches are seeded with sample data using the same as [local seeding behavior](/docs/guides/local-development/seeding-your-database).
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](#disable-branching).
## Branching and hosting providers
Branching works with hosting providers that support preview deployments.
@@ -648,19 +586,13 @@ There are multiple alternative Git providers under consideration. If you're inte
## 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.
Under the hood, you can see Supabase branching as a way to programmatically "duplicate" your Supabase project via git flow. This allows spawning a new configured (via [`config.toml`](/docs/guides/local-development/cli/config)) and seeded instance of the database and the adjacent Supabase services (buckets, edge functions, etc.).
If you prefer not to use branching, you can manage your environments and tests in other ways:
1. A new project is deployed on behalf of the user on the Supabase side as the new "branch" if it doesn't already exist. This includes the database, storage, edge-function, and all Supabase-related services.
2. The branch is cloned and the new project is configured based on the [`config.toml`](/docs/guides/local-development/cli/config) committed into this project branch.
3. Migrations are applied and seeding scripts are run (the first time) for this branch.
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.
You can make a similar setup with a distinct project for each environment. Or just have two environments, the localhost and the production one.
## Pricing
@@ -669,10 +601,36 @@ 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.
## Troubleshooting
### 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 the latest changes, then delete the preview branch in Supabase and reopen it.
The new preview branch is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.
### Deployment failures
A deployment might fail for various reasons, including invalid SQL statements and schema conflicts in migrations. Errors within the `config.toml` config or something else.
To check the error message, see the Supabase workflow run for your branch under the [View logs](/dashboard/project/_/branches) section.
### Schema drift between preview branches
If multiple preview branches exist, 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 that haven't been merged yet.
These conflicts can be resolved in the same way as normal Git Conflicts: merge or rebase from the production Git branch to the 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](#disable-branching).
## 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.
Supabase branching is a new and exciting part of the Supabase development ecosystem. Feedback is welcome.
You can join the [conversation over in GitHub discussions](https://github.com/orgs/supabase/discussions/18937).