CLI
5.1.0
Changed
- Implicit schemas are now ignored. Schemas owned by the database (
dbo,public,main, etc.) will now be ignored during import and planning.
Fixed
- Plugin dependencies are not shared correctly. All plugin dependencies will now be correctly loaded from their own dependency closure where the CLI does not have its own version of an assembly.
5.0.1
Fixed
--destructive-actionsargument is ignored. Policy enforcement overrides like--destructive-actionsand--data-hazardsweren’t being respected due to a bug in Core. This is fixed after updating to 5.0.1.
5.0.0
v5.0 moves the CLI onto NSchema.Core 5.0, whose rearchitecture reshapes configuration, plugins, and planning. Changes below are relative to 4.5.1.
Added
--scopetakes an object, not just a schema. A value is an address —--scope appfor a whole schema,--scope app.ordersfor one object. Read under the NSQL identifier rules, so a quoted segment can carry dots and spaces (--scope '"my.schema"."Order Details"').--ephemeralonplan,apply, anddestroyruns against an in-memory state store discarded when the command exits, standing in for a configuredSTATEstore — for CI pipelines that bootstrap disposable databases. Run-once script history does not persist across runs in this mode.- A lockfile (
nschema.lock) pins declared plugin versions to concrete versions.initresolves eachPLUGIN— a range to the highest available version, an exact pin to itself — and records it; later commands read the pin, so a plugin without a lockfile entry is an error that points toinit. plugin update [<label>]re-resolves ranges to their highest available version and rewrites the lockfile — every plugin, or a single one by label.plugin outdatedshows each plugin’s pinned version against the newest its range allows (whatupdatewould install) and the newest available for this engine.newasks the plugins what it needs to know. A database or state plugin can declare the questions its configuration needs, composing the answers into the statement it writes.--set <key>=<value>onnewanswers a question up front, so a scripted run never blocks. Repeatable.
Changed
- Environments select configuration, not schema.
--environmentlayers the environment’s files over the base configuration; schema files are no longer overlaid per environment. An overlay merges theDATABASE,STATE, orENGINEstatement attributes. DATABASEandSTATEreplacePROVIDERandBACKEND. Each names the thing it configures. The built-in local-file store isSTATE file ( path = '…' );.PLUGINdeclares plugin dependencies.PLUGIN <label> ( source = '…', version = '…' );names the package and pins its version;DATABASE/STATEreference the label. The built-in label-to-package map is gone — every plugin is declared explicitly, andversion/sourceno longer ride the configuring statement. Aversionmay be an exact pin or a NuGet-style range ([5.0,6.0)).ENGINE ( version = '…' );asserts the engine version. A project can require an engine version range; a mismatch fails with a pointer todotnet tool update.newauthors theENGINEassertion. A scaffolded project pins the engine to the CLI’s current major (e.g.ENGINE ( version = '[5.0,6.0)' );), so it fails fast on an incompatible tool.newrunsinitafterwards, resolving and locking the plugins it declared so the project is ready toplanimmediately. Pass--no-initto skip it for an offline or edit-first workflow.- Planning always diffs recorded state against the project, so
plan(and a freshapply) now require both a database and a state store. Planning against the live database is no longer available; userefreshto capture the live schema first. destroyreads the managed schema from the recorded state. The fallback to the working-directory schema when no store was configured is gone, and a state store is now required.- Plan output folds scripts into the diff. Deployment and change-event scripts are first-class parts of the diff, shown in the plan tree (and carried on the
diffobject in--json); the separate pre/post-deployment and data-migration sections are gone. - Policy-blocked plans still render. A plan blocked by policy shows the complete diff and SQL alongside the blocking diagnostics; error severity is what stops an apply.
--destructive-actionsacceptsIgnorealongsideError,Warn, andAllow.- Abbreviated commands are spelled out.
fmtisformat,dbisdatabase, andscaffoldisnew. The old names are gone rather than aliased, so a script still using one fails loudly instead of drifting. applyre-runs policies. The policy flags now apply toapply --plan-filetoo, re-checking the saved plan before executing it.script hash,script taint, andscript untaintoperate on deployment scripts. A template-scoped script is addressed asschema.name, asscript hashlists it.- Errors you can fix are reported as diagnostics; anything else is considered a a bug. A broken configuration file, an unresolvable plugin, an unreachable database — each renders in the diagnostics table, sourced by the file and line or the plugin label that caused it. Anything else reaching the top level is a defect in NSchema: it names the exception type, links the issue tracker, and prints a stack trace unconditionally, so a report needs no re-run with a flag. Messages carry the inner-exception chain, so a cause like
Failed to connect to 127.0.0.1:5432 -> Connection refusedkeeps the part that matters. --jsondistinguishes the two. An expected failure emits a{"type":"diagnostics"}event; an internal error’s{"type":"error"}event gainsexceptionandstack, so a consumer can tell “your project is wrong” from “NSchema is broken” by a null check.
Fixed
- Editing a
PLUGINversion now works correctly.initpreferred the lockfile’s pin unconditionally, so changing a declared version and re-runninginitsilently kept restoring the old one. - An incompatible plugin doesn’t crash the CLI. This CLI will now give a proper explanation of the problem instead.
plugin updateexits non-zero when a restore fails, rather than reporting the problem and returning0.- Plugin loading now resolves a plugin’s native libraries (e.g. SQLite’s
e_sqlite3) from its restored dependency closure. newnames the right environment variable. It pointed at a per-provider variable (NSCHEMA_POSTGRES_CONNECTION_STRING) that no longer has any effect; it now namesNSCHEMA_DATABASE_CONNECTION_STRING.- Contradictory flags fail fast.
--quietwith--verbose, or--jsonwith a non-json--format, are now rejected while parsing. - A failed command always exits non-zero.
lock release,init,new, and theplugincommands reported failures but still exited0. state showreports an error when no state has been recorded yet instead of failing on a missing source.
4.5.1
Changed
- A
RUN ONCEscript that has already been run no-longer produces an informational diagnostic.
4.5.0
Added
refresh --forcerefresh fails if it finds an unreadable state payload, instead of silently overwriting it;--forcereplaces it, resetting the script ledger.state pull [file]to pull the raw recorded state payload out of the configured backend. Writes to a file or stdout.state push <file>to push the raw recorded state payload into the configured backend. Push takes the state lock (--no-lockto skip).scriptcommand group to manage the scripts recorded in the state:script listshows the recorded scripts (name, execution time, body hash);--jsonemits them as a single array.script hash [name]computes the body hash of the project’s script declarations, bare on stdout for one script, or a listing of all of them, for hand-editing pulled state.script taint <name>removes a script’s record, so it runs again on the next apply.script untaint <name>records a script as executed without running it, using the body hash from the script’s declaration. Taint and untaint take the state lock (--no-lockto skip).
4.4.0
Added
- Unified
SCRIPTstatement (viaNSchema.Core 4.4.0).SCRIPT '<name>' RUN [ALWAYS | ONCE] ON <event> AS $$…$$;is the new canonical form of deployment scripts and data migrations: the event isPRE DEPLOYMENT,POST DEPLOYMENT, or a structural change (ADD COLUMN/ALTER COLUMN TYPE/ADD CONSTRAINTwith a target path). - Run-once scripts. A
RUN ONCEscript is recorded in the state backend on a successful apply and skipped by later plans; a recorded script whose body has since changed stays skipped and warns. Plan output marks run-once scripts in the pre/post-deployment sections ((run once);runConditionin--json). Recording requires a state backend — planning without one warns. - Scripts in schema templates. Both script kinds can be declared inside a
TEMPLATE … BEGIN … END;body and instantiate once per applied schema, with the{schema}token substituted in the name and the SQL.
Changed
- Script names must be unique across the project (they identify scripts in diagnostics and run-once tracking); a template-declared script applied to multiple schemas can include
{schema}in its name.
Deprecated
- The
PRE|POST DEPLOYMENT '<name>' AS $$…$$;andMIGRATION ['name'] FOR <trigger> <path> AS $$…$$;forms still work, but plan/apply/validate now surface adeprecationswarning naming theSCRIPTreplacement. They will be removed in NSchema 5.0.
4.3.0
Added
- Data migrations. A
MIGRATION ['name'] FOR <trigger> <schema>.<table>.<member> AS $$…$$;block (viaNSchema.Core 4.3.0) attaches raw SQL to anADD COLUMN,ALTER COLUMN TYPE, orADD CONSTRAINTchange and runs only when that change is in the plan. A required column add with a matching block is applied as add-nullable → backfill →SET NOT NULL, a matching block silences the corresponding data-hazard warning, and a block matching nothing is reported as safe to delete. The plan output gains a “Data migrations” section (dataMigrationsin--json). Executing a plan with a matched block requires a provider plugin at 4.3 or later.
Changed
- The
importcommand now writes the per-schema header to<schema>/schema.sqlinstead of<schema>.sql.
Fixed
- The
nschema lock releasecommand suggested bylock statusandlock acquirenow carries the--environmentand--directoryarguments of the current invocation. - The diff now shows an added or removed column’s default expression and identity marker.
- DDL syntax errors now name the file the error was found in, alongside the existing line and column.
- The
importcommand no longer repeats theCREATE SCHEMAstatement in every object file; only the per-schema header declares the schema.
4.2.0
Added
- Data-hazard detection.
planandapply(viaNSchema.Core 4.2.0) now flag changes that are valid against the schema but can fail on the data already in a table.
4.1.0
Added
- Updated to
NSchema.Core 4.1.0which adds support for schema and table templates.
4.0.1
Fixed
- Updated to
NSchema.Core 4.0.1which fixes several issues to do with action ordering when objects are renamed.