Skip to main content
supaschema is a CLI tool and Node.js library that generates type-safe, idempotent PostgreSQL migrations directly from declarative SQL schema files. You describe what your database schema should look like, and supaschema figures out exactly which SQL statements are needed to get there — without ever connecting to a running database, spinning up Docker, or relying on an ORM.

​
What Problem Does It Solve?

Traditional schema migration workflows require a live or shadow database to diff your desired state against your current state. This creates friction: you need Docker running locally, a shadow database provisioned in CI, or a full Supabase stack just to generate a migration file. If the diff engine is slow or inaccurate, you lose trust in the output and end up editing generated SQL by hand. supaschema takes a different approach. It parses your declarative schema files using PostgreSQL’s own WASM parser — the same parser the database uses — so the analysis is both fast and structurally correct. The result is a migration you can apply with confidence.

​
Key Differentiators

  • No infrastructure required. supaschema never touches a real database during migration generation. No Docker, no shadow DB, no network calls.
  • Built on PostgreSQL’s own parser. supaschema uses the official PostgreSQL parser compiled to WebAssembly, so it understands your SQL the same way the database does.
  • 20–70× faster than alternative engines. supaschema’s diff engine consistently outperforms competing tools in benchmarks across schema sizes.
  • Perfect F1 accuracy (1.000). Independent accuracy benchmarks show supaschema produces zero false positives and zero false negatives in migration output.
  • Replay-safe migrations. Every generated migration is idempotent and safe to re-run, so you can integrate it into CI/CD pipelines without fear of destructive side effects.

​
Benchmark

The table below shows median diff time across schema sizes and F1 accuracy scores from head-to-head benchmarks against the Supabase CLI’s diff engines. All numbers are reproducible from the project repository.
Tool1 table1,000 tables2,500 tablesF1 Accuracy
supaschema0.19 s1.38 s3.23 s1.000
Supabase CLI engines3.6–4.6 s~39 s~3.5 min0.982–0.999
Benchmark figures come from a reference run on Apple Silicon, Node 24, PostgreSQL 17.6, and Supabase CLI 2.106.0. The 20–70× speedup range reflects the spread from small to large schemas — the gap widens as your schema grows because shadow-database engines pay for a full schema replay into a fresh Docker database on every diff. The Supabase CLI accuracy gap is always the same miss: each engine silently drops an RLS policy change.

​
Two Ways to Use supaschema

​
CLI

The supaschema binary is the primary interface for most projects. You run it from your project root, and it reads your configuration from supaschema.config.json. 
# Generate a migration from your declarative schema files
npx supaschema diff

# Validate a migration file before applying it
npx supaschema check supabase/migrations/20240101000000_migration.sql

# Diagnose your environment
npx supaschema doctor
The CLI is designed to slot into existing Supabase projects without changing your deploy workflow — you still apply migrations with supabase db push.

​
Node.js Library API

supaschema also exposes a programmatic API for use inside build scripts, test harnesses, or custom tooling. Install the package and import the functions you need directly in your Node.js code. 
import { diff, check } from "supaschema";

const result = await diff({ from: "supabase/migrations", to: "supabase/schemas" });
console.log(result.sql);

​
Available Commands

CommandDescription
diffGenerate a migration by diffing schema files against the migrations history
checkValidate a migration file for correctness and safety
verifyVerify that applied migrations match your declarative schema
typesGenerate TypeScript types from your schema
planPreview the operations a migration will perform
inspectInspect the current schema tree
fingerprintCompute a deterministic fingerprint of a schema
migrationsList and manage migration history
syncSync migrations directory with schema state
auditAudit migration files for common issues
doctorDiagnose your environment and configuration
initScaffold a supaschema.config.json in your project
completionPrint shell completion scripts (bash, zsh, fish)
explainExplain what a migration file does in plain language
corpusManage the internal test corpus
selfcheckRun supaschema’s internal integrity checks

​
Licensing

supaschema is dual-licensed:
  • AGPL-3.0 for open-source projects. You can use supaschema freely as long as your project is also open source under a compatible license.
  • Commercial license for proprietary use. If you are building closed-source software, contact the supaschema team for a commercial license.

Quickstart

Install supaschema and generate your first migration in under 5 minutes.

Commands: diff, check, verify

Learn the core commands you’ll use every day with supaschema.

Type Generation

Generate TypeScript types directly from your declarative schema files.