supaschema init. The workflow keeps declarative schema changes repeatable across plain PostgreSQL, Neon, RDS/Aurora, Cloud SQL, AlloyDB, Azure PostgreSQL, and Supabase.
Core workflow
Migration generation
supaschema diff extracts, plans, renders, and writes the migration.Replay-safety checker
supaschema check validates generated migrations before they reach a
database.Apply-twice verification
supaschema verify proves the newest pending migration is replay-safe
against a disposable database.Guarded apply
supaschema apply reconciles target history and applies pending migrations
after replay, type, and RLS gates pass.Generated outputs
TypeScript types
Types are generated from the declarative schema tree, not a live database
snapshot.
Zod validators
Runtime validators turn generated database types into an application
boundary without an ORM schema layer.
Actionable diagnostics
SUPA_* diagnostics explain blocked or ambiguous schema changes and point
to recovery steps.Destructive hints
Drops and incompatible changes require explicit object-level intent before
SQL is generated.
Project surfaces
Coding-agent bundle
Public-safe prompt, rule, skill, settings, and hooks installed by default
for AI-agent enforcement in the consuming repo.
GitHub Actions
A ready CI lane for drift, safety, package, docs, corpus, and benchmark
checks.
CI drift gate
Fails pull requests when the declarative tree and generated migrations are
out of sync.
Schema safety scan
Scores RLS, grant, hygiene, and generated-contract usage findings without
connecting to a database.
Type-contract gate
Reports breaking generated TypeScript/Zod contract changes and can enforce
them as a failing command.
Schema contracts
Exports and diffs JSON contracts locally for cross-repository drift checks.
Corpus oracle
Exercises real-world catalogs to prove reconvergence outside toy fixtures.
Provider-aware setup
Detects common PostgreSQL provider layouts while keeping
adapter: "auto"
provider-neutral.Evidence
Benchmarks
Large-schema benchmark results for diff performance, correctness, and
workflow cost.
Case study
A production Supabase project used to validate the migration workflow at
real project scale.
Support matrix
Supported PostgreSQL object classes, failure modes, and current boundaries.
Package boundary
The exact public npm package contract and why internal maintainer tooling
stays out.