NSchema.Cli 3.0.0-alpha.1

NSchema.Cli

A declarative database schema migration tool. You describe the schema you want, and NSchema computes and applies the migration to get there.

Installation

dotnet tool install --global NSchema.Cli

This installs the nschema command.

Quickstart

1. Scaffold a config and a sample schema:

   nschema init
   

   This writes nschema.json and schemas/example.yaml. Edit the sample to describe your desired schema:

   # schemas/example.yaml
   schemas:
     - name: app
       tables:
         - name: widgets
           primaryKey:
             name: widgets_pkey
             columnNames: [id]
           columns:
             - name: id
               type: bigint
               isNullable: false
             - name: name
               type: text
               isNullable: true
   

2. Point at your database (the connection string is a secret, so prefer the environment):

   export NSCHEMA_CONNECTION_STRING="Host=localhost;Database=app;Username=postgres;Password=postgres"
   

3. Preview the migration, then apply it (nschema.json already has the provider and schema directory, so no flags are needed):

   nschema plan
   nschema apply
   

nschema init is the easiest way to get a valid nschema.json — see Configuration for everything it can hold.

Commands

The plan, apply, and refresh commands accept the common options below. Any option can instead be set in nschema.json or via an environment variable (see: Configuration). init is standalone — it only writes files.

nschema init

Scaffold an nschema.json and a sample schema in the current directory, to get a new project going. It connects to nothing.

• --format <yaml|json> — format for the generated config and sample schema. Defaults to yaml.
• --force — overwrite an existing nschema.json.

nschema init

Common options

Available to all commands. These select the database and state store that hold the current schema.

• --provider <postgres> — the database supplying the live schema. Supported: postgres. With no provider, only offline operations (plan/refresh against a state store) are available. (config provider.postgres, env NSCHEMA_PROVIDER)
• --connection-string <value> — connection string for the provider. (config provider.postgres.connectionString, env NSCHEMA_CONNECTION_STRING)
• --state-file <path> — path for a file state store. (config state.file.path, env NSCHEMA_STATE_FILE)
• --state-s3-bucket <bucket> — bucket for an s3 state store. (config state.s3.bucket, env NSCHEMA_STATE_S3_BUCKET)
• --state-s3-key <key> — object key for an s3 state store. (config state.s3.key, env NSCHEMA_STATE_S3_KEY)
• --config <path> — path to the config file. Defaults to ./nschema.json if present.

nschema plan

Compute and show the migration plan, without changing anything.

Needs: a desired schema (--schema-dir) and a current-state source — either a live database (--provider plus a connection string) or, for offline planning, a state store (--state-file).

• --schema-dir <path> (required) — directory containing the desired-schema files. (config schema.dir)
• --format <yaml|json> — the format the desired schema is expressed in. Defaults to yaml. (config schema.format)
• --schema-pattern <pattern> — glob matched within the schema directory. Defaults to **/*.yaml or **/*.json. (config schema.pattern)
• --scope <name> — limit the migration to specific database schemas (namespaces). May be repeated. (config scope)
• --destructive-actions <error|warn|allow> — policy for destructive changes. Defaults to error. (config destructiveActionPolicy, env NSCHEMA_DESTRUCTIVE_ACTION_POLICY)

nschema plan --provider postgres --schema-dir ./schemas

nschema apply

Compute the plan and apply it to the target database. Prompts for confirmation before making changes unless --auto-approve is given.

Needs: the same inputs as plan, against a live database the tool can write to.

Accepts every plan option, plus:

• --auto-approve — skip the confirmation prompt and apply immediately.

nschema apply --provider postgres --schema-dir ./schemas

nschema refresh

Read the live schema and write it to the state store. Use this to seed or repair state.

Needs: a live database (--provider plus a connection string) and a state store to write to (--state-file, or --state-s3-bucket/--state-s3-key). It captures the whole schema and so takes no desired-schema or --scope options.

nschema refresh --provider postgres --state-file ./nschema.state.json

Configuration

Settings come from three sources, in increasing order of precedence:

1. The nschema.json config file (or the file passed to --config).
2. NSCHEMA_* environment variables.
3. Command-line options.

nschema.json

{
  "provider": { "postgres": { "connectionString": "Host=localhost;Database=app;..." } },
  "state":    { "file": { "path": "./nschema.state.json" } },
  "schema":   { "dir": "./schemas", "format": "yaml", "pattern": "**/*.yaml" },
  "scope": ["app"],
  "destructiveActionPolicy": "Error"
}

Connection string

The database connection string is a secret. Prefer supplying it through the environment:

export NSCHEMA_CONNECTION_STRING="..."

It can also be passed with --connection-string or set in nschema.json, but please don't commit secrets to source control.

Desired schema files

A schema file is a document with a schemas array; each schema has tables, and each table has columns (and an optional primaryKey). Column type is a compact string such as bigint, text, varchar(255), or decimal(18,2). The YAML and JSON formats describe the same structure — the YAML quickstart above is equivalent to:

{
  "schemas": [
    {
      "name": "app",
      "tables": [
        {
          "name": "widgets",
          "primaryKey": { "name": "widgets_pkey", "columnNames": ["id"] },
          "columns": [
            { "name": "id", "type": "bigint", "isNullable": false },
            { "name": "name", "type": "text", "isNullable": true }
          ]
        }
      ]
    }
  ]
}

License

See LICENSE.