supabase db: Usage, Options & Common CI Errors
supabase db applies, resets, and diffs Postgres migrations for Supabase.
supabase db drives database migrations in Supabase CI pipelines. The friction points are linking to a project, applying migrations in order, and pointing commands at the right database URL.
What it does
The supabase db subcommands manage the Postgres schema behind a Supabase project: pushing local migrations to a remote database, resetting the local database to the migration history, and diffing the schema to generate new migrations.
Common usage
supabase db push --db-url "postgresql://postgres:secret@localhost:5432/postgres"
supabase db reset # rebuild local db from migrations + seed
supabase db diff -f new_migration # generate a migration from changes
supabase db push --linked # push to the linked remote projectOptions
| Item | What it does |
|---|---|
| push | Apply local migrations to the target database |
| reset | Drop and rebuild the local database from migrations |
| diff -f <name> | Generate a migration from schema changes |
| --db-url <uri> | Target a specific database URL |
| --linked | Operate on the linked remote project |
| --password | Database password for the linked project |
Common errors in CI
Cannot find project ref. Have you run supabase link? - --linked commands need a prior supabase link --project-ref <ref> (and an access token via SUPABASE_ACCESS_TOKEN). "failed to connect to postgres" usually means a wrong --db-url or a database that is not up; for local flows the CLI needs Docker running. A migration that errors mid-apply leaves the schema partially applied - keep migrations idempotent and test with db reset first.