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

feat(docs): new branching docs (#36890)

Browse Source 
* feat(docs): new branching docs

Reorganize branching docs and add Gitless branching page

* style: fix lint and formatting issues

* chore: document email notification for failures

* docs(branching): fix review comments

* branch merge updates

---------

Co-authored-by: Qiao Han <qiao@supabase.io>
Co-authored-by: Saxon Fletcher <saxonafletcher@gmail.com>
This commit is contained in:
CharisQiao HanSaxon Fletcher
 authored and GitHub committed 2025-07-16 09:45:19 -04:00
1 parent 944aba84ae
commit 85bd0d4f9b
8 files changed
+727 -761
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+20 -1
View File
@@ -2453,7 +2453,26 @@ export const deployment: NavMenuConstant = {
items: [
{ name: 'Managing environments', url: '/guides/deployment/managing-environments' },
{ name: 'Database migrations', url: '/guides/deployment/database-migrations' },
{ name: 'Branching', url: '/guides/deployment/branching' },
],
},
{
name: 'Branching',
url: undefined,
items: [
{ name: 'Overview', url: '/guides/deployment/branching' },
{ name: 'GitHub integration', url: '/guides/deployment/branching/github-integration' },
{
name: 'Branching 2.0 (Alpha)',
url: '/guides/deployment/branching/branching-2',
},
{
name: 'Working with branches',
url: '/guides/deployment/branching/working-with-branches',
},
{ name: 'Configuration', url: '/guides/deployment/branching/configuration' },
{ name: 'Integrations', url: '/guides/deployment/branching/integrations' },
{ name: 'Troubleshooting', url: '/guides/deployment/branching/troubleshooting' },
{ name: 'Billing', url: '/guides/platform/manage-your-usage/branching' },
],
},
{
apps/docs/content/guides/deployment/branching.mdx
+4 -760
View File
@@ -1,772 +1,16 @@
---
title: 'Branching'
description: 'Use Supabase Branches to test and preview changes.'
subtitle: 'Use Supabase Branches to test and preview changes'
---
Use branching to safely 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.
Supabase branches create separate environments that spin off from your main project. You can use these branching environments to create and test changes like new configurations, database schemas, or features 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.
## How branching works
- **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 auto-pause after <SharedData data="config">branching.inactivity_period_in_minutes</SharedData> minutes of inactivity. Upon receiving a new request to your database or REST API, the paused branch will automatically resume to serve the request. The implications of this architecture means
- `pg_cron` jobs will not execute in an auto-paused database.
- Larger variance in request latency due to database cold starts.
If you need higher performance guarantees on your Preview Environment, you can switch individual branches to [persistent](/docs/guides/deployment/branching#persistent-branches) so they are not auto-paused.
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt="Each branch has a separate Supabase instance."
caption="Each Branch is a separate environment."
src={{
dark: '/docs/img/guides/platform/branching/github-workflow-without-branching.jpg?v=1',
light: '/docs/img/guides/platform/branching/github-workflow-without-branching--light.jpg?v=1',
}}
/>
### 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](#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.
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.
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:
<Image
zoomable
className="max-w-[700px] !mx-auto"
alt="Each GitHub branch can have its own Supabase preview branch."
caption="Each GitHub branch can have its own Supabase preview branch."
src={{
dark: '/docs/img/guides/platform/branching/github-workflow.jpg?v=1',
light: '/docs/img/guides/platform/branching/github-workflow--light.jpg?v=1',
}}
/>
When you merge your Git branch into the production branch, all new migrations will be applied to your Production environment. If you have declared Storage buckets or Edge Functions in `config.toml`, they will also be deployed automatically. All other configurations, including API, Auth, and seed files, will be ignored by default.
<Admonition type="note" label="Data changes are not merged into production." />
### Preparing your Git repository
You can use the [Supabase CLI](/docs/guides/cli) to manage changes inside a local `./supabase` directory:
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="existing"
queryGroup="platform"
>
<TabPanel id="existing" label="Existing project">
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Initialize Supabase locally" fullWidth>
If you don't have a `./supabase` directory, you can create one:
```markdown
supabase init
```
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Pull your database migration" fullWidth>
Pull your database changes using `supabase db pull`. To get your database connection string, go to your project dashboard, click [Connect](https://supabase.com/dashboard/project/_?showConnect=true) and look for the Session pooler connection string.
```markdown
supabase db pull --db-url <db_connection_string>
# Your Database connection string will look like this:
# postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
```
<Admonition type="note">
If you're in an [IPv6 environment](https://github.com/orgs/supabase/discussions/27034) or have the IPv4 Add-On, you can use the direct connection string instead of Supavisor in Session mode.
</Admonition>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3}>
<StepHikeCompact.Details title="Commit the `supabase` directory to Git" fullWidth>
Commit the `supabase` directory to Git, and push your changes to your remote repository.
```bash
git add supabase
git commit -m "Initial migration"
git push
```
</StepHikeCompact.Details>
</StepHikeCompact.Step>
</StepHikeCompact>
</TabPanel>
<TabPanel id="new" label="New Project">
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:
```bash
npx create-next-app -e with-supabase
```
Push your new project to a GitHub repo. For more information, see the GitHub guides on [creating](https://docs.github.com/en/get-started/quickstart/create-a-repo) and [pushing code](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) to a new repository.
</TabPanel>
</Tabs>
### Enable Supabase branching
Once your repository is [correctly prepared](#preparing-your-git-repository), you can enable branching from the Supabase dashboard.
<Admonition type="caution" label="Prepare your GitHub repository before enabling Branching">
If your repository doesn't have all the migration files, your production branch could run an incomplete set of migrations. Make sure your [GitHub repository is prepared](#preparing-your-git-repository).
</Admonition>
<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" />
</figure>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Install the GitHub integration" fullWidth>
When clicking `Enable branching` you will see the following dialog:
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-opt-in-install-github.jpg?v=1" />
</figure>
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`.
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-opt-in-install-github-permissions.jpg?v=1" />
</figure>
Follow the instructions to link your Supabase project to its GitHub repository.
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-opt-in-install-github-integration-link.jpg?v=1" />
</figure>
Return to your project and re-click `Enable branching`.
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3}>
<StepHikeCompact.Details title="You should now see a popover with the GitHub Connection details shown" fullWidth>
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.
<Admonition type="caution" label="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.
</Admonition>
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-opt-in-install-production-branch.jpg?v=1" />
</figure>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<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>
### 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.
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Create a new Git branch in your GitHub repository" fullWidth>
You need at least one other branch aside from your Supabase production branch.
<figure className="max-w-[520px]">
<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>
</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`](/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" />
</figure>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3}>
<StepHikeCompact.Details title="Create a Supabase preview branch" fullWidth>
Click `Create preview branch`.
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-first-preview-branch-branch-action.jpg?v=1" />
</figure>
Type in the branch name you want to add. Click `Create branch` to confirm.
<Admonition type="note" label="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
</Admonition>
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/enable-supabase-branching-first-preview-branch-choose-branch.jpg?v=1" />
</figure>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
</StepHikeCompact>
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](#develop-locally) or [remotely](#develop-remotely). Local development is recommended.
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="local-dev"
queryGroup="making-updates"
>
<TabPanel id="local-dev" label="Local Development">
The Supabase CLI provides two options: [manual migrations](https://supabase.com/docs/guides/deployment/database-migrations) and [generated migrations](https://supabase.com/docs/guides/deployment/database-migrations#diffing-changes) using Supabase's local studio and the `supabase db-diff` command. Let's use the latter and push the change to our Preview Branch:
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Make schema changes locally" fullWidth>
Start Supabase locally:
```bash
supabase start
```
Then proceed to [localhost:54323](http://localhost:54323) to access your local Supabase dashboard.
You can make changes in either the [Table Editor](http://localhost:54323/project/default/editor) or the [SQL Editor]((http://localhost:54323/project/default/sql)).
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Generate a migration file" fullWidth>
Once you are finished making database changes, run `supabase db diff` to create a new migration file. For example:
```bash
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:
```bash
supabase db reset
```
This will reset the database and run all the migrations again. The local dashboard at [localhost:54323](http://localhost:54323) will reflect the new changes you made.
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3}>
<StepHikeCompact.Details title="Commit your changes and push." fullWidth>
Commit and push your migration file to your remote GitHub repository. For example:
```bash
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.
</StepHikeCompact.Details>
</StepHikeCompact.Step>
</StepHikeCompact>
</TabPanel>
<TabPanel id="remote-dev" label="Remote Development">
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.
<Admonition type="note" label="Changes must be locally pulled and committed to keep your Git repository state in sync.">
Dashboard changes aren't automatically reflected in your Git repository. If you'd like to see automatic syncing in a future release, [join the discussion](https://github.com/orgs/supabase/discussions/18937).
</Admonition>
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Select the branch you want to use." fullWidth>
Select the branch you wish to use in your Supabase [project](https://supabase.com/dashboard/project/_).
<figure className="max-w-[520px]">
<Image src="/docs/img/guides/platform/branching/develop-your-app-develop-remotely.jpg?v=1" />
</figure>
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Make changes to your database schema." fullWidth>
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>
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.
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={4}>
<StepHikeCompact.Details title="Pull changes from remote database." fullWidth>
In your local terminal, navigate to the directory for your Supabase project and use the Supabase CLI to pull changes from your branch to your local migrations directory.
Make sure to use the database URL for your branch:
```bash
supabase db pull --db-url "postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres"
```
</StepHikeCompact.Details>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={5}>
<StepHikeCompact.Details title="Commit and push your migration file." fullWidth>
No new migrations will be run on your remote Preview Branch after pushing your changes. 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.
</StepHikeCompact.Details>
</StepHikeCompact.Step>
</StepHikeCompact>
</TabPanel>
</Tabs>
### 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.
### Persistent branches
Persistent branches are the type of branches that will remain active even after the underlying PR is closed. Any PR based on a persistent branch will also have a corresponding preview branch created automatically.
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
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.
### Using ORM or custom seed scripts
If you want to use your own ORM for managing migrations and seed scripts, you will need to run them in GitHub Actions after the preview branch is ready. The branch credentials can be fetched using the following example GHA workflow.
```yaml
on:
pull_request:
types:
- opened
- reopened
- synchronize
branches:
- main
paths:
- 'supabase/**'
jobs:
wait:
runs-on: ubuntu-latest
outputs:
status: ${{ steps.check.outputs.conclusion }}
steps:
- uses: fountainhead/action-wait-for-check@v1.2.0
id: check
with:
checkName: Supabase Preview
ref: ${{ github.event.pull_request.head.sha }}
token: ${{ secrets.GITHUB_TOKEN }}
migrate:
needs:
- wait
if: ${{ needs.wait.outputs.status == 'success' }}
runs-on: ubuntu-latest
steps:
- uses: supabase/setup-cli@v1
with:
version: latest
- run: supabase --experimental branches get "$GITHUB_HEAD_REF" -o env >> $GITHUB_ENV
- name: Custom ORM migration
run: psql "$POSTGRES_URL_NON_POOLING" -c 'select 1'
```
## Branch configuration with remotes
When Branching is enabled, your `config.toml` settings automatically sync to all ephemeral branches through a one-to-one mapping between your Git and Supabase branches.
### Basic configuration
To update configuration for a Supabase branch, modify `config.toml` and push to git. The Supabase integration will detect the changes and apply them to the corresponding branch.
### Remote-specific configuration
For persistent branches that need specific settings, you can use the `[remotes]` block in your `config.toml`. Each remote configuration must reference an existing project ID.
Here's an example of configuring a separate seed script for a staging environment:
```toml
[remotes.staging]
project_id = "your-project-ref"
[remotes.staging.db.seed]
sql_paths = ["./seeds/staging.sql"]
```
Since the `project_id` field must reference an existing branch, you need to create the persistent branch before adding its configuration. Use the CLI to create a persistent branch first:
```bash
supabase --experimental branches create --persistent
# Do you want to create a branch named develop? [Y/n]
```
### Configuration merging
When merging a PR into a persistent branch, the Supabase integration:
1. Checks for configuration changes
2. Logs the changes
3. Applies them to the target remote
If no remote is declared or the project ID is incorrect, the configuration step is skipped.
### Available configuration options
All standard configuration options are available in the `[remotes]` block. This includes:
- Database settings
- API configurations
- Authentication settings
- Edge Functions configuration
- And more
You can use this to maintain different configurations for different environments while keeping them all in version control.
### Managing secrets for branches
For sensitive configuration like SMTP credentials or API keys, you can use the Supabase CLI to manage secrets for your branches. This is especially useful for custom SMTP setup or other services that require secure credentials.
To set secrets for a persistent branch:
```bash
# Set secrets from a .env file
supabase secrets set --env-file ./supabase/.env
# Or set individual secrets
supabase secrets set SMTP_HOST=smtp.example.com
supabase secrets set SMTP_USER=your-username
supabase secrets set SMTP_PASSWORD=your-password
```
These secrets will be available to your branch's services and can be used in your configuration. For example, in your `config.toml`:
```toml
[auth.smtp]
host = "env(SMTP_HOST)"
user = "env(SMTP_USER)"
password = "env(SMTP_PASSWORD)"
```
<Admonition type="note" label="Secrets are branch-specific">
Secrets set for one branch are not automatically available in other branches. You'll need to set them separately for each branch that needs them.
</Admonition>
#### Using dotenvx for git-based workflow
For managing environment variables across different branches, you can use [dotenvx](https://dotenvx.com/) to securely manage your configurations. This approach is particularly useful for teams working with Git branches and preview deployments.
##### Environment file structure
Following the conventions used in the [example repository](https://github.com/supabase/supabase/blob/master/examples/slack-clone/nextjs-slack-clone-dotenvx/README.md), environments are configured using dotenv files in the `supabase` directory:
| File | Environment | `.gitignore` it? | Encrypted |
| --------------- | ----------- | ---------------- | --------- |
| .env.keys | All | Yes | No |
| .env.local | Local | Yes | No |
| .env.production | Production | No | Yes |
| .env.preview | Branches | No | Yes |
| .env | Any | Maybe | Yes |
##### Setting up encrypted secrets
1. Generate key pair and encrypt your secrets:
```bash
npx @dotenvx/dotenvx set SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET "<your-secret>" -f supabase/.env.preview
```
This creates a new encryption key in `supabase/.env.preview` and a new decryption key in `supabase/.env.keys`.
2. Update project secrets:
```bash
npx supabase secrets set --env-file supabase/.env.keys
```
3. Choose your configuration approach in `config.toml`:
Option A: Use encrypted values directly:
```toml
[auth.external.github]
enabled = true
secret = "encrypted:<encrypted-value>"
```
Option B: Use environment variables:
```toml
[auth.external.github]
enabled = true
client_id = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_CLIENT_ID)"
secret = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET)"
```
<Admonition type="note" label="Secret fields">
The `encrypted:` syntax only works for designated "secret" fields in the configuration (like `secret` in auth providers). Using encrypted values in other fields will not be automatically decrypted and may cause issues. For non-secret fields, use environment variables with the `env()` syntax instead.
</Admonition>
##### Using with preview branches
When you commit your `.env.preview` file with encrypted values, the branching executor will automatically retrieve and use these values when deploying your branch. This allows you to maintain different configurations for different branches while keeping sensitive information secure.
### 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.
### Seeding behavior
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.
## 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](https://vercel.com/integrations/supabase) or
- By clicking the blue `Deploy` button in a Supabase example app's `README` file
<Admonition type="note" label="Vercel GitHub integration also required.">
For branching to work with Vercel, you also need the [Vercel GitHub integration](https://vercel.com/docs/deployments/git/vercel-for-github).
</Admonition>
And make sure you have [connected](/dashboard/org/_/integrations) your Supabase project to your Vercel project.
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](https://github.com/orgs/supabase/discussions/18938).
## Alternatives to branching
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.).
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.
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
Branching is available on the Pro Plan and above. The price is:
- Each Preview branch costs <Price price="0.01344" /> per hour
- Each Preview branch is billed until it is removed
## 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.
### Network restrictions
If you enable [network restrictions](/docs/guides/platform/network-restrictions) on your project, the branching cluster will be blocked from connecting to your project by default. This often results in database connection failures when migrating your production project after merging a development branch.
The workaround is to explicitly allow the IPv6 CIDR range of the branching cluster in your project's [database settings](https://supabase.com/dashboard/project/_/settings/database) page: `2600:1f18:2b7d:f600::/56`
<Image
alt="Network restrictions to allow connections from branching cluster"
src={{
dark: '/docs/img/guides/branching/cidr-dark.png',
light: '/docs/img/guides/branching/cidr-light.png',
}}
className="max-w-[550px] !mx-auto border rounded-md"
zoomable
/>
### 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 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).
- **Persistent Branches**: Persistent branches are long-lived branches. They aren't automatically paused or deleted due to non-inactivity or merging.
- **GitHub integration and Branching 2.0**: You can use branching with the GitHub integration, or use Branching 2.0 to manage your branches without Git (in Feature Preview).
- **Data-less**: New branches do not start with any data from your main project. This is meant to better protect your sensitive production data. To start your branches with data, you can use a [seed file](/docs/guides/deployment/branching/github-integration#seeding) if using the GitHub integration.
apps/docs/content/guides/deployment/branching/branching-2.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: 'Branching 2.0 (Alpha)'
subtitle: 'Create and manage branches without using Git'
---
Branching 2.0 allows you to create and manage Supabase branches without connecting to a Git repository. This is useful for quick testing, prototyping, or when you prefer to manage your database changes outside of Git.
<Admonition type="note" label="Public Alpha">
Branching 2.0 is currently in public alpha. Features and functionality may change.
</Admonition>
## How Branching 2.0 works
With Branching 2.0, you can do the following directly from the Supabase dashboard:
- Create preview branches
- Make changes to your public schema or edge functions
- Merge these changes back into production when ready
- Pull in updates from production
## Enable Branching 2.0
Branching 2.0 is available as a Feature Preview. To enable Branching 2.0 in the Supabase Dashboard:
1. Open the user menu by clicking on your user icon in the top right.
1. Select **Branching 2.0**.
1. Click **Enable feature**.
## Creating a branch
Once you've enabled Branching 2.0, you can create a new branch:
1. Click the arrows next to the branch name in the top menu bar. (The top menu bar has the format `YOUR_ORGANIZATION / YOUR_PROJECT / CURRENT_BRANCH_NAME`.)
2. Click `Create branch`.
## Making changes to a branch
Use the branch selector in the top bar to change to your branch. Any changes you make (including SQL run in the SQL editor, table editor changes, and configuration changes) are now made against the currently selected branch.
You can also use the branch's API keys and connection strings to run changes against the branch from your own code or SQL client.
## Creating a merge request
To review and merge changes from a branch back into your production branch, you must first create a merge request. There are two ways to do this.
The first is to click the merge request button next to the branch selector that's located in the top menu. This will create the merge request and redirect you to the merge page where you can review and merge any changes.
The second is to click on manage branches from within the branch selector, then in the left hand navigation you can click on merge requests. From here you can view all open merge requests and create new ones.
## Pulling changes from production into a branch
When reviewing a merge request you may see a notice at the top of the page asking you to update your branch. This appears when your preview branch has drifted from your production branch. There may be public schema or edge function changes that have been made after your preview branch was created. Clicking update branch will attempt to pull in these changes, but be aware that by doing this your existing edge functions will be replaced. Any new edge functions created on the preview branch will remain untouched.
## Limitations
There are a few limitations you should be aware of before deciding to use branching without git.
- Custom roles created through the dashboard are not captured on branch creation
- Only public schema changes are supported right now
- Extensions are not included in the diff process
- Branches can only be merged to main; merging between preview branches is not supported
- If your branch is out of date, you can pull in latest changes from main, but keep in mind that all functions will be overwritten
- Deleting functions must be done manually on main branch
- Migration conflicts must be manually resolved on the preview branch
- If you have run migrations on main, new branches will be created from existing migrations instead of a full schema dump
apps/docs/content/guides/deployment/branching/configuration.mdx
+207
View File
@@ -0,0 +1,207 @@
---
title: 'Configuration'
subtitle: 'Configure your Supabase branches using configuration as code'
---
This guide covers how to configure your Supabase branches, using the `config.toml` file. In one single file, you can configure all your branches, including branch settings and secrets.
## Branch configuration with remotes
When Branching is enabled, your `config.toml` settings automatically sync to all ephemeral branches through a one-to-one mapping between your Git and Supabase branches.
### Basic configuration
To update configuration for a Supabase branch, modify `config.toml` and push to git. The Supabase integration will detect the changes and apply them to the corresponding branch.
### Remote-specific configuration
For persistent branches that need specific settings, you can use the `[remotes]` block in your `config.toml`. Each remote configuration must reference an existing project ID.
Here's an example of configuring a separate seed script for a staging environment:
```toml
[remotes.staging]
project_id = "your-project-ref"
[remotes.staging.db.seed]
sql_paths = ["./seeds/staging.sql"]
```
Since the `project_id` field must reference an existing branch, you need to create the persistent branch before adding its configuration. Use the CLI to create a persistent branch first:
```bash
supabase --experimental branches create --persistent
# Do you want to create a branch named develop? [Y/n]
```
### Configuration merging
When merging a PR into a persistent branch, the Supabase integration:
1. Checks for configuration changes
2. Logs the changes
3. Applies them to the target remote
If no remote is declared or the project ID is incorrect, the configuration step is skipped.
### Available configuration options
All standard configuration options are available in the `[remotes]` block. This includes:
- Database settings
- API configurations
- Authentication settings
- Edge Functions configuration
- And more
You can use this to maintain different configurations for different environments while keeping them all in version control.
## Managing secrets for branches
For sensitive configuration like SMTP credentials or API keys, you can use the Supabase CLI to manage secrets for your branches. This is especially useful for custom SMTP setup or other services that require secure credentials.
To set secrets for a persistent branch:
```bash
# Set secrets from a .env file
supabase secrets set --env-file ./supabase/.env
# Or set individual secrets
supabase secrets set SMTP_HOST=smtp.example.com
supabase secrets set SMTP_USER=your-username
supabase secrets set SMTP_PASSWORD=your-password
```
These secrets will be available to your branch's services and can be used in your configuration. For example, in your `config.toml`:
```toml
[auth.smtp]
host = "env(SMTP_HOST)"
user = "env(SMTP_USER)"
password = "env(SMTP_PASSWORD)"
```
<Admonition type="note" label="Secrets are branch-specific">
Secrets set for one branch are not automatically available in other branches. You'll need to set them separately for each branch that needs them.
</Admonition>
### Using dotenvx for git-based workflow
For managing environment variables across different branches, you can use [dotenvx](https://dotenvx.com/) to securely manage your configurations. This approach is particularly useful for teams working with Git branches and preview deployments.
#### Environment file structure
Following the conventions used in the [example repository](https://github.com/supabase/supabase/blob/master/examples/slack-clone/nextjs-slack-clone-dotenvx/README.md), environments are configured using dotenv files in the `supabase` directory:
| File | Environment | `.gitignore` it? | Encrypted |
| --------------- | ----------- | ---------------- | --------- |
| .env.keys | All | Yes | No |
| .env.local | Local | Yes | No |
| .env.production | Production | No | Yes |
| .env.preview | Branches | No | Yes |
| .env | Any | Maybe | Yes |
#### Setting up encrypted secrets
1. Generate key pair and encrypt your secrets:
```bash
npx @dotenvx/dotenvx set SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET "<your-secret>" -f supabase/.env.preview
```
This creates a new encryption key in `supabase/.env.preview` and a new decryption key in `supabase/.env.keys`.
2. Update project secrets:
```bash
npx supabase secrets set --env-file supabase/.env.keys
```
3. Choose your configuration approach in `config.toml`:
Option A: Use encrypted values directly:
```toml
[auth.external.github]
enabled = true
secret = "encrypted:<encrypted-value>"
```
Option B: Use environment variables:
```toml
[auth.external.github]
enabled = true
client_id = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_CLIENT_ID)"
secret = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET)"
```
<Admonition type="note" label="Secret fields">
The `encrypted:` syntax only works for designated "secret" fields in the configuration (like `secret` in auth providers). Using encrypted values in other fields will not be automatically decrypted and may cause issues. For non-secret fields, use environment variables with the `env()` syntax instead.
</Admonition>
#### Using with preview branches
When you commit your `.env.preview` file with encrypted values, the branching executor will automatically retrieve and use these values when deploying your branch. This allows you to maintain different configurations for different branches while keeping sensitive information secure.
## Configuration examples
### Multi-environment setup
Here's an example of a complete multi-environment configuration:
```toml
# Default configuration for all branches
[api]
enabled = true
port = 54321
schemas = ["public", "storage", "graphql_public"]
[db]
port = 54322
pool_size = 10
# Staging-specific configuration
[remotes.staging]
project_id = "staging-project-ref"
[remotes.staging.api]
max_rows = 1000
[remotes.staging.db.seed]
sql_paths = ["./seeds/staging.sql"]
# Production-specific configuration
[remotes.production]
project_id = "prod-project-ref"
[remotes.production.api]
max_rows = 500
[remotes.production.db]
pool_size = 25
```
### Feature branch configuration
For feature branches that need specific settings:
```toml
[remotes.feature-oauth]
project_id = "feature-branch-ref"
[remotes.feature-oauth.auth.external.google]
enabled = true
client_id = "env(GOOGLE_CLIENT_ID)"
secret = "env(GOOGLE_CLIENT_SECRET)"
```
## Next steps
- Explore [branching integrations](/docs/guides/deployment/branching/integrations)
- Learn about [troubleshooting branches](/docs/guides/deployment/branching/troubleshooting)
- Review [branching pricing](/docs/guides/deployment/branching/pricing)
apps/docs/content/guides/deployment/branching/github-integration.mdx
+102
View File
@@ -0,0 +1,102 @@
---
title: 'GitHub integration'
subtitle: 'Connect with GitHub to sync branches with your repository'
---
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.
## Installation
In the Supabase Dashboard:
1. Go to **Project Settings** > [**Integrations**](/dashboard/project/_/settings/integrations).
2. Under **GitHub Integration**, click **Authorize GitHub**.
3. You are redirected to a GitHub authorization page. Click **Authorize Supabase**.
4. You are redirected back to the Integrations page. Choose a GitHub repository to connect your project to.
5. Fill in the relative path to the Supabase directory from your repository root.
6. Configure the other options as needed to automate your GitHub connection.
7. Click **Enable integration**.
## Syncing GitHub branches
Enable the **Automatic branching** option in your GitHub Integration configuration to automatically sync GitHub branches with Supabase branches.
When a new branch is created in GitHub, a corresponding branch is created in Supabase. (You can enable the **Supabase changes only** option to only create Supabase branches when Supabase files change.)
### Configuration
You can test configuration changes on your Preview Branch by configuring the `config.toml` file in your Supabase directory. See the [Configuration docs](/docs/guides/deployment/branching/configuration) for more information.
A comment is added to your PR with the deployment status of your preview branch.
### Migrations
The migrations in the `migrations` subdirectory of your Supabase directory are automatically run.
### Seeding
No production data is copied to your Preview branch. This is meant to protect your sensitive production data.
You can seed your Preview Branch with sample data using the `seed.sql` file in your Supabase directory. See the [Seeding docs](/docs/guides/local-development/seeding-your-database) for more information.
Data changes in your seed files are not merged to production.
## Deploying changes to production
Enable the **Deploy to production** option in your GitHub Integration configuration to automatically deploy changes when you push or merge to production branch.
The following changes are deployed:
- New migrations are applied
- Edge Functions declared in `config.toml` are deployed
- Storage buckets declared in `config.toml` are deployed
All other configurations, including API, Auth, and seed files, are ignored by default.
## 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"
/>
### Email notifications
To catch failures early, we also recommend subscribing to email notifications on your branch. Common errors include migration conflict, function deployment failure, or invalid configuration file.
You can setup a custom GitHub Action to monitor the status of any Supabase Branch.
```yaml name=.github/workflows/notify-failure.yaml
name: Branch Status
on:
pull_request:
types:
- opened
- reopened
- synchronize
branches:
- main
- develop
paths:
- 'supabase/**'
jobs:
failed:
runs-on: ubuntu-latest
steps:
- uses: fountainhead/action-wait-for-check@v1.2.0
id: check
with:
checkName: Supabase Preview
ref: ${{ github.event.pull_request.head.sha || github.sha }}
token: ${{ secrets.GITHUB_TOKEN }}
- if: ${{ steps.check.outputs.conclusion == 'failure' }}
run: exit 1
```
apps/docs/content/guides/deployment/branching/integrations.mdx
+30
View File
@@ -0,0 +1,30 @@
---
title: 'Integrations'
description: 'Use Supabase branching with hosting providers and other tools.'
subtitle: 'Use Supabase branching with hosting providers and other tools'
---
Branching works with hosting providers that support preview deployments. Learn how to integrate Supabase branching with various platforms and tools.
## Hosting providers
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](https://vercel.com/integrations/supabase) or
- By clicking the blue `Deploy` button in a Supabase example app's `README` file
<Admonition type="note" label="Vercel GitHub integration also required.">
For branching to work with Vercel, you also need the [Vercel GitHub integration](https://vercel.com/docs/deployments/git/vercel-for-github).
</Admonition>
And make sure you have [connected](/dashboard/org/_/integrations) your Supabase project to your Vercel project.
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.
apps/docs/content/guides/deployment/branching/troubleshooting.mdx
+169
View File
@@ -0,0 +1,169 @@
---
title: 'Troubleshooting'
description: 'Common issues and solutions for Supabase branching.'
subtitle: 'Common issues and solutions for Supabase branching'
---
This guide covers common issues you might encounter when using Supabase branching and how to resolve them.
## Common issues
### 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.
### Network restrictions
If you enable [network restrictions](/docs/guides/platform/network-restrictions) on your project, the branching cluster will be blocked from connecting to your project by default. This often results in database connection failures when migrating your production project after merging a development branch.
The workaround is to explicitly allow the IPv6 CIDR range of the branching cluster in your project's [database settings](https://supabase.com/dashboard/project/_/settings/database) page: `2600:1f18:2b7d:f600::/56`
<Image
alt="Network restrictions to allow connections from branching cluster"
src={{
dark: '/docs/img/guides/branching/cidr-dark.png',
light: '/docs/img/guides/branching/cidr-light.png',
}}
className="max-w-[550px] !mx-auto border rounded-md"
zoomable
/>
### 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).
## Migration issues
### Failed migrations
When migrations fail, check:
1. **SQL syntax**: Ensure your migration files contain valid SQL
2. **Dependencies**: Check if migrations depend on objects that don't exist
3. **Permissions**: Verify the migration doesn't require superuser privileges
To debug:
```bash
# Test migrations locally first
supabase db reset
# Check migration logs in the dashboard
# Navigate to Branches > Your Branch > View Logs
```
### Migration order problems
Migrations must run in the correct order. Common issues:
1. **Timestamp conflicts**: Ensure migration files have unique timestamps
2. **Dependency issues**: Later migrations depending on earlier ones
3. **Rebase problems**: Timestamps getting out of order after Git rebase
Fix by:
```bash
# Rename migration files to fix timestamp order
mv 20240101000000_old.sql 20240102000000_old.sql
# Reset local database to test
supabase db reset
```
## Connection issues
### Cannot connect to preview branch
If you can't connect to a preview branch:
1. **Check credentials**: Ensure you're using the correct branch-specific credentials
2. **Auto-pause**: The branch might be paused. It will resume on the first request
3. **Network restrictions**: Check if network restrictions are blocking access
### Connection timeouts
Preview branches auto-pause after inactivity. First connections after pause may timeout:
1. **Retry**: The branch will wake up after the first request
2. **Persistent branches**: Convert frequently-used branches to persistent
## Configuration problems
### Config.toml not applying
If configuration changes aren't applying:
1. **Syntax errors**: Validate your `config.toml` syntax
2. **Git sync**: Ensure changes are committed and pushed
3. **Branch refresh**: Try deleting and recreating the branch
### Secrets not available
If secrets aren't working in your branch:
1. **Branch-specific**: Remember secrets are set per branch
2. **Syntax**: Use correct syntax: `env(SECRET_NAME)`
3. **CLI version**: Ensure you're using the latest CLI version
## Performance issues
### Slow branch creation
Branch creation might be slow due to:
1. **Large migrations**: Many or complex migration files
2. **Seed data**: Large seed files take time to process
3. **Network latency**: Geographic distance from the branch region
### Query performance
Preview branches may have different performance characteristics:
1. **Cold starts**: First queries after auto-pause are slower
2. **Resource limits**: Preview branches have different resource allocations
3. **Indexing**: Ensure proper indexes exist in your migrations
## Data issues
### Seed data not loading
If seed data isn't loading:
1. **File location**: Ensure `seed.sql` is in `./supabase/` directory
2. **SQL errors**: Check for syntax errors in seed file
3. **Dependencies**: Seed data might reference non-existent tables
### Data persistence
Remember that preview branch data:
1. **Is temporary**: Data is lost when branch is deleted
2. **Isn't migrated**: Data doesn't move between branches
3. **Resets on recreation**: Deleting and recreating branch loses data
## Getting help
If you're still experiencing issues:
1. **Check logs**: Review branch logs in the dashboard
2. **Community**: Ask in [GitHub discussions](https://github.com/orgs/supabase/discussions/18937)
3. **Support**: Contact support for project-specific issues
4. **Documentation**: Review the latest documentation for updates
apps/docs/content/guides/deployment/branching/working-with-branches.mdx
+128
View File
@@ -0,0 +1,128 @@
---
title: 'Working with branches'
description: 'Learn how to develop and manage your Supabase branches.'
subtitle: 'Learn how to develop and manage your Supabase branches'
---
This guide covers how to work with Supabase branches effectively, including migration management, seeding behavior, and development workflows.
## 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.
### Using ORM or custom seed scripts
If you want to use your own ORM for managing migrations and seed scripts, you will need to run them in GitHub Actions after the preview branch is ready. The branch credentials can be fetched using the following example GHA workflow.
```yaml name=.github/workflows/custom-orm.yaml
name: Custom ORM
on:
pull_request:
types:
- opened
- reopened
- synchronize
branches:
- main
paths:
- 'supabase/**'
jobs:
wait:
runs-on: ubuntu-latest
outputs:
status: ${{ steps.check.outputs.conclusion }}
steps:
- uses: fountainhead/action-wait-for-check@v1.2.0
id: check
with:
checkName: Supabase Preview
ref: ${{ github.event.pull_request.head.sha || github.sha }}
token: ${{ secrets.GITHUB_TOKEN }}
migrate:
needs:
- wait
if: ${{ needs.wait.outputs.status == 'success' }}
runs-on: ubuntu-latest
steps:
- uses: supabase/setup-cli@v1
with:
version: latest
- run: supabase --experimental branches get "$GITHUB_HEAD_REF" -o env >> $GITHUB_ENV
- name: Custom ORM migration
run: psql "$POSTGRES_URL_NON_POOLING" -c 'select 1'
```
### 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.
### Seeding behavior
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.
## Developing with branches
You can develop with branches using either local or remote development workflows.
### Local development workflow
1. Create a new Git branch for your feature
2. Make schema changes using the Supabase CLI
3. Generate migration files with `supabase db diff`
4. Test your changes locally
5. Commit and push to GitHub
6. Open a pull request to create a preview branch
### Remote development workflow
1. Create a preview branch in the Supabase dashboard
2. Switch to the branch using the branch dropdown
3. Make schema changes in the dashboard
4. Pull changes locally using `supabase db pull`
5. Commit the generated migration files
6. Push to your Git repository
## Managing branch environments
### Switching between branches
Use the branch dropdown in the Supabase dashboard to switch between different branches. Each branch has its own:
- Database instance
- API endpoints
- Authentication settings
- Storage buckets
### Accessing branch credentials
Each branch has unique credentials that you can find in the dashboard:
1. Switch to your desired branch
2. Navigate to Settings > API
3. Copy the branch-specific URLs and keys
### Branch isolation
Branches are completely isolated from each other. Changes made in one branch don't affect others, including:
- Database schema and data
- Storage objects
- Edge Functions
- Auth configurations
## Next steps
- Learn about [branch configuration](/docs/guides/deployment/branching/configuration)
- Explore [integrations](/docs/guides/deployment/branching/integrations)
- Review [troubleshooting guide](/docs/guides/deployment/branching/troubleshooting)