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/BACKENDblock can name any plugin package with asourceattribute. nschema initnow restores plugins.initnow pre-fetches the provider and backend plugins pinned in your config. Operations restore implicitly on first use;initjust does it up front so the first real command is fast.--no-initflag. Skips the implicit plugin restore and requires the plugins to be cached already.lockcommand group.nschema lock status/lock acquire/lock releaseinspect, manually hold, and release the state lock.lock acquireholds a lock that outlives the command (for out-of-band checks before a migration), with an optional--ttl(e.g.30m) and--reason,lock statussurfaces any information about the currently held lock.lock releaserequires the lock id by default (refusing if it no longer matches the held lock), with--forceto release whatever lock is held without naming it.--no-lockflag onapply,refresh, anddestroy. Runs without taking the state lock.nschema state show <file>renders a state file on disk directly, without a configured backend.nschema db showrenders the live database schema, read directly from the database via the provider — the online counterpart tostate show.plugincommand group.nschema plugin listshows the provider and backend plugins your project pins and whether each is restored; plugin show--formatoption (text|json|markdown), selecting the output format for any command.--jsonis now shorthand for--format json.- Markdown output.
--format markdownrenders 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;
nschemarestores 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
inittonschema scaffold. Creating a starter project is nownschema scaffold(initbecame the restore command above). ItsPROVIDER/BACKENDconfig blocks and the sample schema are rendered by the plugins themselves. PROVIDER/BACKENDblocks now require a pinnedversion(the plugin package version); the built-infilebackend is the exception. A first-party label (postgres,sqlite,sqlserver,s3) still resolves to its package automatically.- A
PROVIDERblock is now required to select a provider.NSCHEMA_POSTGRES_CONNECTION_STRINGand the other connection-string variables no longer name the provider on their own — they still override the connection string set in the block. doctorreports plugin problems as diagnostics. A provider or backend that fails to restore or configure is now reported bydoctoras 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 withapply/destroy) instead of--force. The lock-id safety check is unchanged. showsplit by what it shows. The recorded state is nownschema state show(offline; thestatenoun group will growpull/push/move), and a saved plan isnschema plan show <file>. The top-levelshowcommand is gone.completion install/completion uninstallsubcommands replace the--install-autocomplete/--uninstall-autocompleteflags.nschema completion <shell>still prints the script.- Built on
NSchema.Core 4.0.0and the 4.0 provider/backend packages.
Fixed
- Running
nschema --helpin a busy directory like root would cause a performance slowdown due to the--environmentarg 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
NSCHEMAconfig block.destructive_actionmoved to the--destructive-actionsflag / theNSCHEMA_DESTRUCTIVE_ACTION_POLICYenvironment variable;dialectandtransaction_mode(never wired in) are gone. AnNSCHEMAblock is now rejected as an unknown configuration block. - The top-level
show,lock-status, andforce-unlockcommands, replaced bystate show/plan showand thelockgroup above. Theshow --onlinelive-schema view is nownschema db show(adbnoun group) rather than a mode flag.
3.4.0
Added
doctorcommand. A newnschema doctorcommand runs read-only health checks against your declared infrastructure, including database connectivity, state-store reachability, and the state lock. It exits1when any configured check fails, for gating in CI.force-unlock <lock-id>.force-unlocknow 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. Bareforce-unlockstill releases whatever lock is held. RequiresNSchema.Core 3.4.0andNSchema.Aws 3.2.0.lock-statuscommand. A newnschema lock-statusreports whether the state store is locked. Supports--jsonfor structured output and--detailed-exitcode(exit2when locked) for CI gating.
3.3.0
Added
- Init options. The
initcommand 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 s3block accepts aforce_path_styleattribute 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.0and the latest provider packages.
Fixed
destroynow tears down SQL Server and SQLite projects. Teardown previously failed for these providers because SQL Server’sDROP SCHEMAdoes not cascade, and SQLite cannot drop its implicitmainschema. 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>.sqlfiles.
3.1.0
Added
- SQLite Support. Use:
Connection string may also be supplied separately via thePROVIDER sqlite (connection_string = 'Data Source=app.db')
NSCHEMA_SQLITE_CONNECTION_STRINGenvironment variable. - SQL Server Support. Use:
Credentials and command timeout may also be supplied separately, via thePROVIDER sqlserver (connection_string = 'Server=localhost;Database=app')
username/password/command_timeoutblock attributes or theNSCHEMA_SQLSERVER_CONNECTION_STRING/NSCHEMA_SQLSERVER_USERNAME/NSCHEMA_SQLSERVER_PASSWORDenvironment variables.
3.0.0
Initial release of the NSchema CLI. dotnet tool install -g nschema
See https://nschema.dev for full documentation.