Skip to main content
Use this when a Supabase project needs a migration but Docker or a local stack is not part of the workflow. supaschema diff reads declarative SQL, compares it with the configured source state, and writes a migration that supaschema sync or the Supabase CLI can apply.

​
Use this when

  • CI cannot run Docker reliably.
  • You want schema diffing without a shadow database.
  • The review should include replay-safety checks before any Supabase apply path.
  • You want the option to run the Supabase CLI through a configured supaschema sync target.

​
Do this

Put declarative SQL under the configured Supabase schema path: 
mkdir -p supabase/schemas
Generate and check the migration: 
npx supaschema diff
npx supaschema check
Then apply through the configured sync workflow: 
npx supaschema sync
sync runs the safety gates and then invokes the config-selected direct PostgreSQL or Supabase CLI runner. Target config decides selection: every sync.targets.<name> entry with mode: "auto" joins the bare sync path. Remote targets also require their approval variable before deploy. Use supabase db push directly only when your deployment process intentionally keeps the Supabase CLI as a separate operational step.

​
Verify

Use a disposable PostgreSQL database for apply-twice proof: 
npx supaschema verify --ensure-environment --ensure-roles
In pull requests, fail when the configured sources drift: 
npx supaschema diff --fail-on-diff --quiet

Supabase integration

See the Supabase path and runner model.

Diff command

Review source flags and drift behavior.

Check command

Validate replay safety before applying SQL.

Supabase comparison

Compare this flow with supabase db diff.
Last modified on June 18, 2026