This FAQ gives short, citation-friendly answers about supaschema: what it is, how it differs from database-backed diff tools, what it generates, and how it fits into PostgreSQL migration workflows across providers.
What is supaschema?
supaschema is a CLI and Node.js library that generates deterministic PostgreSQL migrations from declarative SQL schema files. You edit the desired schema tree, run supaschema diff, and get a timestamped migration plus refreshed TypeScript and Zod output.
Does supaschema work outside Supabase?
Yes. supaschema works with PostgreSQL 15+ targets, including plain PostgreSQL, Neon, RDS/Aurora, Cloud SQL, AlloyDB, Azure PostgreSQL, and Supabase. supaschema sync can apply generated migration files through configured direct PostgreSQL or Supabase CLI targets; teams with a separate deployment owner can still apply the generated SQL through that runner.
Is supaschema affiliated with Supabase?
No. supaschema is an independent open-source project for PostgreSQL projects on any provider. Supabase is supported, including supabase db push, but it is not required.
Does supaschema apply migrations to my database?
Yes, through supaschema sync when you select an apply target explicitly or configure approved automatic targets. sync still runs the generation, generated-output refresh, replay-safety, type-safety, RLS-safety, and target-reconciliation gates before it mutates a database. Remote automatic targets require an approval environment variable such as SUPASCHEMA_REMOTE_SYNC_APPROVED=1.
Does supaschema need Docker or a shadow database?
No for migration generation and type generation. supaschema diff parses schema files with PostgreSQL’s parser compiled to WebAssembly, so it does not need to spin up Docker, replay the schema into a shadow database, or introspect a database before producing SQL.
How is supaschema different from supabase db diff?
supabase db diff compares database states through engines that rely on a database-backed workflow. supaschema compares SQL definitions structurally from parse trees, so it can generate migrations from files and git refs without a shadow database. It also guards generated statements so retries do not fail on already-created objects.
For a deeper comparison, see supaschema vs Supabase CLI.
Can supaschema generate TypeScript types without a database?
Yes. supaschema types emits database.types.ts plus database.zod.ts directly from the declarative schema tree. You can use those generated types and validators in any TypeScript app; it does not need a live database or a previously applied migration.
Do I still need an ORM?
No for schema ownership, migration generation, generated TypeScript types, runtime validators, guarded apply, type-safety checks, or RLS-safety checks. Use the generated database.types.ts and database.zod.ts contracts with your PostgreSQL driver or platform client. Add an ORM or query builder only when you specifically want its query-construction API.
See ORM-free applications for the directive.
What makes a migration replay-safe?
A replay-safe migration can be run more than once without failing on objects it already created. supaschema emits guarded SQL such as CREATE TABLE IF NOT EXISTS, DROP ... IF EXISTS, and catalog-checked DO blocks around operations that PostgreSQL does not expose as simple idempotent statements.
How does supaschema handle destructive changes?
Destructive changes fail closed. Drops, unsafe type changes, and PostgreSQL-incompatible replacements stay blocked until the exact object key is reviewed and added to hints.destructive. The committed config should never use a wildcard destructive hint.
Does supaschema understand Row Level Security policies?
Yes. RLS policies are modeled as schema objects, including their USING and WITH CHECK expressions. A changed policy predicate is surfaced as a reviewable migration operation instead of being treated as unchanged because the policy name stayed the same.
What should CI run?
Most projects should run:
npx supaschema diff --fail-on-diff --quiet
npx supaschema check
Which PostgreSQL objects are supported?
supaschema models schemas, extensions, enum/domain/composite types, tables, constraints, indexes, sequences, functions, procedures, views, materialized views, triggers, RLS, policies, grants, default privileges, comments, and foreign data wrappers. Unsupported DDL and provider-owned surfaces such as publications/subscriptions, partitioning, event triggers, collations, and Supabase-managed storage/auth/realtime internals fail with a diagnostic instead of passing through silently. See the support matrix.
What happens when supaschema blocks a diff?
Every blocking diagnostic has a SUPA_* code. Run:
npx supaschema explain SUPA_CODE
What license does supaschema use?
supaschema is dual-licensed: AGPL-3.0 for open-source projects and a commercial license for proprietary use.
How do I get commercial support or a commercial license?
Use the commercial support page and issue template for licensing or support intake. Public bug reports and feature requests still belong in GitHub issues. Do not include secrets, database URLs, customer data, private schema dumps, contracts, pricing details, or confidential roadmap material in a public issue. Last modified on June 18, 2026
