Skip to content
NSchema

Quickstart Guide

This guide will walk you through setting up NSchema in an empty directory and applying a basic Schema to a live PostgreSQL database. It assumes you’ve installed nschema and have a connection string to a database available.

  1. Scaffold the project.

    Terminal window
    nschema scaffold

    This writes three files:

    • config.sql. The default PROVIDER / BACKEND configuration (which database to connect to, and where state lives).
    • config.env.prod.sql. The PROVIDER / BACKEND configuration to use when running with --environment production.
    • schemas/example.sql — a sample desired-schema file.

    Edit the sample to describe the schema you want, using 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.

    -- NSchema project configuration. These blocks tell NSchema which database to
    -- connect to and where to keep state. Config blocks may live in any .sql file.
    

    PROVIDER postgres (
      version = '4.0.0',
      -- Prefer the NSCHEMA_POSTGRES_CONNECTION_STRING environment variable, which
      -- overrides the value below.
      connection_string = ''
      -- Credentials may be supplied separately from the connection string (e.g. from
      -- a secret store) via NSCHEMA_POSTGRES_USERNAME / NSCHEMA_POSTGRES_PASSWORD.
      -- They override any user/password embedded in connection_string.
    );
    

    BACKEND file (
      path = './nschema.state.json'
    );

    The configuration in your config.sql files is the default, so you could enter connection_string directly, but connection strings need to remain secret, so the safer approach is to set the connection string by environment variable instead:

    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

    validate checks for syntax errors, and also any structural errors like invalid foreign keys or tables without columns.

  4. Preview the migration.

    Terminal window
    nschema plan

    plan computes the changes and prints them. If you have a backend configured, the comparison will be done against the last state snapshot 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 and apply the changes.

Congrats! You just deployed your first database using NSchema.

What next?

Section titled “What next?”