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:
Generate and check the migration:
Then apply through the configured sync workflow:
sync checks pending migrations, refreshes generated contracts, stages the schema closure, runs safety gates, verifies the pending migration set, and then invokes the selected direct PostgreSQL or Supabase CLI runner. Target config may select one sync.targets.<name> entry with mode: "auto" for bare sync; multiple automatic targets are refused before any runner can mutate a database. 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:
In pull requests, fail when the configured sources drift:

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 July 9, 2026