Skip to content
NSchema

Quickstart

import { Steps } from “@astrojs/starlight/components”;

This walks you from an empty directory to a schema applied to a live PostgreSQL database. It assumes you’ve installed the nschema tool and have a database you can connect to.

  1. Scaffold a project.

    Terminal window
    nschema init

    This writes two files:

    • config.sql — the project’s PROVIDER / BACKEND configuration blocks (which database to connect to, and where state lives).
    • schemas/example.sql — a sample desired-schema file.

    Edit the sample to describe the schema you want, written in NSchema DDL:

    -- schemas/example.sql
    CREATE SCHEMA app;
    

    CREATE TABLE app.widgets (
      id   bigint NOT NULL,
      name text,
      CONSTRAINT widgets_pkey PRIMARY KEY (id)
    );

  2. Point at your database.

    The connection string is a secret, so supply it through the environment rather than committing it:

    Terminal window
    export NSCHEMA_POSTGRES_CONNECTION_STRING="Host=localhost;Database=app;Username=postgres;Password=postgres"

    See Configuration blocks for setting the provider and backend, and Environment variables for the full list of overrides.

  3. Check the schema files are well-formed (optional, but a fast pre-flight):

    Terminal window
    nschema validate

  4. Preview the migration.

    Terminal window
    nschema plan

    This computes the changes and prints them, without touching the database.

  5. Apply it.

    Terminal window
    nschema apply

    apply shows the same plan, then prompts for confirmation before making any changes. Answer yes to proceed.

That’s the core loop: edit the .sql files → plan → apply. Everything else builds on it.

What next?

Section titled “What next?”