supabase "db push" failed in CI

supabase db push applies your local migration files to the linked remote database. It fails when a statement errors, the connection is refused, or the remote migration history does not line up with the local files.

What this error means

A "supabase db push" step fails with a SQL error from a specific migration file, a connection error, or "Remote migration versions not found in local migrations directory".

Applying migration 20260615120000_add_orders.sql...
ERROR: column "user_id" referenced in foreign key constraint does not exist (SQLSTATE 42703)
At statement 3: ALTER TABLE public.orders ADD CONSTRAINT ...

Common causes

A migration statement errors on the remote schema

The SQL depends on objects or ordering that do not hold on the remote database, so a statement fails and push aborts.

The remote and local migration histories diverge

A migration applied out of band on the remote, or a local file was renamed, so push cannot reconcile the histories.

How to fix it

Read the failing statement and fix the migration

1. Note the migration file and statement number in the error.
2. Correct the SQL (ordering, missing column, or dependency).
3. Re-run db push against the linked project.

supabase db push --debug

Reconcile drifted history

If versions differ, repair the migration history so local and remote agree before pushing.

supabase migration repair --status applied <version>

How to prevent it

• Test migrations against a fresh local db before pushing in CI.
• Keep migration files append-only; do not rename applied ones.
• Apply schema changes only through migrations, never out of band.

Related guides