supaschema is best when you want deterministic PostgreSQL or Supabase migrations from declarative SQL files without Docker, a shadow database, or a hand-edited generated migration. The Supabase CLI remains a supported runner for Supabase projects; supaschema sync can also own the guarded apply pipeline through configured direct PostgreSQL or Supabase CLI targets.
Short answer
Usesupaschema when the schema files are the source of truth and you need a fast, replay-safe migration from those files. Use supaschema sync when you want one configured workflow for diff, generated outputs, deploy safety gates, target reconciliation, and apply. Keep supabase db push when you want the Supabase CLI to remain the standalone apply step.
Comparison
| Capability | supaschema | Supabase CLI db diff |
|---|---|---|
| Migration generation source | Declarative SQL files, git refs, dumps, catalogs, or read-only database catalogs | Database-backed diff workflow |
| Docker or shadow database for generation | Not required | Commonly required by database-backed engines |
| Type generation before apply | Yes, from schema files with supaschema types | Usually generated from an already-applied database state |
| Replay safety | Generated SQL is guarded and checked | Generated SQL may need manual review for retry safety |
| RLS policy body changes | Policy expressions are compared structurally | Engines can miss policy-body changes when names stay stable |
| Destructive change handling | Fails closed until exact hints are approved | Depends on generated output and reviewer discipline |
| Applies to production | Yes, through configured sync targets and runner approval gates | Yes, via Supabase migration commands |
Why the workflow is different
supaschema parses SQL with PostgreSQL’s parser compiled to WebAssembly. It compares the resulting parse trees and renders a guarded migration from the structural difference. That means it can compare a declared target schema against a git ref, a directory, a dump, a catalog snapshot, or a read-only live catalog without creating a temporary database.
The practical loop is:
diff writes the migration and refreshes generated outputs according to workflow.type_generation and workflow.zod_generation. check catches replay-safety and lock hazards. verify applies the migration twice in disposable databases and confirms the result matches the declared target. sync can run the same chain and apply pending migrations through a configured direct PostgreSQL or Supabase CLI runner. supabase db push remains valid when the Supabase CLI is intentionally kept as the external apply step.
RLS policy safety
Row Level Security policies are tenant boundaries in many Supabase applications. If a policy changes from a broad predicate to a tenant-scoped predicate, the migration generator must see the body change, not just the policy name.supaschema models policy expressions and surfaces predicate changes as first-class operations. That makes RLS policy changes visible in review and CI.
Benchmark results
The repository benchmark harness comparessupaschema with Supabase CLI diff engines on identical fixtures. On the 1,000-table fixture, supaschema generates the migration and type outputs in one command, while database-backed workflows need multiple steps and a database that has already caught up.
See benchmarks for latency, accuracy, and replay-safety charts, and see the anilize case study for a production Supabase schema with thousands of objects.
Last verified 2026-06-18 against the Supabase CLI documentation. Supabase CLI
behavior is set by Supabase and can change; confirm current command semantics
before relying on them.
When to use each tool
Choosesupaschema for:
- Declarative schema repositories where SQL files are the source of truth.
- CI gates that need to detect drift and prove replay safety.
- Supabase projects where Docker or shadow database startup is slow or unavailable.
- Teams that want TypeScript and Zod output before applying a migration.
- Projects where RLS policy changes need explicit review.
- Applying the final migration outside the
supaschema syncorchestration. - Managing Supabase platform resources outside the schema migration file.
- Existing deployment workflows that already call
supabase db push.
Minimal migration pipeline
supaschema verify before merge when CI can reach a disposable PostgreSQL database.