homeresume
 
   
🔍

Supabase migrations with GitHub Actions

November 20, 2026

Schema 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 --version locally, 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 init
supabase migration new create_todos
-- supabase/migrations/20261120162000_create_todos.sql
create 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.todos
add column if not exists priority integer not null default 0;

Replay the files against a local database before you push them:

supabase start
supabase 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.

PieceValue
Userpostgres.<project-ref>
PasswordDatabase password, percent-encoded
HostSession pooler host, copied from Connect
Port5432
Databasepostgres
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 project
  • SUPABASE_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.yml
name: Deploy Migrations to Production
on:
push:
branches:
- master
paths:
- 'supabase/migrations/**'
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
env:
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.com
steps:
- uses: actions/checkout@v4
- uses: supabase/setup-cli@v1
with:
version: 2.67.1 # same version as local `supabase --version`
- name: Push migrations
run: |
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.co is IPv6 unless the IPv4 add-on is enabled. Use the session pooler host on port 5432.
  • Transaction pooler - port 6543 is the wrong mode for migrations. Session mode is port 5432, and the user is postgres.<project-ref>.
  • Guessed pooler host - aws-0 and aws-1 are 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 push fails. Prefer a new migration for the intended change. Use supabase db pull or supabase migration repair when 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 CONCURRENTLY out of these files.
  • Missing --yes - the job hangs on the confirmation prompt and then fails.