Skip to content

CLI

4.0.0

Version 4.0.0 changes the provider and backend model to function as plugins resolved through the NuGet package manager.

Added

  • Third-party providers and backends. A PROVIDER / BACKEND block can name any plugin package with a source attribute.
  • nschema init now restores plugins. init now pre-fetches the provider and backend plugins pinned in your config. Operations restore implicitly on first use; init just does it up front so the first real command is fast.
  • --no-init flag. Skips the implicit plugin restore and requires the plugins to be cached already.
  • lock command group. nschema lock status / lock acquire / lock release inspect, manually hold, and release the state lock. lock acquire holds a lock that outlives the command (for out-of-band checks before a migration), with an optional --ttl (e.g. 30m) and --reason, lock status surfaces any information about the currently held lock. lock release requires the lock id by default (refusing if it no longer matches the held lock), with --force to release whatever lock is held without naming it.
  • --no-lock flag on apply, refresh, and destroy. Runs without taking the state lock.
  • nschema state show <file> renders a state file on disk directly, without a configured backend.
  • nschema db show renders the live database schema, read directly from the database via the provider — the online counterpart to state show.
  • plugin command group. nschema plugin list shows the provider and backend plugins your project pins and whether each is restored; plugin show
  • --format option (text | json | markdown), selecting the output format for any command. --json is now shorthand for --format json.
  • Markdown output. --format markdown renders the plan, SQL, and schema as Markdown for a PR comment or a CI job summary.

Changed

  • Providers and backends are now plugins. They ship as separate NuGet packages instead of being bundled with the tool; nschema restores the one pinned in your config on first use (it shells out to the .NET SDK to do so). The local-file state backend remains built in.
  • Scaffolding moved from init to nschema scaffold. Creating a starter project is now nschema scaffold (init became the restore command above). Its PROVIDER / BACKEND config blocks and the sample schema are rendered by the plugins themselves.
  • PROVIDER / BACKEND blocks now require a pinned version (the plugin package version); the built-in file backend is the exception. A first-party label (postgres, sqlite, sqlserver, s3) still resolves to its package automatically.
  • A PROVIDER block is now required to select a provider. NSCHEMA_POSTGRES_CONNECTION_STRING and the other connection-string variables no longer name the provider on their own — they still override the connection string set in the block.
  • doctor reports plugin problems as diagnostics. A provider or backend that fails to restore or configure is now reported by doctor as a health-check finding (every such problem at once) instead of aborting on the first.
  • Lock commands grouped under lock. lock-status → nschema lock status; force-unlock → nschema lock release, whose prompt is now skipped with --auto-approve/-y (consistent with apply/destroy) instead of --force. The lock-id safety check is unchanged.
  • show split by what it shows. The recorded state is now nschema state show (offline; the state noun group will grow pull/push/move), and a saved plan is nschema plan show <file>. The top-level show command is gone.
  • completion install / completion uninstall subcommands replace the --install-autocomplete / --uninstall-autocomplete flags. nschema completion <shell> still prints the script.
  • Built on NSchema.Core 4.0.0 and the 4.0 provider/backend packages.

Fixed

  • Running nschema --help in a busy directory like root would cause a performance slowdown due to the --environment arg autocomplete recursively scanning all the files in the directory. This has been fixed by removing autocomplete.
  • Torn reads of the local state file. The built-in file state store now writes to a temporary sibling file and atomically renames it into place, so a command reading the recorded state while another run writes it.

Removed

  • The NSCHEMA config block. destructive_action moved to the --destructive-actions flag / the NSCHEMA_DESTRUCTIVE_ACTION_POLICY environment variable; dialect and transaction_mode (never wired in) are gone. An NSCHEMA block is now rejected as an unknown configuration block.
  • The top-level show, lock-status, and force-unlock commands, replaced by state show / plan show and the lock group above. The show --online live-schema view is now nschema db show (a db noun group) rather than a mode flag.

3.4.0

Added

  • doctor command. A new nschema doctor command runs read-only health checks against your declared infrastructure, including database connectivity, state-store reachability, and the state lock. It exits 1 when any configured check fails, for gating in CI.
  • force-unlock <lock-id>. force-unlock now accepts the lock id (shown in the blocked operation’s error) and refuses if it no longer matches the held lock — a safety guard against breaking a lock that changed under you. Bare force-unlock still releases whatever lock is held. Requires NSchema.Core 3.4.0 and NSchema.Aws 3.2.0.
  • lock-status command. A new nschema lock-status reports whether the state store is locked. Supports --json for structured output and --detailed-exitcode (exit 2 when locked) for CI gating.

3.3.0

Added

  • Init options. The init command now accepts --provider (postgres, sqlite, sqlserver) and --backend (file, s3) options to scaffold configuration for a specific provider/backend combination.
  • S3-compatible state stores. The BACKEND s3 block accepts a force_path_style attribute for S3-compatible stores (such as MinIO) that require path-style addressing. The endpoint, region, and credentials continue to come from the ambient AWS configuration (AWS_ENDPOINT_URL_S3, AWS_REGION, and the credential chain).
  • Updated to NSchema.Core 3.3.0 and the latest provider packages.

Fixed

  • destroy now tears down SQL Server and SQLite projects. Teardown previously failed for these providers because SQL Server’s DROP SCHEMA does not cascade, and SQLite cannot drop its implicit main schema. The migration engine now drops a schema’s contained objects before the schema itself.
  • DDL formatting (fmt). Fixed two formatting bugs: comments following the last attribute in a block were flattened onto a single line, and a blank line between a leading comment and its statement was removed.

3.2.0

Added

  • Short option aliases. Common flags now have single-character forms: -C (--directory), -e (--environment), -v (--verbose), -q (--quiet), -s (--scope), -y (--auto-approve), -f (--force), -o (--out / --out-dir), and -p (--plan-file).
  • Tab-completion for environment names. --environment <TAB> now completes the environment names discovered from the project’s *.env.<name>.sql files.

3.1.0

Added

  • SQLite Support. Use:
    PROVIDER sqlite (
    connection_string = 'Data Source=app.db'
    )
    Connection string may also be supplied separately via the NSCHEMA_SQLITE_CONNECTION_STRING environment variable.
  • SQL Server Support. Use:
    PROVIDER sqlserver (
    connection_string = 'Server=localhost;Database=app'
    )
    Credentials and command timeout may also be supplied separately, via the username / password /command_timeout block attributes or the NSCHEMA_SQLSERVER_CONNECTION_STRING / NSCHEMA_SQLSERVER_USERNAME / NSCHEMA_SQLSERVER_PASSWORD environment variables.

3.0.0

Initial release of the NSchema CLI. dotnet tool install -g nschema

See https://nschema.dev for full documentation.