Supabase migrations with GitHub Actions
November 20, 2026Schema changes for a hosted Supabase project belong in versioned SQL files. The Supabase CLI applies those files in filename order and records each one in supabase_migrations.schema_migrations. A GitHub Action can run supabase db push when migration files land on the production branch, so the hosted database stays aligned with git.
The Supabase basics note applies a first schema from the SQL Editor. This post covers migration files, the session-pooler connection GitHub-hosted runners need, a workflow that pushes on changes under supabase/migrations, and pitfalls. Workflow syntax is the same as in GitHub actions 101.
Prerequisites
- A Supabase project
- The Supabase CLI (
supabase --versionlocally, so you can pin the same version in CI) - A GitHub repository with Actions enabled
Migration files
Initialize the CLI config once, then add a migration. supabase migration new creates an empty SQL file under supabase/migrations with a timestamp prefix:
supabase initsupabase migration new create_todos
-- supabase/migrations/20261120162000_create_todos.sqlcreate table if not exists public.todos (id bigint generated always as identity primary key,title text not null,done boolean not null default false,created_at timestamptz not null default now());
The next change is a new file. Leave a file that production has already applied unchanged:
supabase migration new add_todo_priority
alter table public.todosadd column if not exists priority integer not null default 0;
Replay the files against a local database before you push them:
supabase startsupabase db reset
db reset rebuilds the local database and runs every file in supabase/migrations in order.
Session pooler from GitHub Actions
GitHub-hosted runners are IPv4-only. The direct database host (db.<project-ref>.supabase.co) is IPv6 unless the project has the IPv4 add-on, so a push from Actions often never connects.
Use the session pooler string from Dashboard → Connect → Session pooler. It is IPv4, and port 5432 keeps a real Postgres session, which DDL needs. Port 6543 is transaction mode and is the wrong target for db push.
| Piece | Value |
|---|---|
| User | postgres.<project-ref> |
| Password | Database password, percent-encoded |
| Host | Session pooler host, copied from Connect |
| Port | 5432 |
| Database | postgres |
postgresql://postgres.<project-ref>:<encoded-password>@<pooler-host>:5432/postgres
The pooler host looks like aws-1-eu-west-1.pooler.supabase.com. The aws-N prefix is a cluster index, not something you can derive from the region. Copy it from the Connect dialog.
<project-ref> is the id in the dashboard URL: https://supabase.com/dashboard/project/<project-ref>.
Characters such as @, #, %, and / in the database password break that URI. Percent-encode the whole password before you interpolate it. urllib.parse.quote with safe='' encodes every reserved character, including /.
GitHub Action
Store the values in Settings → Secrets and variables → Actions:
SUPABASE_DB_PASSWORD- database password for the projectSUPABASE_PROJECT_ID- the project ref
The pooler host is not a secret. Put it in the workflow env after you copy it from Connect.
This workflow runs on a push to master that touches supabase/migrations/**, and from the Actions tab via Run workflow (workflow_dispatch). Change master if production follows another branch. --yes skips the CLI confirmation prompt so the job does not wait for input.
# .github/workflows/deploy-migrations.ymlname: Deploy Migrations to Productionon:push:branches:- masterpaths:- 'supabase/migrations/**'workflow_dispatch:jobs:deploy:runs-on: ubuntu-latestenv:SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}# Dashboard → Connect → Session pooler. Do not guess the aws-N prefix.SUPABASE_POOLER_HOST: aws-1-eu-west-1.pooler.supabase.comsteps:- uses: actions/checkout@v4- uses: supabase/setup-cli@v1with:version: 2.67.1 # same version as local `supabase --version`- name: Push migrationsrun: |ENCODED=$(python3 -c "import urllib.parse, os; print(urllib.parse.quote(os.environ['SUPABASE_DB_PASSWORD'], safe=''))")supabase db push --yes --db-url "postgresql://postgres.${SUPABASE_PROJECT_ID}:${ENCODED}@${SUPABASE_POOLER_HOST}:5432/postgres"
actions/checkout is required so the runner has the supabase/migrations directory. supabase/setup-cli installs the CLI. Pin version to the CLI you already use locally, so a later release does not change push behavior on its own.
db push compares those files with supabase_migrations.schema_migrations on the remote database and applies only the pending ones, in filename order. A push that does not change supabase/migrations does not start this workflow. Run workflow on the Actions tab applies whatever is already pending, which is useful after you fix a secret or the pooler host.
db push --db-url authenticates with the database password. supabase link uses SUPABASE_ACCESS_TOKEN and then opens the direct database host, which is the connection GitHub-hosted runners often cannot reach.
Pitfalls
- Direct host from Actions -
db.<project-ref>.supabase.cois IPv6 unless the IPv4 add-on is enabled. Use the session pooler host on port5432. - Transaction pooler - port
6543is the wrong mode for migrations. Session mode is port5432, and the user ispostgres.<project-ref>. - Guessed pooler host -
aws-0andaws-1are both real. Copy the host from Dashboard → Connect → Session pooler. - Raw password in the URI - encode it before building
--db-url. An unencoded@or#makes the CLI parse the wrong host. - Editing an applied file - the remote history is the filename version. Changing SQL that already ran does not run it again, and git and production drift apart. Add a new migration.
- Renaming a file after it was pushed - the history row no longer matches, and the next push treats it as a different migration.
- Dashboard SQL on production - schema and migration history can disagree, and
db pushfails. Prefer a new migration for the intended change. Usesupabase db pullorsupabase migration repairwhen you intentionally adopt SQL that was applied outside the CLI. - Statements that cannot run in a transaction - the CLI runs each migration file in a transaction. Leave
CREATE INDEX CONCURRENTLYout of these files. - Missing
--yes- the job hangs on the confirmation prompt and then fails.