> ## Documentation Index
> Fetch the complete documentation index at: https://supaschema.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install supaschema, write a declarative schema file, and run the full sync workflow.

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](/docs/installation) when that manager owns the project.

<Steps>
  <Step title="Install">
    Install supaschema in the package or workspace that owns your schema files,
    then initialize the local project before editing the schema:

    ```bash theme={null}
    npm install supaschema
    npm exec -- supaschema init
    npm exec -- supaschema --version
    npm exec -- supaschema config validate
    ```
  </Step>

  <Step title="Write schema">
    Create one schema file:

    ```bash theme={null}
    mkdir -p database/schemas
    ```

    ```sql database/schemas/app.sql theme={null}
    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.
  </Step>

  <Step title="Sync">
    Run the full workflow:

    ```bash theme={null}
    npm exec -- supaschema sync
    ```

    You will see output like this:

    ```text theme={null}
    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:

    ```sql database/migrations/20240101120000_migration.sql theme={null}
    -- 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 (...);
    ```
  </Step>

  <Step title="Focused lanes">
    Run a focused lane only when you need to operate one step directly:

    ```bash theme={null}
    npm exec -- supaschema diff
    npm exec -- supaschema check
    npm exec -- supaschema types
    npm exec -- supaschema stage
    npm exec -- supaschema apply
    ```

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

## Related

<CardGroup cols={2}>
  <Card title="Setup" icon="wrench" href="/docs/setup">
    Confirm install-time paths and setup output.
  </Card>

  <Card title="Commands" icon="terminal" href="/docs/commands">
    Deep-dive into `diff`, `check`, `verify`, and other commands.
  </Card>

  <Card title="Types" icon="code" href="/docs/commands/types">
    Configure and consume generated TypeScript and Zod outputs.
  </Card>

  <Card title="ORM-free apps" icon="database" href="/docs/concepts/orm-free-applications">
    Use generated database contracts without adding an ORM schema layer.
  </Card>
</CardGroup>