Quickstart

Use this page to generate, check, type, stage, and apply or dry-run one migration. The examples use the neutral paths database/schemas and database/migrations. If install selected provider-specific paths, use the values in supaschema.config.json. The commands below use npm’s local runner. Use the matching pnpm, Yarn, or Bun runner from Installation when that manager owns the project.

Install

Install supaschema in the package or workspace that owns your schema files, then initialize the local project before editing the schema:

npm install supaschema
npm exec -- supaschema init
npm exec -- supaschema --version
npm exec -- supaschema config validate

Write schema

Create one schema file:

mkdir -p database/schemas

database/schemas/app.sql

CREATE SCHEMA app;

CREATE TABLE app.accounts (
  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  name text NOT NULL
);

ALTER TABLE app.accounts ENABLE ROW LEVEL SECURITY;

CREATE POLICY accounts_select ON app.accounts
  FOR SELECT
  TO public
  USING (true);

Your schema files are the source of truth. supaschema writes the migration.

Sync

Run the full workflow:

npm exec -- supaschema sync

You will see output like this:

diff: wrote database/migrations/20240101120000_migration.sql
checked: 20240101120000_migration.sql (replay-safe)
types: wrote database.types.ts
types: wrote database.zod.ts
stage: staged database/migrations/20240101120000_migration.sql
dry run: no sync target was selected by config

Review the generated file. It should include a lineage marker and guarded SQL:

database/migrations/20240101120000_migration.sql

-- Generated by supaschema x.y.z.
-- supaschema: lineage from=0000000000000000... to=4db806bc9b786ea2...

CREATE SCHEMA IF NOT EXISTS app;
CREATE TABLE IF NOT EXISTS app.accounts (...);

Focused lanes

Run a focused lane only when you need to operate one step directly:

npm exec -- supaschema diff
npm exec -- supaschema check
npm exec -- supaschema types
npm exec -- supaschema stage
npm exec -- supaschema apply

If check reports issues, review the flagged statements before applying the migration. A database URL alone does not enable apply: sync stays a dry run until config selects exactly one apply target, the migration policy permits apply, verification passes, and any remote approval is present. supaschema fails closed when it cannot prove safety.

Setup

Confirm install-time paths and setup output.

Commands

Deep-dive into diff, check, verify, and other commands.

Types

Configure and consume generated TypeScript and Zod outputs.

ORM-free apps

Use generated database contracts without adding an ORM schema layer.

Start

Core workflow

Configure

Tasks

Agents and CI

Evidence

Reference

Setup

Commands

Types

ORM-free apps

​Related

Setup

Commands

Types

ORM-free apps

Related