supaschema is distributed as a standard npm package and works with any Node.js project. This page covers installing the package, understanding what the postinstall step does, initialising your configuration, and using the doctor command to verify that your environment is ready.
Requirements
Before installing, confirm your environment meets these minimum requirements:
| Requirement | Minimum Version |
|---|
| Node.js | 22.x or later |
| PostgreSQL (target) | 15 or later |
Install
npm install --save-dev supaschema
What the postinstall step does
After the package installs, a postinstall script runs automatically. It checks whether a supaschema.config.json file already exists in your project root. If it does not, it creates one with sensible defaults:
{
"schemaPaths": ["supabase/schemas"],
"migrationsDir": "supabase/migrations"
}
npx supaschema diff immediately after install without any manual configuration for a standard Supabase project layout.
If you commit supaschema.config.json to version control (recommended), the postinstall script will detect the existing file and skip scaffolding on subsequent npm install runs across your team.
Initialise Configuration
If you need to create or regenerate supaschema.config.json at any time — for example, after deleting it or when setting up a new environment — run:
This is the same scaffolding that postinstall performs, but invoked explicitly. It writes supaschema.config.json to your current working directory with the default configuration values.
Diagnose Your Environment with doctor
The doctor command runs a series of environment checks and reports any issues that would prevent supaschema from working correctly. Run it after installation to confirm everything is set up properly:
Example output from a healthy environment:
PASS node version: running 22.4.0, requires >=22
PASS sql parser: libpg-query WASM parser loaded
PASS config: supaschema.config.json
PASS database url: resolved via SUPASCHEMA_DATABASE_URL
PASS database reachable: SELECT 1 succeeded
PASS createdb capability: role can CREATE DATABASE (verify/corpus will work)
PASS migrations history: 12 applied, 0 pending, 0 ghosts, 0 out-of-order
PASS declarative tree: supabase/schemas exists
doctor: healthy
doctor checks the following:
| Check | What It Verifies |
|---|
| node version | Your Node.js runtime meets the >=22 requirement |
| sql parser | The bundled WASM parser (libpg-query) loads without error |
| config | supaschema.config.json is found and valid |
| database url | A database URL resolves (via --database-url, SUPASCHEMA_DATABASE_URL, or supabase/config.toml) |
| database reachable | The resolved database can be reached (skipped if no URL resolves) |
| createdb capability | The database role has CREATEDB (required for verify and corpus) |
| migrations history | Applied, pending, ghost, and out-of-order migration counts from the configured migrationsDir |
| declarative tree | The configured schemaPaths directory exists and contains .sql files |
Run npx supaschema doctor in CI as a preflight step before running diff or check. Any failed check will be surfaced clearly before it causes a more cryptic failure downstream.
Exit Codes
supaschema uses structured exit codes so you can integrate it reliably into scripts and CI pipelines:
| Exit Code | Meaning |
|---|
0 | Success — the command completed without errors |
1 | Runtime error — an unexpected error occurred during execution |
2 | Diagnostics error — one or more doctor checks failed |
3 | Diff found operations — returned by diff when --fail-on-diff is set and the diff is non-empty |
Exit code 3 is only returned when you pass the --fail-on-diff flag to diff. This is useful in CI to assert that your schema files and migrations directory are already in sync (i.e. no uncommitted schema changes exist).
Shell Completions
supaschema can generate shell completion scripts for bash, zsh, and fish. Add completions to your shell so you can tab-complete commands and flags.
npx supaschema completion bash
npx supaschema completion bash >> ~/.bashrc
source ~/.bashrc
npx supaschema completion zsh >> ~/.zshrc
source ~/.zshrc
Shell completion scripts are generated dynamically from the supaschema command tree, so they stay up to date automatically as you upgrade the package.