mirror of
https://github.com/supabase/supabase.git
synced 2026-07-03 12:14:26 +08:00
386 lines
13 KiB
Plaintext
386 lines
13 KiB
Plaintext
---
|
||
id: cicd-workflow
|
||
title: CI / CD Workflow
|
||
description: How to deploy Supabase schema changes with a CI / CD pipeline.
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs'
|
||
import TabItem from '@theme/TabItem'
|
||
|
||
## Overview
|
||
|
||
The Supabase CLI also functions as a database migrations tool. In this guide, we will show you how to setup your local Supabase development environment that integrates with GitHub Action to automatically test and release schema changes to staging and production Supabase projects.
|
||
|
||
- `develop` branch tracks staging
|
||
- `main` branch tracks production
|
||
|
||
|
||
|
||
Before you start, here are some prerequisites:
|
||
|
||
- [Install the Supabase CLI](/docs/guides/cli)
|
||
- Create a Supabase project
|
||
- Initialise a local Git repository
|
||
|
||
You can use your existing Supabase project and Git repository to follow this guide. Otherwise, you can [create a new project](https://app.supabase.com/?next=new-project) and set up an empty Git repository.
|
||
|
||
## Setting up a project
|
||
|
||
The first step is to set up your local repository with the Supabase CLI. You can do this by running:
|
||
|
||
```bash
|
||
supabase init
|
||
```
|
||
|
||
You should see that a new `supabase` directory is created. Then you need to link your local repository with your Supabase project:
|
||
|
||
```sql
|
||
supabase login
|
||
supabase link --project-ref $PROJECT_ID
|
||
```
|
||
|
||
You can get your `$PROJECT_ID` from your project’s dashboard URL:
|
||
|
||
```
|
||
https://app.supabase.com/project/<project-id>
|
||
```
|
||
|
||
If you’re using an existing Supabase project, you might have made schema changes through the dashboard. You need to pull these changes before making local schema changes from the CLI. You can do this by running:
|
||
|
||
```sql
|
||
supabase db remote commit
|
||
```
|
||
|
||
This command creates a new migration in `supabase/migrations/<timestamp>_remote_commit.sql` that reflects all the schema changes you might have made beforehand.
|
||
|
||
Now commit your local changes to Git and run the local development setup:
|
||
|
||
```sql
|
||
supabase start
|
||
```
|
||
|
||
You are now ready to develop schema changes locally and create your first migration 🎉
|
||
|
||
## Creating a new migration
|
||
|
||
There are two ways to make schema changes in a version controlled way.
|
||
|
||
1. Write DDL statements manually into a migration file
|
||
2. Make changes through Studio UI and auto generate a schema diff
|
||
|
||
For this guide, we will create an `employees` table using the schema below.
|
||
|
||
```sql
|
||
create table public.employees (
|
||
id integer primary key generated always as identity,
|
||
name text
|
||
);
|
||
```
|
||
|
||
### Manual migration
|
||
|
||
|
||
|
||
The first step is to create a new migration script. You can do this by running:
|
||
|
||
```bash
|
||
supabase migration new new_employee
|
||
```
|
||
|
||
You should see that a new file `supabase/migrations/<timestamp>_new_employee.sql` is created. You can then write any DDL statements in this script using a text editor.
|
||
|
||
Alternatively, the new migration command also supports stdin as input. This allows you to pipe in an existing script from another file or stdout.
|
||
|
||
```bash
|
||
supabase migration new new_employee < create_employees_table.sql
|
||
```
|
||
|
||
Next, you want to apply the new migration to your local database. You can do so by running:
|
||
|
||
```bash
|
||
supabase db reset
|
||
```
|
||
|
||
This command recreates your local database from scratch and applies all migration scripts under `supabase/migrations` directory. Now your local database is up to date.
|
||
|
||
### Auto schema diff
|
||
|
||
The key difference between manual migration is that auto schema diff creates a new migration script from changes **already** applied to your local database.
|
||
|
||
|
||
|
||
The first step is to create an `employees` table under the `public` schema using Studio UI (accessible at [http://localhost:54323](http://localhost:54323/) by default).
|
||
|
||
Next, generate a schema diff by running the following command:
|
||
|
||
```bash
|
||
supabase db diff -f new_employee
|
||
```
|
||
|
||
You should see that a new file `supabase/migrations/<timestamp>_new_employee.sql` is created. Open the file and verify that the generated DDL statements are the same as below.
|
||
|
||
```sql
|
||
-- This script was generated by the Schema Diff utility in pgAdmin 4
|
||
-- For the circular dependencies, the order in which Schema Diff writes the objects is not very sophisticated
|
||
-- and may require manual changes to the script to ensure changes are applied in the correct order.
|
||
-- Please report an issue for any failure with the reproduction steps.
|
||
|
||
CREATE TABLE IF NOT EXISTS public.employees
|
||
(
|
||
id integer NOT NULL GENERATED ALWAYS AS IDENTITY ( INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 2147483647 CACHE 1 ),
|
||
name text COLLATE pg_catalog."default",
|
||
CONSTRAINT employees_pkey PRIMARY KEY (id)
|
||
)
|
||
|
||
TABLESPACE pg_default;
|
||
|
||
ALTER TABLE IF EXISTS public.employees
|
||
OWNER to postgres;
|
||
|
||
GRANT ALL ON TABLE public.employees TO anon;
|
||
|
||
GRANT ALL ON TABLE public.employees TO authenticated;
|
||
|
||
GRANT ALL ON TABLE public.employees TO postgres;
|
||
|
||
GRANT ALL ON TABLE public.employees TO service_role;
|
||
```
|
||
|
||
You may notice that the auto generated migration script is more verbose than the manually written one. This is because the schema diff tool we use under the hood does not take into account of default privileges added by the initial schema.
|
||
|
||
Alternatively, you may pass in the `--use-migra` experimental flag to generate a more concise schema diff.
|
||
|
||
```sql
|
||
supabase db diff --use-migra
|
||
```
|
||
|
||
Without the `-f` file flag, the output will be written to stdout by default.
|
||
|
||
Finally, commit the new migration script to git and you are ready to deploy 🎉
|
||
|
||
## Deploying a migration
|
||
|
||
In a real project, you might not want to deploy migrations directly from your local machine as other engineers could be pushing features simultaneously. Instead, you would use a CI/CD pipeline to deploy new migrations.
|
||
|
||
|
||
|
||
In this section, we will show how to set up a CI/CD workflow with the CLI on GitHub Actions. We will use two projects here, one for production and one for staging. The prerequisites are:
|
||
|
||
- Create separate Supabase projects for staging and production
|
||
- Push your Git repository to GitHub and enable GitHub Actions
|
||
|
||
> ⚠️ You need a _new_ project for staging. A project which has already been modified to reflect the production project’s schema can’t be used because the CLI would reapply these changes.
|
||
|
||
### Configure GitHub Actions
|
||
|
||
The Supabase CLI requires a few environment variables to run in non-interactive mode.
|
||
|
||
- `SUPABASE_ACCESS_TOKEN` is your personal access token
|
||
- `SUPABASE_DB_PASSWORD` is your project specific database password
|
||
|
||
We recommend adding these as [encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to your GitHub Action runners.
|
||
|
||
Here are the workflow files we will be using for this guide:
|
||
|
||
- `.github/workflows/ci.yml`:
|
||
|
||
```yaml
|
||
name: CI
|
||
|
||
on:
|
||
pull_request:
|
||
workflow_dispatch:
|
||
|
||
jobs:
|
||
test:
|
||
runs-on: ubuntu-22.04
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- uses: supabase/setup-cli@v1
|
||
with:
|
||
version: 1.0.0
|
||
|
||
- name: Start Supabase local development setup
|
||
run: supabase start
|
||
|
||
- name: Verify generated types are up-to-date
|
||
run: |
|
||
supabase gen types typescript --local > types.ts
|
||
if [ "$(git diff --ignore-space-at-eol types.ts | wc -l)" -gt "0" ]; then
|
||
echo "Detected uncommitted changes after build. See status below:"
|
||
git diff
|
||
exit 1
|
||
fi
|
||
```
|
||
|
||
- `.github/workflows/production.yml`:
|
||
|
||
```yaml
|
||
name: Deploy Migrations to Production
|
||
|
||
on:
|
||
push:
|
||
branches:
|
||
- main
|
||
workflow_dispatch:
|
||
|
||
jobs:
|
||
deploy:
|
||
runs-on: ubuntu-22.04
|
||
|
||
env:
|
||
SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
|
||
SUPABASE_DB_PASSWORD: ${{ secrets.PRODUCTION_DB_PASSWORD }}
|
||
PRODUCTION_PROJECT_ID: abcdefghijklmnopqrst
|
||
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- uses: supabase/setup-cli@v1
|
||
with:
|
||
version: 1.0.0
|
||
|
||
- run: |
|
||
supabase link --project-ref $PRODUCTION_PROJECT_ID
|
||
supabase db push
|
||
```
|
||
|
||
- `.github/workflows/staging.yml`:
|
||
|
||
```yaml
|
||
name: Deploy Migrations to Staging
|
||
|
||
on:
|
||
push:
|
||
branches:
|
||
- develop
|
||
workflow_dispatch:
|
||
|
||
jobs:
|
||
deploy:
|
||
runs-on: ubuntu-22.04
|
||
|
||
env:
|
||
SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
|
||
SUPABASE_DB_PASSWORD: ${{ secrets.STAGING_DB_PASSWORD }}
|
||
STAGING_PROJECT_ID: abcdefghijklmnopqrst
|
||
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- uses: supabase/setup-cli@v1
|
||
with:
|
||
version: 1.0.0
|
||
|
||
- run: |
|
||
supabase link --project-ref $STAGING_PROJECT_ID
|
||
supabase db push
|
||
```
|
||
|
||
Commit these files to Git and push to your `main` branch on GitHub. Make sure you’ve updated these environment variables to match your Supabase projects:
|
||
|
||
- `SUPABASE_ACCESS_TOKEN`
|
||
- `PRODUCTION_PROJECT_ID`
|
||
- `PRODUCTION_DB_PASSWORD`
|
||
- `STAGING_PROJECT_ID`
|
||
- `STAGING_DB_PASSWORD`
|
||
|
||
When configured correctly, your repository should have CI and Release workflows that trigger on new commits pushed to `main` and `develop` branches.
|
||
|
||
|
||
|
||
### Open a PR with new migration
|
||
|
||
Now that your repository is set up, it’s time to create a new migration. Follow the [migration section](#creating-a-new-migration) to create a file `supabase/migrations/<timestamp>_new_employee.sql`.
|
||
|
||
Checkout a new branch `feat/employee` from `develop` , commit the migration file, and push to GitHub.
|
||
|
||
```bash
|
||
git checkout -b feat/employee
|
||
git add supabase/migrations/<timestamp>_new_employee.sql
|
||
git commit -m "Add employee table"
|
||
git push --set-upstream origin feat/employee
|
||
```
|
||
|
||
Then open a PR from `feat/employee` to `develop` branch.
|
||
|
||
|
||
|
||
You can see that this triggers the test job on GitHub Actions. You can add more test steps to the job, such as running integration tests against the local database started by Supabase CLI. Here we assert that the generated types are up-to-date with new schema.
|
||
|
||
|
||
|
||
Once the test error are resolved, merge this PR, and watch the deployment in action 🚀
|
||
|
||
### Release to production
|
||
|
||
After verifying your staging project has successfully migrated, create another PR from `develop` to `main` and merge it to deploy the migration to the production project.
|
||
|
||
|
||
|
||
The `release` job applies all new migration scripts merged in `supabase/migrations` directory to a linked Supabase project. You can control which project the job links to via `PROJECT_ID` environment variable.
|
||
|
||
The full example code for this guide is available on our [demo repository](https://github.com/supabase/supabase-action-example).
|
||
|
||
## Troubleshooting
|
||
|
||
### Sync production project to staging
|
||
|
||
When setting up a new staging project, you might need to sync the initial schema with migrations previously applied to the production project.
|
||
|
||
One way is to leverage the Release workflow:
|
||
|
||
- Create a new branch `develop` and choose `main` as the branch source
|
||
- Push the `develop` branch to GitHub
|
||
|
||
The GitHub Actions runner will deploy your existing migrations to the staging project.
|
||
|
||
Alternatively, you can also apply migrations through your local CLI to a linked remote database.
|
||
|
||
```sql
|
||
supabase db push
|
||
```
|
||
|
||
Once pushed, check that the migration version is up to date for both local and remote databases.
|
||
|
||
```sql
|
||
supabase migration list
|
||
```
|
||
|
||
### Permission denied on db push
|
||
|
||
If you created a table through Supabase dashboard, and your new migration script contains `ALTER TABLE` statements, you might run into permission error when applying them on staging or production databases.
|
||
|
||
```bash
|
||
ERROR: must be owner of table employees (SQLSTATE 42501); while executing migration <timestamp>
|
||
```
|
||
|
||
This is because tables created through Supabase dashboard are owned by `supabase_admin` role while the migration scripts executed through CLI are under `postgres` role.
|
||
|
||
One way to solve this is to grant `postgres` role additional privileges through the SQL Editor available on Supabase dashboard. For example, the following command grants postgres permissions to alter any table in the public schema.
|
||
|
||
```sql
|
||
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO postgres;
|
||
```
|
||
|
||
### Rebasing new migrations
|
||
|
||
Sometimes your teammate may merge a new migration file to git main branch, and now you need to rebase your local schema changes on top.
|
||
|
||
|
||
|
||
We can handle this scenario gracefully by renaming your old migration file with a new timestamp.
|
||
|
||
```bash
|
||
git pull
|
||
supabase migration new dev_A
|
||
# Assume the new file is: supabase/migrations/<t+2>_dev_A.sql
|
||
mv <time>_dev_A.sql <t+2>_dev_A.sql
|
||
supabase db reset
|
||
```
|
||
|
||
In case [`reset`](/reference/cli/usage#supabase-db-reset) fails, you can manually resolve conflicts by editing `<t+2>_dev_A.sql` file.
|
||
|
||
Once validated locally, commit your changes to Git and push to GitHub.
|