nschema plan

Compute and show the migration plan, without changing anything.

nschema plan
nschema plan --out tonight.nplan       # save it to apply later
nschema plan --detailed-exitcode       # CI: exit 2 if the schema would change

Options

--scope <name> — limit the migration to specific database schemas (namespaces). May be repeated.
--destructive-actions <error|warn|allow> — policy for destructive changes. Defaults to error. (NSCHEMA destructive_action, env NSCHEMA_DESTRUCTIVE_ACTION_POLICY) See Destructive-action safety.
--destroy — preview the SQL that destroy would run to tear the managed schema down, instead of a forward plan (Terraform’s plan -destroy).
--out <path> — write the computed plan to a file so it can be replayed later by apply --plan-file (Terraform’s plan -out). Works with --destroy too, saving the teardown plan.
--detailed-exitcode — return a detailed exit code: 0 when there are no changes, 2 when the plan has changes (errors stay 1), so CI can gate on “does this change the schema?” without parsing output (Terraform’s plan -detailed-exitcode). Without it, plan exits 0 even when there are changes.

Saving a plan

Write the computed plan to a file and apply that exact file later, so what was reviewed is exactly what runs — useful when planning and applying happen in separate steps (plan in a pull request, apply after approval):

nschema plan --out tonight.nplan
nschema apply --plan-file tonight.nplan

See The plan / apply workflow for the full pattern.

Previewing a teardown

With --destroy the command previews a teardown rather than a forward migration. It takes the same inputs as destroy — a live database the teardown SQL is rendered against, and a managed-schema source (a configured state store, or a desired schema to fall back on) — but only shows the SQL; it never connects to apply it, prompts, or writes state. --scope and --destructive-actions don’t apply to a teardown and are ignored.

nschema plan --destroy