The full SchemaQuench reference for MariaDB deployments — configuration, execution flow, WhatIf previews, migration tracking, checkpoint/resume, and FK-aware data delivery.
By the SchemaSmith Team · Last reviewed
Take your declared schema and harden it onto a live database — that's what SchemaQuench does.
It reads a schema package, connects to the target server, and transforms each database to match the desired state. No hand-written ALTER scripts, no guessing what changed. Run it against dev, staging, and production with the same package, the same confidence, and the same boring, predictable result every time. SchemaQuench compares current state against desired state, makes only the changes necessary, and tracks migration scripts so they execute only once.
One executable, every supported platform. The product's Platform value — MariaDb for a MariaDB package — tells SchemaQuench which adapter, which DDL flavor, and which set of helper procedures to use. Everything else looks the same.
SchemaQuench is included in the SchemaSmith distribution. Run it from the directory containing SchemaQuench.settings.json:
schemaquench
Point SchemaQuench at an alternate settings file or log directory:
SchemaQuench --ConfigFile:path\to\alternate.settings.json
SchemaQuench --LogPath:path\to\logs
schemaquench --ConfigFile:path/to/alternate.settings.json
schemaquench --LogPath:path/to/logs
Run a pre-flight check that lints the package, or validates the connection and version floor, then exits without deploying — see Pre-flight diagnostics:
schemaquench --Validate
schemaquench --TestConnection
schemaquench --PreviewTargets
Point SchemaQuench at a MariaDB target with --ConnectionString:
schemaquench --ConnectionString:"Server=db1;Database=mysql;User=deploy"
The --ConnectionString switch bypasses all Target settings and passes the value directly to the MariaDB driver.
SchemaQuench reads configuration from SchemaQuench.settings.json (or the file specified by --ConfigFile), environment variables with the SmithySettings_ prefix, and command-line switches. Later sources override earlier ones. For the full loading-order and precedence rules, see Configuration.
| Key | Type | Default | Description |
|---|---|---|---|
Target:Server | string | (required) | Database server hostname or IP. |
Target:Port | string | 3306 | TCP port for MariaDB. |
Target:User | string | (empty) | Login username. |
Target:Password | string | (empty) | Login password. |
Target:ConnectionProperties | object | {} | Arbitrary key-value pairs appended to the connection string. Platform-specific keys — see Connection configuration. |
| Key | Type | Default | Description |
|---|---|---|---|
Target:Templates | string array | [] | Run only these templates. Empty array means no filter — all templates run. See Target. |
Target:Databases | string array | [] | Run only against these databases. Empty array means no filter — all discovered databases run. See Target. |
Target:TemplateTargets | object | {} | Per-template target override, keyed by template name: supplies that template's databases for this environment in place of its DatabaseIdentificationScript. See TemplateTargets. |
MariaDB has no schema-inside-database concept, so the Target:Schemas filter array does not apply and is omitted here — selective scope narrows by Templates and Databases only. See Target.
| Key | Type | Default | Description |
|---|---|---|---|
SchemaPackagePath | string | (required) | Path to the schema package directory or ZIP file. |
WhatIfONLY | bool | false | Dry-run mode. Generates SQL without executing. The --WhatIf switch turns it on for one run. |
KindleTheForge | bool | true | Deploy SchemaSmith helper procedures and the migration tracking table to each target database before quenching. |
ForceReKindle | bool | false | Re-deploy SchemaSmith's helper procedures even when the in-database kindle stamp is current. The --ForceReKindle switch turns it on for one run. See ForceReKindle. |
UpdateTables | bool | true | Apply table structure changes (columns, indexes, constraints, foreign keys) from the schema package. |
OnlineApply | string | Off | Off, Prefer or Require: whether a deploy uses the engine's lower-lock forms of index and column changes. A table's own OnlineApply overrides it. See OnlineApply. |
RebuildPolicyMode | string | (unset) | The environment tier of the rebuild policy: NEVER, ALWAYS or THRESHOLD, deciding when SchemaQuench rebuilds a table instead of altering it in place. A product, template or table that declares its own policy replaces it whole. With no policy declared anywhere, tables are altered in place. See SchemaQuench runtime controls. |
RebuildPolicyThreshold | int | (unset) | With THRESHOLD, the number of pending column modifications that triggers a rebuild. |
RebuildPolicyOnOrderMismatch | bool | (unset) | true also rebuilds a table whose deployed column order has drifted from the package. Composes with any mode. Under OnlineApply Prefer or Require, a table rebuilt only for its column order has its columns moved into order in place instead. See OnlineApply. |
SystemVersioningAlterHistory | string | (unset) | KEEP lets a column change on a system-versioned table proceed, and rewrites the stored history to match. Unset, MariaDB refuses the change. See SchemaQuench runtime controls. |
DeliverData | bool | true | Run the per-table DataDelivery step and the TableData-slot scripts. Set to false to ship a structure-only deployment that leaves reference data untouched — pairs naturally with UpdateTables: true for "deploy schema, skip data" pipelines. |
RunScriptsTwice | bool | false | Run object scripts twice to verify idempotency. A CI/testing tool. |
Target:SkipUnchangedObjects | bool | true | Do not re-run an object script whose text is unchanged since it last applied and whose object the server still renders as it was left. A hand change on the server, an edited script, an [ALWAYS] name or a -- SchemaSmith: AlwaysRun comment runs it again. The key lives under Target; a top-level SkipUnchangedObjects is not read. See Unchanged object scripts. |
Target:UnsupportedFeaturePolicy | string | warn | What to do when the package declares a feature the detected target version cannot support. warn emits the object without the unsupported aspect and records it in the deployment summary; fail aborts the run with a message naming the feature and the version it requires. See Engine version compatibility. |
TrackRunOnceMigrations | bool | true | Track run-once migration scripts. When false, all scripts run on every deployment. |
PruneObsoleteMigrationTracking | bool | true | Remove tracking entries for scripts no longer in the package. When Target filters are active, prune is restricted to the targeted scope — see PruneObsoleteMigrationTracking. |
CheckpointDirectory | string | "" | Directory for checkpoint files used by --ResumeQuench. When blank, defaults to a per-platform temp location. See Checkpoint and Resume. |
MaxThreads | int | 10 | Maximum parallel work units. Range 1–20; a value outside it, or one that is not a whole number, falls back to 10. See MaxThreads. |
ScriptTokens | object | {} | Config-level overrides for product script tokens. |
| Key | Type | Default | Description |
|---|---|---|---|
PreventDrop | bool | false | Environment-wide no-drop protection: when true, the drop-by-absence passes listed under PreventDrop are suppressed for the run, and it completes normally, itemizing the withheld table, column, foreign-key, constraint and index drops in the deployment summary's preventDrop manifest. Transient drop-then-recreate for a declared change is unaffected. See PreventDrop. |
DropTablesRemovedFromProduct | bool | true | Drop tables that exist in the database but aren't defined in the schema package. Also settable as a Product.json property — see DropTablesRemovedFromProduct. |
DropColumnsRemovedFromProduct | bool | true | Drop columns that exist in the database but aren't defined in the schema package. Resolves across a four-tier cascade (env → product → template → table) with explicit-false-sticky semantics. See Per-type drop protection. |
DropForeignKeysRemovedFromProduct | bool | true | Drop foreign keys that exist in the database but no longer appear in the table JSON. Four-tier cascade, explicit-false-sticky. See Per-type drop protection. |
DropCheckConstraintsRemovedFromProduct | bool | true | Drop table-level CHECK constraints that exist in the database but no longer appear in the table JSON. Four-tier cascade, explicit-false-sticky. See Per-type drop protection. |
DropIndexesRemovedFromProduct | bool | true | Drop a product-owned index (one SchemaSmith created and tracks) that no longer appears in the table JSON. Four-tier cascade, explicit-false-sticky. See Per-type drop protection. |
DropUnknownIndexes | bool | false | Drop indexes on managed tables that aren't defined in the schema package — out-of-band indexes SchemaSmith never created. Three-tier cascade (env → product → template), explicit-false-sticky. See Per-type drop protection. |
DropPeriodsRemovedFromProduct | bool | (unset) | true drops an application-time period that the package no longer declares. Unset, the period stays: this flag defaults off, unlike most of the family. A table's own DropPeriodsRemovedFromProduct overrides it. See Per-type drop protection. |
DropEventsRemovedFromProduct | bool | false | Drop a scheduled event that exists on the server but no longer appears in the package. Environment-level only: an event has no product, template or table tier. See Per-type drop protection. |
| Key | Type | Default | Description |
|---|---|---|---|
VerboseLogging | bool | false | Has no effect on MariaDB: SchemaQuench does not log informational messages from MariaDB scripts. SchemaSmith's own progress messages always appear. |
WriteDebugSql | bool | false | Write the SQL of each step SchemaQuench runs to .sql files in ArtifactPath. The files hold real values, for local debugging only. The --WriteDebugSql switch turns it on for one run. See Failure artifacts and debug SQL. |
ArtifactPath | string | (unset) | Directory where WriteDebugSql writes the files. Unset, the current working directory; a relative path is resolved from it. The directory is created if it does not exist. See Failure artifacts and debug SQL. |
FailureContextLines | int | 25 | How many lines of lead-up context each failure captures in SchemaQuench - Failures.log. 0 disables context capture; the roll-up still lists the failed scopes and their errors. See Failure triage roll-up. |
BottleneckThresholdMs | int | 30000 | The milliseconds an individual slot measurement must exceed to be listed as a bottleneck in the deployment summary. See Deployment summary report. |
ExitNonZeroOnWarning | bool | false | Exit 1 instead of 0 when the run finished but logged a warning, for pipelines that treat warnings as failures. Never lowers or replaces a failure code. The --ExitNonZeroOnWarning switch turns it on for one run. See Exit codes. |
LogHygiene | object | (unset) | Tunes how sensitive values are kept out of the logs, with the LogTokens, ScrubTokens, ScrubPatterns and AllowTokens keys. Unset, the default scrubbing applies. See Tuning the scrubbing. |
ScrubArtifacts is deprecated and does nothing; a settings file that still carries it gets a warning. See Failure artifacts and debug SQL.
Every setting SchemaQuench reads for a MariaDB deployment. Apart from the Target connection values and SchemaPackagePath, each is shown at its default, and a setting shown as "" is not set, so SchemaQuench applies its default behavior.
{
"Target": {
"Server": "localhost",
"Port": "3306",
"User": "deploy",
"Password": "",
"ConnectionProperties": {
"SslMode": "Required"
},
"Templates": [],
"Databases": [],
"TemplateTargets": {},
"SkipUnchangedObjects": true,
"UnsupportedFeaturePolicy": "warn"
},
"SchemaPackagePath": "./MyProduct",
"WhatIfONLY": false,
"KindleTheForge": true,
"ForceReKindle": false,
"UpdateTables": true,
"OnlineApply": "Off",
"RebuildPolicyMode": "",
"RebuildPolicyThreshold": "",
"RebuildPolicyOnOrderMismatch": "",
"SystemVersioningAlterHistory": "",
"DeliverData": true,
"RunScriptsTwice": false,
"TrackRunOnceMigrations": true,
"PruneObsoleteMigrationTracking": true,
"CheckpointDirectory": "",
"MaxThreads": 10,
"ScriptTokens": {},
"PreventDrop": false,
"DropTablesRemovedFromProduct": true,
"DropColumnsRemovedFromProduct": true,
"DropForeignKeysRemovedFromProduct": true,
"DropCheckConstraintsRemovedFromProduct": true,
"DropIndexesRemovedFromProduct": true,
"DropUnknownIndexes": "",
"DropPeriodsRemovedFromProduct": "",
"DropEventsRemovedFromProduct": false,
"VerboseLogging": false,
"WriteDebugSql": false,
"ArtifactPath": "",
"FailureContextLines": 25,
"BottleneckThresholdMs": 30000,
"ExitNonZeroOnWarning": false,
"LogHygiene": {
"LogTokens": true
}
}
DropUnknownIndexes defaults to false but is shown as "" on purpose. An explicit false at the environment tier is sticky: it locks the flag off for every product and template, so a product that turns it on is overruled. Leaving it unset lets them decide.
For environment variable mapping, see Environment variables.
Selective execution scope narrows a deployment to a subset of the work the product would otherwise perform. The most common use is deploying to a single newly-onboarded tenant without re-running the full product, canary-deploying a hotfix to one tenant to verify it before rolling out, or re-running a single template after a configuration change. Without Target, every template runs against every discovered database.
MariaDB has no schema-inside-database concept, so there is no Target:Schemas dimension — scope narrows by template and database only.
| Key | Type | Default | Description |
|---|---|---|---|
Target:Templates | string array | [] | Run only these templates. Empty array means no filter — all templates run. |
Target:Databases | string array | [] | Run only against these databases. Empty array means no filter — all discovered databases run. |
The two dimensions filter AND together. Setting Target:Templates: ["TenantWorkspace"] and Target:Databases: ["tenant_newco"] runs only the TenantWorkspace template, and within that template only the iteration where the database is tenant_newco. Unmatched work units are skipped before any database connections open for them.
SchemaQuench validates filter values against the discovered universe before dispatching any work. A value that doesn't match anything in the discovered set fails immediately with a diagnostic that lists the available options, so a typo surfaces as a clear error rather than a silent empty run.
Deploy TenantWorkspace to a newly-onboarded tenant database without touching any existing tenants:
{
"Target": {
"Server": "production-db",
"Templates": ["TenantWorkspace"],
"Databases": ["tenant_newco"]
}
}
With this configuration, SchemaQuench runs TenantWorkspace and skips every other template in TemplateOrder. Within TenantWorkspace, it runs only the tenant_newco database — tenant_acme, tenant_beta, and all other tenant databases are untouched, and their tracking rows in CompletedMigrationScripts are preserved exactly. For a full narrative walkthrough of tenant onboarding, see Multi-tenant deployments.
When Target filters are active, PruneObsoleteMigrationTracking is restricted to the targeted scope. This is intentional — pruning tracking rows outside the targeted scope would delete correct records of migrations applied against databases you explicitly excluded from this run. See PruneObsoleteMigrationTracking for the full rule.
Target.TemplateTargets lets the deployment system own the universe a template fans out across, instead of asking the target server to enumerate it. A template's DatabaseIdentificationScript still defines the package's contract — this block replaces the script's result at runtime for one named template, per environment. The pattern unlocks single-canonical-package deployments where each environment's settings file declares which tenant databases belong on that target, and SchemaQuench reconciles existence (optionally provisioning what's missing) before deploying.
{
"Target": {
"TemplateTargets": {
"TenantBody": {
"Databases": ["tenant_acme", "tenant_globex"],
"CreateIfMissing": true
},
"Shared": {
"Databases": ["tenant_acme"]
}
}
}
}
Each key under TemplateTargets is a template name as declared in Product.json.TemplateOrder. On MariaDB the value carries the database axis; the schema axis does not apply (see the callout below).
String array. Replaces the result of the named template's DatabaseIdentificationScript for this run. When set, the listed databases ARE the universe — the discovery script does not run. The template must declare a DatabaseIdentificationScript in its Template.json; if you don't need real discovery, the recommended marker is "SELECT 'CONFIG-DRIVEN' AS DatabaseName WHERE 1=0" — a placeholder that returns no rows and signals "this template is database-fan-out, the universe lives in settings."
Boolean. Default false. Controls what happens when an entry in Databases doesn't exist on the target server:
| State | CreateIfMissing: true | CreateIfMissing: false (default) |
|---|---|---|
| Target exists | Deploy normally | Deploy normally |
| Target missing | Provision (DDL), then deploy | Skip with info log, no error |
When true, SchemaQuench issues idempotent CREATE DATABASE IF NOT EXISTS against information_schema before deploying into the new target — so the credential the user supplied to SchemaQuench must carry CREATE DATABASE privilege. When false and a target is missing, the engine emits an info log naming the skipped target and continues with the rest of the override list; no work units run for the missing target, no error.
TemplateTargets is validated against the loaded product before any deployment work runs. Rules fail fast with a precise diagnostic naming the offending entry: unknown template name, template excluded by Target.Templates, empty entry (no Databases), Databases declared without a DatabaseIdentificationScript, and filter values composing with Target.Databases to produce an empty universe. On MariaDB, declaring a Schemas axis is rejected as well. A misconfiguration cannot reach a deployment connection.
TemplateTargets replaces the source of a template's fan-out universe; Target.Templates / Target.Databases still filter the result. The override produces the universe, then the filters narrow it. See Target for the filter semantics — composition is straightforward: Target.Databases keeps only entries that match its allow-list, whether those entries came from discovery or an override.
MariaDB has no schema-inside-database concept. TemplateTargets.<template>.Schemas is rejected on MariaDB templates: it requires a SchemaIdentificationScript, and on MariaDB that key is only a deprecated alias, migrated to DatabaseIdentificationScript at load. Use the database axis instead; multi-tenant on MariaDB is database-per-tenant.
CreateIfMissing: true needs CREATE DATABASE privilege — provisioning runs against information_schema. A permission denial surfaces an actionable diagnostic naming the missing privilege, but the deployment fails fast at that target. If your deployment account is intentionally low-privilege, leave CreateIfMissing: false and provision the database externally; SchemaQuench will pick the target up as soon as it exists.
For users who don't need declarative provisioning and are happy letting discovery scripts return the live universe, the existing DatabaseIdentificationScript (which can interpolate query-tokens, read tenant tables, or query system catalogs) remains the right tool. Reach for TemplateTargets when the deployment system needs to own the universe declaratively — typically when one canonical package ships to multiple environments with per-environment tenant rosters.
For a worked end-to-end example — single canonical package, per-region settings files, first-run provisioning, subsequent-run idempotent refresh, onboarding a new tenant — see Multi-tenant deployments — region-rotated tenant rosters.
The MaxThreads setting controls how many of a template's work units run concurrently, and templates themselves run one at a time, in TemplateOrder. On MariaDB, a work unit is one database iteration — MariaDB has no schema-inside-database concept, so there are no (database, schema) work units and {{SchemaName}} is not available.
Default: 10. Range: 1–20. A value outside that range, or one that does not parse as a whole number, is replaced by the default without a message, so MaxThreads: 32 runs ten at a time, not twenty.
A template that fans out across many databases deploys up to MaxThreads of them at once, and the next template starts only when it has finished.
A template with AllowParallel: false runs its iterations one at a time. Templates never run concurrently, so the setting governs only that template's own iterations. See Products & Templates — AllowParallel for the per-template parallel-disable case.
Failure isolation is controlled by template-level flags set in Template.json, not in SchemaQuench.settings.json. On MariaDB, database-level isolation is the operative case — MariaDB has no schema templates, so the schema-level flag has no effect.
Failure isolation at the database level applies to every template. When ContinueOnDatabaseFailure is true (the default), one database's failure does not abort the product run; SchemaQuench logs the failure, continues processing remaining databases, and exits with code 2 after all work units have completed or failed. Continuing does not make the run complete: after any failure, the product's After Product scripts and its VersionStampScript are skipped, so the next run is not told this version is deployed. A later --ResumeQuench that finishes the failed work runs them.
When false, the first database-level failure aborts subsequent iterations. In-flight work units drain naturally — SchemaQuench does not cancel active database connections because an incomplete transaction is more hazardous than a completed one. The product run exits with code 2.
{
"Name": "CustomerDB",
"DatabaseIdentificationScript": "...",
"ContinueOnDatabaseFailure": false
}
ContinueOnSchemaFailure governs schema-iteration failures inside a schema template. MariaDB has no schema-inside-database concept and therefore no schema templates, so the flag is ignored on MariaDB; a non-default value logs a warning at load time. Database-level failure isolation on any MariaDB template is governed by ContinueOnDatabaseFailure above.
When SchemaQuench runs, the product quench executes these steps in order:
Product.ValidationScript is configured, executes it against information_schema. Aborts if the result is falsy.Product.BaselineValidationScript is configured, executes it. Aborts if the result is falsy.Product.TemplateOrder, merging template-level ScriptTokens over the product token set, then checks TemplateTargets and Target.Templates against them and, on a server that folds table names, refuses two tables differing only in case (see Name case on MariaDB). None of this touches a database, so an error here stops the run before anything has changed.Before Product folder(s) against the administrative connection.Product.TemplateOrder:
DatabaseIdentificationScript against information_schema to discover target databases.(database, schema) pairs).MaxThreads concurrent workers. Each worker runs the full database quench sequence for its assigned database.ContinueOnDatabaseFailure setting.After Product folder(s).Product.VersionStampScript is configured, executes it.After the quench returns, the calling program backs up log files to a numbered directory and exits with code 0 (see Exit codes).
For each database identified by a template's DatabaseIdentificationScript, the database quench runs the following sequence. All steps execute on the identified database.
This list is the authoritative order. A step named for a procedure (ModifiedTableQuench, ForeignKeyQuench) is the procedure SchemaQuench calls on the target; the work inside each is listed under Modular quench procedures. Steps marked checkpointed are the ones a resumed run can skip.
SkipIfReadOnly skips a read-only target (a replica) and counts it as a success.{{ServerMajorVersion}} token; {{CompatibilityLevel}} resolves to the same value on MariaDB.ShouldApplyExpression is evaluated against this database, and the scripts of a folder whose gate is false leave every slot list for this iteration. The version tokens are then substituted into the scripts and the table, event and sequence payloads. See ShouldApplyExpression and conditional deployment.KindleTheForge is false. See KindleTheForge and What SchemaSmith installs in your database.Template.BaselineValidationScript if configured; a falsy result or an error stops the deploy. Checkpointed as ValidateBaseline.Setup slot, before any object or table is touched. Sequential, run on every deploy, and the first error stops the deploy. See The Setup slot.Objects-slot scripts whose text holds no {{…}} token (a script that needs a query token is held back), using the dependency retry loop. If RunScriptsTwice is enabled, runs a complete second pass to verify idempotency.nextval(). Checkpointed as SequenceQuench.Tables/*.json into session working tables for every later table step, then, in this order: refuses the deploy if another product owns a declared table; checks each expression SchemaSmith has not recorded on a scratch copy (ExpressionMapAdopt, see Expression change detection); and runs MissingTableAndColumnQuench, which renames tables and columns by OldName, creates missing tables and adds missing columns. Never checkpointed — a resumed run repeats it to rebuild the session working tables. Skipped when UpdateTables is false or the template is index-only.Objects-slot scripts, now that missing tables exist, then resolves the template's query tokens into every slot's scripts.Before slot. Sequential and tracked.ModifiedTables.VECTOR index whose M or Distance changed, for step 16 to build again as declared.AfterTablesObjects-slot scripts (triggers, post-table views) using the dependency retry loop, together with any Objects-slot script not yet applied — including the ones steps 7 and 10 held back for a query token, whose values step 10 has since resolved.BetweenTablesAndKeys slot. Sequential and tracked.IndexOnlyQuench here instead. Checkpointed as IndexesAndConstraints.AfterTablesScripts slot. Sequential and tracked.Objects- and AfterTablesObjects-slot scripts not yet applied, with the final attempt's failures reported as errors.DataDelivery blocks, ordered by foreign key dependencies. See Table data delivery. Then executes any hand-written scripts in the TableData slot using the dependency retry loop. Skipped when DeliverData is false. Checkpointed as TableDataDelivery.ForeignKeys.EventQuench procedure when the template declares any. Checkpointed as EventQuench.After slot. Sequential and tracked.Template.VersionStampScript if configured. Checkpointed as VersionStamp.As the work unit ends, SchemaQuench reads and clears the change-audit rows its procedures wrote for the deployment summary, and drops the session working tables.
When UpdateTables is false, the table steps — 9, 12, 13, 16, 17 and 21 — are skipped; scripts, data delivery and step 22 still run. When IndexOnlyTableQuenches is enabled on a template, steps 9, 12 and 21 are skipped and step 16 runs the IndexOnlyQuench procedure instead, so the template manages only the indexes of tables it does not own.
Each schema package targets a single engine, declared by Platform in its Product.json, and SchemaQuench adapts the DDL it generates to the version of that engine on each target rather than demanding uniformity. The minimum supported version for every engine is listed in the table below. When you need to enforce a version floor, declare it once in Product.json.
These are the minimum versions SchemaSmith supports for deployment:
| Platform | Minimum supported |
|---|---|
| SQL Server | 2008 (major version 10) |
| PostgreSQL | 12 |
| MySQL | 5.7.22 on the 5.7 line; 8.0.23 on the 8.0 line |
| MariaDB | 10.2.13 |
These floors are enforced automatically — you do not declare anything. Before any deployment (SchemaQuench) or extraction (SchemaTongs) work begins, the target server's version is detected and logged. A below-floor server aborts the run with a clear "unsupported version" message instead of failing later with a raw engine error. MinimumVersion, below, is a separate opt-in gate for raising the floor further per product.
You can raise the floor for a specific product by declaring MinimumVersion in Product.json. Before any deployment work begins, SchemaQuench detects the version of every resolved target. If any target is below the declared floor, the entire run aborts with a manifest naming each below-floor server and its detected version. Nothing is deployed — no partial work, no side effects on any target.
For MariaDB, the accepted value is major.minor (for example 10.6 or 11.4) or major.minor.patch (10.6.4). A value with a patch is compared patch for patch. It may be any supported version, including 10.2.13 to pin exactly at the floor. If a target's version cannot be determined, that is a hard error — SchemaQuench never deploys blind against an unknown version. An unparseable MinimumVersion value fails at startup before any connections open. See Products & Templates — Product.json for the accepted formats on every platform.
Pre-flight logs the version it detected for every server, and — with one exception — that string is whatever the engine itself publishes; SchemaSmith does not reshape them into a common format. They report their versions in different forms, which reflects how each engine versions itself rather than an inconsistency in SchemaSmith's logging.
| Platform | Detected version reads like | Why that precision |
|---|---|---|
| SQL Server | 16.0.4260.1 (full build) | Servicing level is load-bearing: CREATE OR ALTER arrived in 2016 SP1, so 13.0.4001 and 13.0.1601 are the same major and behave differently |
| PostgreSQL | 16 (major) | PostgreSQL gates features on the major; the minor carries no capability difference to report. The server reports server_version_num as a packed integer (160013); SchemaSmith normalizes it to the major for display, making PostgreSQL the one engine whose logged version is not the raw string the server published |
| MySQL | 8.0.45 | Feature boundaries land mid-major — CHECK constraints at 8.0.16 — so a major alone cannot answer the question |
| MariaDB | 11.4.12-MariaDB-ubu2404 | Same reason, plus the vendor and build tail the server appends — RENAME COLUMN at 10.5.2, native UUID at 10.7 |
Normalizing every engine to a bare major would read tidier and tell you less. On all but one it would discard the digits SchemaSmith's own version gates turn on — servicing levels on SQL Server, mid-major feature boundaries on MySQL and MariaDB — and a degrade you needed to diagnose would become invisible in the log.
The comparison is unaffected either way: the floor check and MinimumVersion both parse each engine's own form correctly, so a passing or failing verdict never depends on how the string is printed. What you declare is a separate, friendlier grammar — 16 or 2022 on SQL Server, 15 on PostgreSQL, 8.0 on MySQL, 10.6 on MariaDB. You never have to match the detected string's shape.
When the supported range across your targets diverges, SchemaSmith adapts the DDL it generates automatically. There is nothing to configure — you deploy the same package to older and newer engine versions and SchemaSmith picks the right form for each target. These cases apply to MariaDB, whose supported range (10.2.13 through current) spans versions that differ in available DDL and JSON support.
The schema model itself parses on every supported version. A version-agnostic JSON_EXTRACT shred stands in for JSON_TABLE (MariaDB 10.6 and later), so kindling and ingest do not depend on the target version.
Automatic table-data delivery has full support at the floor: on MariaDB 10.2 it uses a recursive-CTE shred. MariaDB patches whose JSON_TABLE keeps string escapes literally (MDEV-27412: 10.6 before 10.6.20, 10.11 before 10.11.10, 11.2 before 11.2.6, 11.4 before 11.4.4, 11.6 before 11.6.2, and every 10.7–10.10, 11.0, 11.1, 11.3 and 11.5 patch) use the same shred, which is slower on large tables.
Beyond that, SchemaSmith takes one of two paths. For a feature with an equivalent form that reaches the same end state, it uses the equivalent syntax automatically — nothing is degraded, only the implementation changes. For a feature with no equivalent, the unsupported-feature policy (Target:UnsupportedFeaturePolicy) decides what happens: the default warn applies the object without the unsupported aspect and lists each affected object under Unsupported Feature Downgrades in the deployment summary, while fail aborts instead and names the required version.
| Authored feature | Requires | Below that version, SchemaSmith… |
|---|---|---|
Column rename (RENAME COLUMN) | MariaDB 10.5.2 | reproduces the rename with CHANGE COLUMN, reconstructing the current column definition (same end state) |
Index rename (RENAME INDEX) | MariaDB 10.5.2 | drops and recreates the index under the new name from its live definition (same end state) |
Instant column add or drop (OnlineApply Prefer or Require) | MariaDB 10.4 | adds or drops the column with ALGORITHM=INPLACE, LOCK=NONE instead, which rebuilds the table without blocking writes, and records online as its mode. MariaDB 10.3 adds instantly only at the end of the table; MariaDB 10.2 has no INSTANT |
Online table copy (OnlineApply Prefer, ALGORITHM=COPY, LOCK=NONE) | MariaDB 11.2 | runs a change INPLACE cannot take, such as a column type change, as written, blocking writes while it copies, and records unavailable as its mode; under Require the deploy is refused, naming the statement |
| CHECK constraints | MariaDB 10.2.22 | applies the table without the check and records a downgrade (MariaDB before 10.2.22 has no INFORMATION_SCHEMA.CHECK_CONSTRAINTS, so a deployed check cannot be read back). A column's own CheckExpression is skipped and recorded the same way. Because a check cannot be read before 10.2.22, one created outside SchemaSmith is not dropped ahead of a column it reads, so removing that column fails with the engine's error; drop the check in a Before script |
Invisible index (IGNORED) | MariaDB 10.6 | stores the index visible — the visibility clause is suppressed — and records a downgrade. The modified-index compare ignores the visibility difference below the floor, so re-deploys stay idempotent |
Invisible column (Column.Invisible) | MariaDB 10.3 | stores the column visible — the INVISIBLE clause is suppressed — and records a downgrade. The modified-column compare ignores the visibility difference below the floor, so re-deploys stay idempotent instead of churning the column every run |
Descending index key parts (… DESC) | MariaDB 10.8 | stores the key part ascending (the engine silently does so anyway) and records a downgrade |
Long unique key (UNIQUE … USING HASH, extracted from MariaDB 10.4 and later) | MariaDB 10.4 | refuses the deploy by name before anything is created, under either policy. InnoDB on 10.2 and 10.3 cannot enforce the key, and skipping it would drop the uniqueness. Only a key too wide for a B-tree is refused (a TEXT, BLOB or JSON column used in full, or a character column over 768 characters); a narrower one is built as a B-tree, as it always was |
Application-time period (PERIOD FOR) | MariaDB 10.4.3 | creates the table without the period and records a downgrade |
Temporal key (a unique or primary key with WithoutOverlaps: true over a period) | MariaDB 10.5.3 | creates the key over the period's end and start columns, without WITHOUT OVERLAPS, and records a downgrade |
Vector index (IndexType: VECTOR) | MariaDB 11.7 | skips the index and records a downgrade |
Explicit system-time columns (declared GeneratedAlways RowStart / RowEnd on an existing table that has the implicit pair) | MariaDB 11.7 | keeps the table's hidden row_start / row_end and records a downgrade. A new table takes the declared columns on every version that has system versioning |
Table-level system versioning (WITH SYSTEM VERSIONING) | MariaDB 10.3 | creates an ordinary, non-versioned table and records a downgrade |
SYSTEM_TIME partitioning by count or with STARTS (a SYSTEM_TIME table with no partition list, or with StartsAt) | MariaDB 10.5 | creates the versioned table without its SYSTEM_TIME partitioning and records a downgrade. MariaDB 10.3 and 10.4 accept only a list that names every partition, which deploys there |
COLLATE on a generated column | MariaDB 10.2.37 / 10.3.28 / 10.4.18 / 10.5.9, on each line | creates the column in its character set's default collation (the set read from the Collation when CharacterSet is not declared) and records a downgrade; earlier patches reject the clause, and a redeploy leaves the column as it is |
SYSTEM_TIME partitioning with AUTO | MariaDB 10.9.1 | creates the partitioning without AUTO and records a downgrade: the history is still partitioned, and new history partitions are added by hand |
Per-column history exclusion (WITHOUT SYSTEM VERSIONING) | MariaDB 10.3.4 | creates the column without the exclusion and records a downgrade — the column survives, the exclusion does not |
Declared sequence (Sequences/*.json) | MariaDB 10.3 | skips the sequence and records a downgrade |
Sequence data type (DataType other than bigint) | MariaDB 11.5 | creates the sequence as a signed bigint and records a downgrade |
| Functional / expression index (a key part that is an expression) | No equivalent on MariaDB at any version | skips the index and records a downgrade |
Column SRID restriction (SRID n on a spatial column) | No equivalent on MariaDB at any version | creates the column without the SRID restriction and records a downgrade |
"No equivalent at any version" is not the same as "old". The last two rows above are not version gates at all — MariaDB has no SRID restriction or functional index at any release. Those degrade on every MariaDB target, current versions included, which is why they appear here rather than reading as legacy concerns.
The version-sensitive catalog reads (CHECK constraints, index visibility) are branched so they parse on the older server too, and integer display widths and foreign-key default actions are normalized on compare so an unchanged table doesn't phantom-modify across versions. The end state is identical — deploy the same package to MariaDB 10.2.13 through current and you get the same database, minus only the features the target genuinely cannot support, which the deployment summary names.
SchemaQuench emits MariaDB's own native DDL, and a few forms are specific to the engine. You do not configure any of this — SchemaSmith detects the target and emits the correct form automatically.
CREATE INDEX … IGNORED, and its visibility is read back from the IGNORED column of INFORMATION_SCHEMA.STATISTICS, where 'YES' means the index is ignored.ALTER TABLE … DROP CONSTRAINT.INFORMATION_SCHEMA.COLUMNS.COLUMN_DEFAULT quotes string literals, reports a literal NULL marker for a nullable column that has no default, and parenthesizes function defaults such as current_timestamp(). SchemaSmith folds these back to a canonical form on compare, so an unchanged column does not phantom-modify on every deploy.One difference is yours to handle: MariaDB rejects a NOT NULL INVISIBLE column with no DEFAULT (engine error 4108, “must have a default value”). Give the column a Default, or leave it nullable. SchemaSmith does not pre-validate this; the engine's own error passes through unmodified.
This one is not about the DDL SchemaQuench generates — it is about comparison SQL you write, in a migration script, an After Script, or a ValidationScript. MariaDB 11.4 changed the default collation for utf8mb4 to utf8mb4_uca1400_ai_ci.
When you compare a string produced at run time (a value derived from JSON_TABLE, for instance, which takes that new default) against a column stored under a different collation, MariaDB raises Illegal mix of collations rather than coercing. Add an explicit COLLATE to one side so both operands share a collation, for example WHERE t.name = j.name COLLATE utf8mb4_general_ci. This is distinct from a latin1 target database charset, which SchemaSmith handles internally.
MariaDB decides whether two names are the same object from the server setting lower_case_table_names. SchemaSmith asks the server and follows its answer, so one package deploys the same way whichever setting the target runs.
| Setting | Database and table names | Usual default on |
|---|---|---|
0 | Case-sensitive: Orders and orders are two tables | Linux |
1 | Stored in lowercase; any spelling finds the table | Windows |
2 | Stored as declared, compared case-insensitively | macOS |
Column, index, CHECK and foreign-key names are case-insensitive on every setting. When the server holds one of them under a spelling that differs from your package only in case, SchemaSmith keeps the object and its data and converges it to your package's spelling. An index is dropped and re-created rather than renamed, because a case-only index rename corrupts the index dictionary on some MariaDB versions. An index that starts with a foreign key's column keeps its existing spelling, because the engine will not drop an index a foreign key depends on.
One exception, on older MariaDB patches. From 10.3 until 10.6.26, 10.11.17 and 11.4.11 (and the series between them, which never received the fix), MariaDB cannot change the case of an index's name while a foreign key needs that index: the statement runs and the old spelling stays. On those versions SchemaSmith leaves such an index under its existing spelling and warns, naming it, rather than rebuilding the table on every deploy to no effect. The index, the key and their data are untouched; only the spelling differs from your package. Upgrade the server to converge it.
A server on setting 1 or 2 has two consequences worth knowing:
1 writes lowercase table names, because the server holds no other spelling. Setting 2 keeps the declared spelling.2) on a server on setting 1 or 2, before any database is touched — the server would hold one table for both. Variants gated by ShouldApplyExpression are not a collision. --Validate reports such a pair as SS-DUP-001 whatever the target.Two things a deploy does on MariaDB, because the engine gives no other way:
DROP TRIGGER IF EXISTS followed by CREATE TRIGGER, and a row written to the table between the two statements is not seen by the trigger. The window is one statement wide and exists only on a deploy that changes the trigger: an unchanged script is not re-run (see Unchanged object scripts). Deploy a trigger change when the table is quiet, or inside the maintenance window the change already needs.CREATE OR REPLACE VIEW records the account that ran it as the view's DEFINER, so a view created by one account and redeployed by another changes definer, and with it whose privileges a SQL SECURITY DEFINER view runs under. A view whose script carries an explicit DEFINER clause keeps it, provided the deploying account may set it.A MariaDB server can be configured in ways that change how SQL is read and how columns and data behave. SchemaSmith runs its own work under a known setting for each of those, and puts the session back afterwards. Your scripts (Before, After, Objects, migration scripts and ValidationScript) always run under the server's own settings.
| Server setting | What SchemaSmith does |
|---|---|
sql_mode | Creates its procedures and delivers data under your server's mode with the flags that change how SQL text is read taken out: ANSI_QUOTES, PIPES_AS_CONCAT, NO_BACKSLASH_ESCAPES, IGNORE_SPACE, the combination modes ANSI, ORACLE, MSSQL, DB2, POSTGRESQL and MAXDB, NO_KEY_OPTIONS, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, EMPTY_STRING_IS_NULL, SIMULTANEOUS_ASSIGNMENT, HIGH_NOT_PRECEDENCE, REAL_AS_FLOAT and PAD_CHAR_TO_FULL_LENGTH. Strictness flags such as STRICT_TRANS_TABLES, NO_ZERO_DATE and ONLY_FULL_GROUP_BY stay as your server has them. When the server's mode changes, the next run re-creates the procedures. |
explicit_defaults_for_timestamp | Turned on while tables are created and altered, so a TIMESTAMP column gets exactly the default it declares. With it off, the default on MariaDB before 10.10, the server would invent one. A few MariaDB versions (10.2, 10.3 and early 10.4 to 10.6 patches) do not let a session change it; there the deploy logs a note, and a TIMESTAMP NOT NULL column needs its default declared. |
time_zone | DataTongs extracts at +00:00 and records that on the delivery it configures (TimeZone). Delivery uses the recorded zone, so TIMESTAMP values arrive unchanged whatever zone either server runs in. A delivery without TimeZone runs in the session's zone. |
sql_mode during data delivery | NO_AUTO_VALUE_ON_ZERO is added, so a row whose AUTO_INCREMENT key is 0 keeps 0. |
innodb_force_primary_key | SchemaSmith's own tables all have primary keys. Your tables must declare one, because the server refuses any table without it. |
lower_case_table_names | See Name case on MariaDB. |
A package that deploys cleanly today can stop deploying after the server is upgraded, because a newer engine refuses something the older one accepted. SchemaSmith's own DDL is kept to forms every supported version accepts; these are the changes that reach your declarations and your own scripts. Each was checked on the version named.
| From | What changes | What to do |
|---|---|---|
| 11.4 | The default utf8mb4 collation is utf8mb4_uca1400_ai_ci (Debian and Ubuntu packages from 11.3.2). | See the collation note above; an extraction carries it, see SchemaTongs. |
| 11.8 | innodb_snapshot_isolation is on by default: a transaction that reads a row another transaction changed after its snapshot gets error 1020 instead of reading past it. | Retry such transactions in your own scripts, or turn the setting off. |
| 11.8 | A column with CHARACTER SET x COMPRESSED is refused; COMPRESSED CHARACTER SET x still works. | Reorder it in your scripts. SchemaSmith writes the type, with any COMPRESSED, before the character set. |
| 12.3 | CONVERSION and TO_DATE are reserved words: a table or column of that name must be quoted. | The DDL SchemaSmith writes quotes table and column names; quote them in your scripts. |
SchemaQuench assigns every script folder to a quench slot that determines when the folder's scripts execute and how they are handled. The slot list is the same on every platform; the default folders vary by platform.
| Slot | Execution style |
|---|---|
Setup | Sequential, every deploy |
Before | Sequential, tracked |
Objects | Dependency retry loop |
BetweenTablesAndKeys | Sequential, tracked |
AfterTablesScripts | Sequential, tracked |
AfterTablesObjects | Dependency retry loop |
TableData | Dependency retry loop |
After | Sequential, tracked |
Setup is for what the objects and the later scripts rely on being in place first: a server or database setting, a setting a view or a migration assumes. It runs after the helpers are deployed and the baseline is validated, and before the first object pass — so nothing in the template has been touched yet. No default folder uses it; add one to ScriptFolders when you need it:
{ "FolderPath": "Setup", "QuenchSlot": "Setup" }
A setting is state, not a migration, so Setup scripts run on every deploy: a value someone changed by hand is put back the next time the package deploys. That makes each script responsible for checking before it changes anything — for example, the event scheduler a declared event relies on, switched on only when it is off (a SET GLOBAL runs through a prepared statement so it can be made conditional):
SET @ss_setup = IF(@@GLOBAL.event_scheduler = 'ON', 'DO 0', 'SET GLOBAL event_scheduler = ON');
PREPARE ss_setup FROM @ss_setup; EXECUTE ss_setup; DEALLOCATE PREPARE ss_setup;
Setup scripts run once per database. There is no retry: nothing in the template has run before them, so a script that fails will fail again, and the deploy stops at the first one. WhatIf lists them without running them, and a run resumed from a checkpoint skips the ones that already succeeded in it. Query tokens resolve in them as in any other script.
| Slot | Execution style |
|---|---|
Before | Sequential |
After | Sequential |
Product scripts run against the administrative connection, outside the per-database template loop.
CompletedMigrationScripts so they only run once (unless marked [ALWAYS]).[ALWAYS] has nothing to add. The first script that fails stops the deploy; the ones after it do not run.Objects or AfterTablesObjects script that is unchanged since it last applied, and whose object the server still holds as it was left, is not re-run. See Unchanged object scripts.See exactly what SchemaQuench would do before it touches a single table. Set WhatIfONLY to true to perform a dry run. In WhatIf mode:
p_WhatIf = 1, generating the SQL that would be executed and logging it without applying changes.Would APPLY: {script} for scripts that haven't yet been tracked.Would SKIP (previously quenched): {script} for scripts already recorded in CompletedMigrationScripts.Console verbosity — --WhatIfDetail. By default WhatIf prints one line per script (Would APPLY: … / Would SKIP … / Would DELIVER …), which is thorough but noisy on a large package. Pass --WhatIfDetail:concise to collapse each section into a per-category count (for example 12 would apply, 3 would skip); --WhatIfDetail:normal (the default) keeps the per-script lines; --WhatIfDetail:verbose is reserved for future extra detail and currently matches normal. Two kinds of line are printed one at a time at every setting: a product Before/After script's Would Quench line and a DataDelivery block's Would DELIVER line. This affects only the console stream — the SchemaQuench - Summary.md/.json files always carry the full per-script listing regardless of the switch.
WhatIf shows the top level of changes, not the full cascade. Because nothing actually executes, WhatIf can't show ripple effects that depend on earlier changes having been applied. For example, if an object script drops an index, that script doesn't run in WhatIf mode, so the index still exists when WhatIf analyzes table changes — meaning the table diff won't show the index as needing to be recreated. WhatIf is a confidence check, not a guarantee. It catches the majority of issues but the full deployment may produce additional changes that WhatIf couldn't predict.
The gaps a dry run has are each explained where the feature is; this is the one list of them.
would* actions for the deployment summary — the foreign-key and event steps included.Would APPLY, object and migration scripts as Would APPLY or Would SKIP, table-data scripts as Would DELIVER and product scripts as Would Quench. Template query tokens are not resolved, so an object script that uses one is always previewed as would-apply, never as unchanged; a migration script is matched by its path instead, so one already recorded is still previewed as a skip. Product query tokens are resolved, as on a real run. Setup scripts and the template version stamp are named, not run.SKIP (unchanged); nothing is recorded. See Unchanged object scripts.mode, because only the engine can say which form it accepts. See objectChanges.DataDirectory move and the removal of IsSystemVersioned. The exception is the foreign-key refusal in Column changes, which runs only on a live deploy.With WriteDebugSql on (or the --WriteDebugSql switch), SchemaQuench writes the SQL of each step it runs — the table, index and foreign-key quench calls, and any script that fails — to .sql files in ArtifactPath (default: the working directory), named SchemaQuench - <step> <server>.<database>.sql. It is off by default, and a failure says how to get the file. The files hold real values, for local debugging only; a run removes its own when it finishes cleanly and the previous run's for its targets when it starts. See Failure artifacts and debug SQL.
Reach for WhatIf while you're debugging a tricky deployment or while you're still building confidence with the tooling. Inspect the generated SQL, confirm the changes match intent, then run for real. Once you trust the package and the pipeline, direct quenches are the normal mode — WhatIf isn't a required gate on every deployment.
You don't have to quench to know whether your configuration is ready. Three read-only CLI switches run targeted diagnostics and exit without deploying anything — so a pipeline can fail fast on a broken package, a bad connection string, an unpropagated firewall rule, a below-floor server, or a target roster that resolved to the wrong set, long before the deploy window opens. They layer by what each one needs: the first reads nothing but the files on disk, the second opens a connection, and the third resolves the full target roster as well.
schemaquench --Validate
--Validate is SchemaQuench's static linter: it loads your schema package through the same domain model the real quench uses, runs a battery of structural checks against it, and tells you exactly what's wrong — in seconds, from a laptop or a CI runner with no database anywhere in sight. It's the fastest, cheapest gate in the whole pre-flight family, and the only one that needs nothing but the files on disk.
Run it from the directory containing SchemaQuench.settings.json, or point SchemaPackagePath at the package you want to check:
schemaquench --Validate --SchemaPackagePath=./MyProduct
No Target, no --ConnectionString, no credentials of any kind — it never opens a connection. It reads Product.json to determine the declared Platform, loads the package through that platform's domain types, runs every check, prints the findings, and exits.
What it checks:
ShouldApplyExpression.{{Token}} reference across every script and JSON file in the package, resolved as raw text..json-schemas/*.schema files, in a staleness pass followed by a structural and governance pass.SchemaIdentificationScript, the deprecated old name for DatabaseIdentificationScript. Load migrates it and deployment still works, but the package won't validate clean while it depends on something scheduled for retirement.The duplicate check runs at every level a name collision could hide: columns, indexes, foreign keys, check constraints, tables within a template, the product's TemplateOrder, MariaDB's full-text indexes, and each template's declared sequences and events.
| Code | Severity | Meaning |
|---|---|---|
SS-LOAD-001 | Error | Either the whole package failed to load (Product.json itself is missing or unparseable, or the configured path doesn't exist — every other check is skipped when this happens), or one component file (a table JSON) inside an otherwise-loadable template was unparseable and got excluded — the rest of the package still loads and every other check still runs. |
SS-LOAD-002 | Error | A whole template's own Template.json couldn't be loaded (unparseable JSON, or a self-contradictory template configuration). That template is excluded and every check for it is skipped, but every other template in the package still loads and still gets full check coverage. |
SS-LOAD-003 | Error | Product.json does not declare a Platform. Every check depends on the target engine, so nothing further is checked. Add "Platform": "MariaDb". |
SS-DUP-001 | Error | Same-name entries exist and at least one isn't gated by ShouldApplyExpression — an accidental duplicate. Checked at every table level, and across each template's declared sequences and events. |
SS-DUP-VAR-002 | Warning | Every entry in the group is gated (a legitimate variant set), but not every entry declares VariantName — label them for clarity. |
SS-FK-001 | Error | A foreign key's Columns entry names a column that doesn't exist on the local table. |
SS-FK-002 | Warning | A foreign key's RelatedTable doesn't resolve to any table in the package. A warning rather than an error because the deploy creates a foreign key to any table that already exists on the target, declared or not. A partial deployment such as a SchemaShears patch or a bootstrap references tables it does not declare by design, so expect the warning there; --Validate still exits 0. |
SS-FK-004 | Error | A foreign key's RelatedColumns entry names a column that doesn't exist on the related table. |
SS-FK-005 | Error | Columns and RelatedColumns have different entry counts — the column lists must be the same length. |
SS-FK-006 | Warning | Two tables in one template declare a foreign key with the same name. MariaDB names foreign keys per table from 12.1, so this is a Warning, and there is no finding at all when the product's MinimumVersion is 12.1 or later. |
SS-FK-009 | Warning | A foreign key declares SET DEFAULT as its DeleteAction or UpdateAction. MariaDB accepts it and then acts as RESTRICT: the change to the parent row is refused. |
SS-FK-010 | Warning | A foreign key's RelatedTable is declared in another template whose DatabaseIdentificationScript differs from this one's, so the two deploy to different databases. A foreign key resolves within its own template; the deploy succeeds only if the table already exists on this template's database. Templates with the same identification script resolve against each other. |
SS-IDX-001 | Error | An index's IndexColumns entry names a column that doesn't exist on the table. |
SS-IDX-002 | Error | An index sets WithoutOverlaps but is not a primary key or unique key, so the clause would not be emitted. |
SS-IDX-003 | Error | An index sets WithoutOverlaps but its last IndexColumns part is not one of the table's Periods. |
SS-IDX-005 | Error | A VECTOR index does not cover exactly one NOT NULL VECTOR column. MariaDB builds a vector index over one such column and refuses anything else (error 1252 for a nullable one). |
SS-IDX-006 | Error | A table declares more than one VECTOR index. MariaDB allows one per table (error 1235); the second and later are reported. |
SS-COL-002 | Warning | A column declares a CharacterSet other than the table's and no Collation, so it gets that character set's default collation, which varies by engine version. A column in the table's own character set gets the table's collation; utf8 and utf8mb3 count as one set, and a short collation such as uca1400_ai_ci belongs to the table's CharacterSet. |
SS-COL-005 | Warning | A column is declared NVARCHAR, NCHAR or NATIONAL ..., which creates a utf8mb3 column. Declare VARCHAR or CHAR with CharacterSet: utf8mb4. |
SS-COL-007 | Warning | A column's Default is a quoted function call ('CONCAT(''A'',''B'')', 'uuid()'), so it deploys as that text, not as the expression. A package extracted before 2.8 wrote expression defaults this way: re-extract it, or write the expression in parentheses ((CONCAT('A','B'))). |
SS-COL-008 | Warning | A column in a primary key is declared "Nullable": true. A key column cannot hold NULL, so the deploy makes it NOT NULL and warns before the table step; a column that already exists and holds NULLs fails that change. Remove "Nullable": true so the declaration says what deploys. A key with a ShouldApplyExpression is left as declared. |
SS-TBL-001 | Error | A RebuildPolicy — on the product, a template, or a table — uses Mode: "THRESHOLD" without a Threshold of 1 or more, so the policy cannot be evaluated. Because a policy declared at any level replaces the one it would have inherited, an unusable one also blocks rebuilds an outer level asked for. |
SS-TBL-002 | Warning | A RebuildPolicy sets a Threshold while its Mode is not "THRESHOLD", so the threshold is ignored. An omitted Mode defaults to "NEVER", so { "Threshold": 50 } on its own means never rebuild — and, replacing the inherited policy, can block rebuilds an outer level asked for. |
SS-VER-001 | Error | A product's MinimumVersion is not a version the engine can resolve, so the deploy refuses the package before touching any object. MariaDB reads the value arithmetically, so only a non-numeric one fails. Reported here because MinimumVersion has no pattern in the generated JSON schema, so an editor cannot flag it. |
SS-DESC-001 | Error | A table, column, index, full-text index or event says two different things about its description: Description and the older spelling, Comment, disagree. The deploy applies Description and ignores the other, so keep one. |
SS-CHK-002 | Error | A CheckConstraints entry is named like a column of its table. MariaDB gives that name to the column's own column-level check, which SchemaSmith reads as the column's CheckExpression, and from 10.11.19 / 11.4.13 / 13.0.2 the engine refuses a table-level check that shares it. Rename the constraint, or declare it as the column's CheckExpression. |
SS-DESC-002 | Warning | A table, column, index, full-text index or event still uses the older spelling of Description (Comment). It still deploys; move the value to Description, which is what SchemaTongs writes on re-extraction. One finding per table, naming the components. |
SS-SV-001 | Warning | A column sets WithoutSystemVersioning on a table that does not set IsSystemVersioned. MariaDB accepts the clause there and silently discards it, so the exclusion does nothing and nothing at deploy time reports it. |
SS-CO-001 | Error | A table sets PageCompressed together with RowFormat: "COMPRESSED". MariaDB refuses that combination (errno 140) and the error does not name the option. |
SS-CO-002 | Warning | A table sets PageCompressionLevel without PageCompressed, so the level is ignored. |
SS-EVT-001 | Error | A scheduled event is declared as JSON and scripted as a .sql file in the same Events folder. The scripted form drops and recreates the event on every deploy, undoing what the declared form converged. |
SS-EVT-002 | Warning | An event's comment is longer than 64 characters. MariaDB keeps the first 64 and drops the rest without a word, so the database shows a shorter comment than the package. The deploy compares the part the engine keeps, so the event is not re-created over it. |
SS-SEQ-001 | Error | A sequence is declared as JSON and scripted as a .sql file in the same Sequences folder. Two authoring paths for one object leave it ambiguous which one is in charge. |
SS-SEQ-002 | Warning | A script outside MigrationScripts re-creates a sequence with CREATE OR REPLACE SEQUENCE. Object scripts run on every deploy, and replacing a sequence resets it to its START value, so NEXTVAL returns numbers it has already given. Use CREATE SEQUENCE IF NOT EXISTS, which is how SchemaTongs extracts sequences; packages extracted by earlier versions carry the replacing form. |
SS-PART-003 | Error | A table partitions by RANGE or LIST (or their COLUMNS forms) and declares no Partitions. Each partition is named with its boundary; use HASH or KEY with a PartitionCount to spread rows without boundaries. |
SS-PART-004 | Error | A HASH or KEY partition declares a Values boundary. Those methods assign rows by hashing and have none. |
SS-PART-005 | Error | A primary or unique key does not hold a partitioning column whole: the column is missing from the key, or the key holds only a prefix of it (`code`(10)). The engine refuses the table (1503). Checked for KEY (an empty list means the primary key's columns) and the COLUMNS forms; an expression method's columns are not read. |
SS-PART-006 | Error | A table partitions by SYSTEM_TIME but does not set IsSystemVersioned: true. SYSTEM_TIME partitions a system-versioned table's history; the engine refuses it on any other table (4124). |
SS-PART-007 | Error | A table partitions by a method other than SYSTEM_TIME but declares no Expression. |
SS-PART-008 | Error | A partitioned table declares a foreign key, or a foreign key references a partitioned table. InnoDB has no foreign keys on a partitioned table on either side, so the engine refuses it (1506, or errno 150 on the referencing side). |
SS-PART-010 | Error | PartitionCount and the named Partitions disagree on how many partitions there are; the engine refuses the table. |
SS-PART-011 | Error | A RANGE or LIST partition's Values carries its own clause (LESS THAN ..., VALUES ..., IN (...)). Values is the boundary alone (2025, MAXVALUE, 1, 2); the deploy writes VALUES LESS THAN or VALUES IN around it. |
SS-PART-012 | Error | Subpartitioning under a method other than RANGE or LIST. Only those can be subpartitioned, and under SYSTEM_TIME the clause would be dropped. |
SS-PART-013 | Error | SYSTEM_TIME partitioning with both Interval and Limit. MariaDB takes one or the other. |
SS-PART-014 | Error | SYSTEM_TIME partitioning with Auto and neither Interval nor Limit, which AUTO adds history partitions by. |
SS-PART-015 | Error | SYSTEM_TIME partitions that MariaDB refuses (4128): a PartitionCount below 2, or named partitions without one or more HISTORY partitions and exactly one CURRENT partition, last. Each Values is HISTORY or CURRENT. |
SS-PART-016 | Warning | A partitioning value the deploy ignores: SystemTime outside SYSTEM_TIME, Expression under SYSTEM_TIME, KeyAlgorithm outside KEY, or SystemTime.StartsAt without an Interval. |
SS-PER-001 | Error | A period's StartColumn or EndColumn names no column of the table; MariaDB refuses the period. |
SS-PER-002 | Error | A table declares more than one period; MariaDB allows one application-time period per table. |
SS-TOK-001 | Error | A {{Token}} reference has no matching definition anywhere in the package. |
SS-TOK-002 | Error | A file contains an unmatched {{ with no closing }}. |
SS-TOK-003 | Warning | A ScriptTokens entry is defined but never referenced anywhere in the package. |
SS-TOK-004 | Error | A <*File*>/<*BinaryFile*>/<*QueryFile*> ScriptTokens entry points at a file that doesn't exist (or can't be read). |
SS-STALE-001 | Error | The committed schema no longer matches what the current domain model would generate — regenerate it. |
SS-STALE-002 | Error | A committed schema file could not be parsed. It is unusable, so any Extensions governance authored in it was not applied this run. |
SS-STALE-003 | Warning | The committed schema was written by a newer SchemaSmith: it holds everything this version generates and more. The finding names what this version does not know. Do not regenerate it with this version — that would remove them; upgrade instead. |
SS-JSON-001 | Error | A package JSON file violates its schema — a misnamed property, a missing required field, a value outside a declared enum, or a violation of a hand-authored Extensions governance fragment. |
SS-FILE-NAME-003 | Warning | A table or declared-object file's on-disk name differs from the canonical <name>[.<VariantName>].json derived from its Name and VariantName. Covers Tables/ and Events/. |
SS-DEP-001 | Warning | A template uses SchemaIdentificationScript, the deprecated alias for DatabaseIdentificationScript. Rename the key; the value is unchanged. |
A table's identity lives in its file content, never its filename, so a misnamed file still deploys correctly — file naming is a lean, not a gate. The canonical name keeps a table's conditional variants sorted together in source control and makes a file's name a reliable pointer to the table it holds. MariaDB packages carry no per-table schema, so the canonical name has no schema segment.
Type correctness is deliberately left to deployment. DataType is an open-ended field by design — it carries engine user-defined types and platform-specific aliases that are only resolvable against a real, connected engine, so a static linter has no reliable way to tell a genuine typo from a legitimate custom type it's never heard of.
Exit codes: 0 when there are no findings or warnings only, 2 on at least one Error-severity finding (including a load failure). Warnings do not fail the run on their own — they're advisory. To treat warnings as failures, pass --ExitNonZeroOnWarning (or set ExitNonZeroOnWarning to true): a board with warnings and no errors then exits 1.
schemaquench --TestConnection
Opens a connection to the configured server, runs a MariaDB liveness query, and validates that the server meets the product's declared MinimumVersion floor (if one is set). Nothing is deployed. No schema is read, no helper procedures are installed, no migration scripts are touched.
Use this in your pipeline's readiness check before you commit to a full deployment window — catch a bad connection string, a firewall rule that didn't propagate, or a server below your version floor before the quench itself begins.
What it validates:
MinimumVersion floor against the server's detected versionExit codes: 0 on pass, 2 on any connection failure or version violation.
schemaquench --PreviewTargets
Everything --TestConnection does, plus a read-only per-template report of the databases the deployment would target. For each template in scope, the report lists every database work unit that would run — exactly what the full quench would touch, without touching any of it.
This is the right tool before a large fan-out deployment, before onboarding a new environment, or any time you want human eyes on the scope before committing to the run. The preview respects the same Target filters and TemplateTargets overrides a real deployment would use.
What it shows:
Template: TenantWorkspace [required]
db: acme_prod
db: globex_prod (would be created)
Read-only guarantee: the preview never provisions databases and never deploys DDL. A database entry labeled (would be created) means CreateIfMissing: true is configured for that entry in TemplateTargets and the database does not yet exist on the server — the preview reports the intent without acting on it.
RequireAtLeastOneTarget enforcement: if a template has RequireAtLeastOneTarget: true and discovery or filtering produces zero targets, the preview fails with a FAIL result and exit code 2 — the same enforcement that applies at quench time, caught here before any deployment begins. Exit codes: 0 on pass, 2 on any connection failure, version violation, or required-template match failure.
None of the three performs WhatIf analysis (no SQL generation, no schema diff). They lint the package, validate connectivity, and enumerate targets — nothing more. For a preview of the structural changes a quench would make, use WhatIfONLY: true — see WhatIf mode.
Before SchemaQuench can shape your database, it needs its tools in place. KindleTheForge deploys the SchemaSmith infrastructure to each target database. The infrastructure includes the MariaDB helper procedures, the modular table-quench procedures, the reverse-engineering procedures used by SchemaTongs, and the CompletedMigrationScripts tracking table.
KindleTheForge runs on every quench, but the install itself is version-stamped and self-skipping: SchemaSmith records a content-hash stamp of the helper objects in each target database and the call returns immediately when the stamp matches the current tooling — so a normal deployment pays the install cost only when the tooling actually changes. In a normal release pipeline, always leave this true. See ForceReKindle for the override that re-installs unconditionally.
Data-fix and patch deployments turn this off so the run can't alter structure. See Data fixes — the datafix profile for the full flag combination and rationale.
Default false. SchemaSmith records a content-hash stamp of the helper procedures and tables it installs in each target database. On every subsequent run it compares the stamp to the current tooling and skips the re-install when nothing has changed, so a normal deployment pays the helper-install cost only when the tooling actually moves. ForceReKindle overrides that skip and re-installs the helper objects unconditionally — handy after a manual edit to the helpers, when diagnosing a deploy problem, or any time you want a known-good baseline regardless of stamp state.
Set it in SchemaQuench.settings.json, or pass --ForceReKindle on the command line (presence enables it, no value needed). When both are present the CLI switch wins.
Forcing a re-kindle is safe to run concurrently. SchemaSmith serializes the helper re-install per database with a session lock, so parallel deployments don't collide even when every one of them is forcing.
If you can't change the configuration or CLI invocation but still need a re-kindle, dropping the SchemaSmith_KindleStamp marker table has the same effect — the gate sees the missing stamp on the next run and re-installs.
SchemaQuench does its comparing and changing from inside the target: the procedures that read the catalog, work out the difference and run the DDL live in the database they deploy to, beside a handful of tables that remember what was applied. That is what lets a DBA read every statement the tool can issue with the engine's own tools, and it is what a database carries once SchemaSmith has deployed to it. This section is the inventory — where it lives, what each piece holds, when it is installed, and how to take it all out again.
Where it lives. MariaDB has no schema inside a database, so every object sits in the target database itself with a SchemaSmith_ prefix. Nothing is installed outside the databases being deployed to and, because SchemaTongs kindles the same set before it extracts, the databases being extracted from (a read-only source is checked, not written). The admin database (information_schema) only ever runs your product scripts and discovery queries.
The tables. Seven on MariaDB:
| Table | What it holds |
|---|---|
KindleStamp | One row: a hash of the helper scripts as installed. Compared at the start of every quench to decide whether kindling has anything to do. |
CompletedMigrationScripts | The run-once record: one row per migration script that has applied, per product and template. See Migration script tracking. |
ScriptStamp | For each object script that applied, a hash of its text and a hash of the engine's rendering of the object it created, so an unchanged script is not re-run. See Unchanged object scripts. |
ExpressionMap | For each check, generated column or default SchemaSmith applied: the text you declared, the text the engine stored, and the engine version at the time. See Expression change detection. |
ProductOwnership | Which product owns a table, index or event (the template is recorded for a scheduled event and left empty for tables and indexes), and the table's sticky PreventDrop marker. See Table ownership. |
ChangeAudit | A working queue, not a history: each procedure writes a row per object it changed (or, under WhatIf, would change) tagged with its session id, and SchemaQuench reads and deletes its own session's rows at the end of each work unit to build the deployment summary. Rows a session that died left behind are discarded at the start of the next run that reuses its id. |
StatusMessages | The progress lines the procedures write as they go, since a procedure on MariaDB cannot print to the client. SchemaQuench reads them during a step and deletes its session's rows afterwards; anything older than an hour is cleared whenever kindling re-installs the routines. |
On MariaDB the names are SchemaSmith_KindleStamp, SchemaSmith_CompletedMigrationScripts, and so on; the quench steps also create session temporary tables with a _SchemaSmith_ prefix, which exist only for the connection and are dropped as each work unit ends.
The routines. The quench procedures listed under Modular quench procedures, the functions they share, the procedures that generate table and view JSON for SchemaTongs, and the gate functions that tell the table pass what the detected version supports. Kindling runs about a hundred and ten scripts on MariaDB; apart from the ones that create the tables, each creates between one and six routines. On MariaDB sixteen are declared SQL SECURITY DEFINER and run with the rights of the account that kindled them.
When kindling runs. On every work unit, as step 4 of the database quench sequence, after the target's version is detected and the folder gates have run, under a lock per database (GET_LOCK) so parallel work units on one database install once. The stamp is a hash of the scripts exactly as they would be installed, with the session sql_mode folded in, and it is compared with the KindleStamp row. A match returns after one read; anything else re-installs every routine and rewrites the stamp. So whatever changes the installed text re-kindles: a SchemaSmith release whose helper scripts changed, a different sql_mode, and ForceReKindle, which skips the comparison. On MariaDB the text also depends on whether the server has INFORMATION_SCHEMA.CHECK_CONSTRAINTS. MariaDB reads the server version and the unsupported-feature policy at run time: a changed policy never re-kindles there, and a server upgrade does so only through a changed sql_mode or that view. KindleTheForge: false skips the step entirely, as does SkipKindlingForge passed as the first command-line argument; a --WhatIf run kindles like a real one.
Removing it. SchemaSmith's objects are ordinary objects, and dropping them takes nothing of yours with them. Your tables, indexes, scripts and data are untouched; what you lose is the memory of what was applied, so the next deploy re-kindles, runs every migration script again unless you keep the tracking table, and compares expressions by the engine's rendering until it has recorded them again.
Generate the drops from INFORMATION_SCHEMA — the routines and the tables share the prefix — and run the statements it returns. SchemaSmith_CustomTableDrop and SchemaSmith_CustomTableRestore match the pattern too, if you installed them.
SELECT CONCAT('DROP ', ROUTINE_TYPE, ' `', ROUTINE_NAME, '`;')
FROM INFORMATION_SCHEMA.ROUTINES
WHERE ROUTINE_SCHEMA = DATABASE() AND ROUTINE_NAME LIKE 'SchemaSmith\_%'
UNION ALL
SELECT CONCAT('DROP TABLE `', TABLE_NAME, '`;')
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME LIKE 'SchemaSmith\_%';
The deploy machine keeps its own traces: the log directories and the checkpoint files under the checkpoint directory, which a clean run removes for its own targets.
SchemaQuench runs as whatever login the connection string names, and it asks that login to do three different kinds of work: install and read its own helpers, change your tables, and run your scripts. The right grant set follows from which of those a deploy actually does — a full release needs all three, a data fix needs almost none of the first two — so this section says what the run executes on MariaDB and leaves the mapping to your engine's grants to you, where the engine's own documentation is the authority.
What every run does.
information_schema) and runs SELECT @@hostname; the product's ValidationScript, BaselineValidationScript and each template's DatabaseIdentificationScript run there too (an identification script runs in the template's IdentificationDatabase instead, when it names one), and need whatever they read. Each work unit then reads the server version.false, step 4 of the database quench sequence creates or replaces everything listed under What SchemaSmith installs: the procedures and functions, the tables (through BootstrapTableQuench), and the kindle lock (GET_LOCK). The table steps create session temporary tables.On MariaDB, kindling runs DROP and CREATE PROCEDURE and FUNCTION in the target database, CREATE TABLE for the SchemaSmith_* tables and CREATE TEMPORARY TABLE for the working set, so the account needs the right to create routines, tables and temporary tables there. With binary logging on, the server's own rule for who may create a stored function applies (log_bin_trust_function_creators, or the privilege your version substitutes for it). Sixteen of the routines are SQL SECURITY DEFINER, so they keep running with the kindling account's rights after a lower-privilege account takes over the deploys. The table steps run CREATE, ALTER, DROP and RENAME TABLE, CREATE INDEX and ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY in the database; a declared event runs CREATE EVENT and DROP EVENT; and the permission carry-across reads mysql.procs_priv to see a routine's grants before a script drops it — an account that cannot read it is told so and the deploy continues without them.
CreateIfMissing provisions databases and needs the rights that implies; see CreateIfMissing.
WhatIf needs the same. A --WhatIf run kindles, reads and writes SchemaSmith's own tables and runs every procedure in preview mode, which writes ChangeAudit and StatusMessages. Only your objects are left unchanged; under a reader account a preview fails at kindling whenever the helpers need installing or refreshing.
The reduced profile. A deploy with KindleTheForge, UpdateTables, DropTablesRemovedFromProduct and TrackRunOnceMigrations off runs only your scripts and the reads above; Data fixes — scoped deployment account gives a grant set for it. With TrackRunOnceMigrations on, add SELECT, INSERT and DELETE on CompletedMigrationScripts; a deploy that also runs object scripts writes ScriptStamp, and an account that cannot is told once and continues.
Every engine rewrites an expression when it stores it. Comparing what you wrote against what the catalog reports therefore never matches for anything non-trivial — so a check constraint or generated column could be re-applied on every deploy, at exit 0, with nothing in the log to say why.
SchemaSmith answers the question from what it applied instead of from the text. A table it owns, SchemaSmith_ExpressionMap, records for each expression: the text your package declared, the text the engine reported back immediately afterwards, and the engine version in force at the time. On the next deploy:
| What moved | What SchemaSmith does |
|---|---|
| Nothing | Leaves the object alone, however differently the two texts read. |
| Your declaration | Applies it. |
| The live object (someone edited it by hand) | Re-applies your declaration. Drift is still corrected — this is not a one-sided comparison that trusts the package and stops looking at the server. |
| The engine version | Re-baselines: re-reads the live text and updates its record, without touching the object. |
An expression SchemaSmith has not applied is checked by the engine itself. A database built by hand or by another tool, or a declaration you reworded, has no record yet. Rather than re-apply every such expression whose text differs, SchemaQuench applies your declared text to an empty copy of the table, reads back what the engine stored, and compares that with the live object byte for byte. Identical means the live object is your declaration: it is recorded and left alone, and the log says how many were verified this way. Anything else — a different rendering, or an expression the copy could not take — is applied, as it would have been. The copy lives in the same database (so it can call its functions); on MariaDB it is a real table for a moment, so WhatIf skips the check and previews such an expression as a change. Nothing needs migrating, and the table can be emptied at any time: the worst case is one more check.
A re-baseline is logged, not silent. The deploy log says how many records were refreshed and for which version — Re-baselined 3 recorded expression(s) ... No object was changed. — so an engine upgrade is visible in the first deploy after it.
Covered surfaces: check constraints, generated columns and expression defaults.
The table quench is broken into modular stored procedures, each handling a specific aspect of the table schema. The procedures are deployed during the KindleTheForge step and called in sequence during the database quench. The core procedures are the same on every engine; MariaDB adds the ones its own features need.
Core procedures:
| Procedure | Responsibility |
|---|---|
| TableQuench | The wrapper that runs the whole table sequence below in one call — what a migration script calls to bootstrap a table. SchemaQuench itself calls the pieces, so it can run scripts between them. |
| BootstrapTableQuench | A minimal create-or-rename-or-add-columns procedure with no dependency on the other helpers; it installs SchemaSmith's own tables during kindling. |
| MissingTableAndColumnQuench | Renames tables and columns declared with OldName, creates tables that exist in the schema package but not in the database, and adds missing columns. |
| ModifiedTableQuench | Drops tables removed from the product, elects rebuilds, drops modified or removed indexes, foreign keys and check constraints, alters existing columns (type, nullability, default, generated), drops removed columns and converges table attributes. See Column changes. |
| MissingIndexesAndConstraintsQuench | Adds generated columns, and creates the indexes, check constraints, defaults and full-text indexes the package declares and the database lacks. |
| ForeignKeyQuench | Creates, modifies and drops foreign keys to match the schema package. Runs late in the sequence so all referenced tables, columns and data exist. |
| IndexOnlyQuench | Alternative to the full sequence. Manages indexes only — doesn't create tables, add columns, or manage foreign keys. Used when IndexOnlyTableQuenches is enabled on a template. |
MariaDB procedures:
| Procedure | Responsibility |
|---|---|
| EventQuench | Declared scheduled events: created, dropped and re-created on change, dropped by absence under DropEventsRemovedFromProduct. |
| SequenceQuench | Declared sequences on MariaDB 10.3 and later, every attribute converged in place and the current value never touched. |
The implementation lives in the deployed SQL on the target database — which means a DBA can read it on the server with SHOW CREATE PROCEDURE. No black boxes.
The quench procedures are deployed to the target database during the KindleTheForge step and remain there afterward. You can call them directly from Before Scripts, After Scripts, or any migration script to bootstrap specific tables as part of a data migration.
The typical pattern uses specific-object tokens to quench individual objects that your migration script depends on, rather than passing the entire schema. First, define a token in your Product.json or Template.json:
{
"ScriptTokens": {
"AuditLogTable": "<*SpecificTable*>AuditLog"
}
}
TableQuench — ensures a specific table exists with the right structure before your migration script runs. On MariaDB the procedure is SchemaSmith_TableQuench and takes a positional DatabaseName parameter (the database the migration is running against):
-- Bootstrap the AuditLog table so we can insert into it during this migration
CALL SchemaSmith_TableQuench(
'{{ProductName}}',
DATABASE(), -- p_DatabaseName: the target database
'[{{AuditLogTable}}]',
0, -- p_WhatIf
0, -- p_DropUnknownIndexes
0 -- p_DropTablesRemovedFromProduct
);
You can also pass the full schema token ({{TableSchema}}) to quench all tables, but the specific-object pattern is more common in migration scripts where you need one table to exist before proceeding.
TableQuench parameters. The parameters, in declared order. MariaDB has no parameter defaults: the six positional arguments are the whole signature.
| Parameter | Default |
|---|---|
| ProductName | Required |
| DatabaseName | Required (second) |
| TableDefinitions (JSON) | Required |
| WhatIf | Required |
| DropUnknownIndexes | Required |
| DropTablesRemovedFromProduct | Required |
| RebuildPolicyMode | session variable |
| RebuildPolicyThreshold | session variable |
| RebuildPolicyOnOrderMismatch | session variable |
| OnlineApply | session variable |
The by-absence drops of columns, foreign keys, check constraints and product-owned indexes are not parameters of the wrapper: it passes them on. The rebuild policy and OnlineApply reach the procedures through session variables SchemaQuench sets before its own calls (@ss_rebuild_policy_mode, @ss_rebuild_policy_threshold, @ss_rebuild_policy_on_order_mismatch, @ss_online_apply); a direct call that sets none gets NEVER, which can never elect a rebuild.
When to use direct calls: when a migration script needs a table to exist before it can run — for example, bootstrapping an audit table in a Before Script before inserting migration tracking data.
SchemaQuench remembers what it has already run, so you never have to worry about a migration script executing twice. Migration scripts (scripts in the Before, BetweenTablesAndKeys, AfterTablesScripts, and After slots) are tracked in the SchemaSmith_CompletedMigrationScripts table:
| Column | Description |
|---|---|
Id | Auto-increment primary key. |
ProductName | The product name from Product.json. |
QuenchSlot | The slot the script belongs to. |
ScriptPath | The relative path of the script within the template. |
template_name | The template the script ran under. |
schema_name | Always empty — schema templates do not apply on MariaDB. |
QuenchDate | Timestamp when the script was executed. Before 2.5 it was named CompletedAt; the next deploy renames it, keeping its values. |
Those five identity columns — ProductName, QuenchSlot, ScriptPath, template_name and schema_name — are what make a tracking row unique, so the same script is recorded separately per template. MariaDB carries an auto-increment Id primary key and enforces the same five columns as a unique index, with prefix lengths on the three longest.
Scripts with [ALWAYS] in the filename (before the .sql extension) run on every quench regardless of tracking:
001_SeedReferenceData [ALWAYS].sql
002_RefreshPermissions [ALWAYS].sql
[ALWAYS] scripts are never recorded in the tracking table.
Migration scripts within each slot execute in alphabetical order by filename. Use numeric prefixes to control execution order:
001_CreateStagingTable.sql
002_MigrateData.sql
003_DropStagingTable.sql
When SchemaQuench processes a slot, it compares the tracking table entries against the scripts currently present in the package. Entries for scripts that no longer exist in the package are automatically removed.
To force a tracked script to run again, either delete the corresponding row from SchemaSmith_CompletedMigrationScripts in the target database, or rename the script file (tracking is by path, so a renamed script is treated as new).
The run-once record is only as good as the deploy login's access to it, so SchemaQuench treats a problem with the table as a reason to stop rather than a reason to guess:
SELECT on the table, stops the run before the slot: Cannot read which Before scripts have already run from SchemaSmith_CompletedMigrationScripts. Nothing in the slot was run, because a run-once script would run again.The script applied, but could not be recorded as run, so the next deploy would run it again — and the run fails, so the problem is fixed before a second deploy repeats the script. A duplicate row is not an error.The grants that satisfy both are SELECT, INSERT and DELETE on the tracking table; for a least-privilege deploy account, see Data fixes — scoped deployment account.
You shouldn't have to name your files in dependency order just so they deploy correctly. Scripts in the Objects, AfterTablesObjects, and TableData slots execute using a dependency retry loop rather than simple sequential execution:
On the final attempt (the last pass when errors are reported), failures are logged as errors and the quench fails.
This mechanism allows scripts with interdependencies to coexist in the same folder without requiring a specific naming order. For example, if View B references View A and is alphabetically first, it will fail on the first pass but succeed on the retry after View A has been created.
A script that is unchanged since it last applied is not part of the loop at all — see Unchanged object scripts.
Each pass is itself a retry loop, and the passes are placed so a script can wait for the tables it needs: the Objects slot runs before the table quench and again once missing tables and columns exist, and the AfterTablesObjects slot runs after table modifications and again after the AfterTablesScripts slot. Only that last pass reports what still fails as an error. This handles cases where a view or function references a table column that doesn't yet exist on the first pass. See the database quench sequence for where each pass sits.
Most of a package does not change between two deployments, yet every view, function, procedure and trigger script used to run again on every quench. Each run was harmless on paper, but it still rewrote the object and, on MariaDB, where a module is a DROP and a CREATE, briefly removed it. SchemaQuench now records what each object script left behind and runs it again only when something has moved.
What is recorded. After an Objects or AfterTablesObjects script applies, SchemaQuench stores two hashes in the SchemaSmith_ScriptStamp table on the target database, keyed by product, template and the script's path within the package: a hash of the script text, and a hash of the engine's own rendering of the object the script created (SHOW CREATE, with a module's sql_mode included where the engine keeps them apart). A script is stamped only when it comes from a folder declared with an ObjectType and contains exactly one CREATE of a view, function, procedure, trigger or event, so the rendering is of the object it declares; any other script runs every time, as before.
When a script runs again. On the next quench the script is skipped only when both hashes still match: the text is as it was, and the server still renders the object as the last run left it. Edit the script and it runs. Change the object by hand on the server — an ALTER, a dropped and recreated view — and the rendering no longer matches, so the script runs and puts the declared definition back. Drop the object and it runs. A skipped script is logged as Unchanged, not re-run, recorded as unchanged in the change audit, and counted as Unchanged (object scripts) in the deployment summary, separately from the scripts that ran.
What is never skipped. A script with [ALWAYS] in its name runs on every quench, as it always has, and so does a script carrying a -- SchemaSmith: AlwaysRun comment anywhere in its text — the opt-out for a script with side effects whose object may well be unchanged. A script from a folder declared without an ObjectType (a custom folder) is never stamped. RunScriptsTwice runs every script twice, as before: it exists to prove scripts re-run cleanly, which a skipped script cannot. A script is stamped only when it creates exactly one view, function, procedure, trigger or event; a CREATE inside a comment or a string literal does not count, so a header comment showing how to schedule a procedure is harmless. Scripts in the sequential slots (Before, BetweenTablesAndKeys, AfterTablesScripts, After) are migration scripts and keep their own run-once tracking. A WhatIf run reads the stamps and reports a script it would skip as SKIP (unchanged), but records nothing; a script that uses query tokens is always previewed as would-apply, because WhatIf does not resolve the tokens and so cannot compare the text. Set Target:SkipUnchangedObjects to false to run every object script on every deployment; while it is off nothing is stamped, so the first deploy after turning it back on runs everything once. A stamp that cannot be written — a login without rights on the table — is logged once and the deploy continues; the scripts simply run again next time.
The rendering is compared only with the engine's own earlier rendering of the same object, never with the script text, so an engine that reformats a body, expands a * or re-quotes identifiers does not cause a re-run. Only a rendering that differs from the one recorded after the script last applied does.
Some changes can only be made by replacing an object. MariaDB keys a table's grants by name, so a rebuilt table keeps them without help; only a routine's grants are lost by a DROP, and only those are captured. The replacement is built from the package, and the package does not declare a routine's grants — so they used to be gone after the deploy, with a successful exit code.
What is carried. Before the drop SchemaQuench captures what sits on the object and is not in the package, and puts it back once the replacement exists: the grants on a procedure or function.
Where it applies. Around any object script that drops its own procedure, function or view before creating it — the DROP PROCEDURE IF EXISTS ... CREATE PROCEDURE form that MariaDB requires. A script that alters in place (CREATE OR REPLACE) loses nothing and needs nothing.
What you see. The log names the object as its permissions are put back, and the run manifest records a reapplied row for it. Under WhatIf the statements are printed and the manifest records wouldReapply instead.
Limits. A MariaDB deploy user that cannot read mysql.procs_priv cannot see a routine's grants; the run says so and the deploy continues without them.
Changing a column that already holds data is where a declarative deploy earns its keep. Some changes the engine makes in place; some SchemaQuench can only make by replacing the column or the table; a few it refuses, because the only way through would lose something it cannot put back. The table below says which path each change takes and what comes down and goes back up around it. A rebuild of the whole table is a separate decision, off by default, documented under RebuildPolicy; the online forms of these statements are under OnlineApply.
| Change | Path | Taken down and put back |
|---|---|---|
Type, character set, collation, nullability, default, comment, ON UPDATE, invisibility, SRID | In place: ALTER TABLE … MODIFY COLUMN, one statement per table. Invisibility needs MariaDB 10.3, and MariaDB has no SRID attribute at any version; where the engine lacks one, it is left off and reported through the unsupported-feature policy | For a type, character-set or collation change, the foreign keys on the column and the ones pointing at it are dropped first and created again by the foreign-key pass — except a widening the engine makes with the key in place (a VARCHAR or VARBINARY made longer on the same side of 255 bytes), which MariaDB makes only before the releases that refuse any change to a key column (MDEV-31086). On the MariaDB versions affected by MDEV-35630, a type change on a column that follows a STORED generated column takes every foreign key on the table down and back. |
Generated column added, removed or switched between VIRTUAL and STORED | Drop and re-add the column | The column comes back last in column order. A column that stops being generated comes back without its values. |
Renamed (OldName) | RENAME COLUMN on MariaDB 10.5.2 and later, CHANGE COLUMN below it, before any other change | MariaDB carries a generated column that reads the column across the rename itself. |
| Removed from the package | Dropped under DropColumnsRemovedFromProduct | Foreign keys that reference it first. |
| Column order | A rebuild; or, when OnOrderMismatch asks for one and OnlineApply is on, MODIFY COLUMN … AFTER in place instead — except a table with a generated column, which is still rebuilt, and a system-versioned table, which is not moved in place either and whose rebuild is refused (next column), so the deploy stops | A rebuild is refused for a partitioned table, one whose table or column rename has not landed yet, a system-versioned table, and one with an application-time period (seen from MariaDB 11.4, where the catalog first reports periods). |
On a system-versioned MariaDB table, MariaDB itself refuses a column change (error 4119) unless SystemVersioningAlterHistory is KEEP, which lets the change through and rewrites the stored history to match.
A type, character-set or collation change under a foreign key the package does not declare — another product's, or one made by hand — which would be dropped and never put back; a DataDirectory move, which the engine cannot do in place; and the removal of IsSystemVersioned, because DROP SYSTEM VERSIONING would purge the table's row history. Each names the object. The foreign-key refusal fires before any key is dropped; it runs only on a live deploy, so WhatIf does not show it. The DataDirectory and IsSystemVersioned refusals fire under WhatIf too; the IsSystemVersioned one fires after the run's column changes, which a live deploy has already made by then. Earlier steps of the same run may already have applied, such as table and column renames and new tables and columns.
Changing an index or a column on a table in use takes locks while the change runs, and on a large table that can be long enough to stall the application. Engines have lower-lock forms of many of these statements. OnlineApply lets a deploy use them, per environment, with a per-table override.
| Scope | Where to set | Default |
|---|---|---|
| Environment | OnlineApply in SchemaQuench.settings.json (or the SmithySettings_OnlineApply environment variable, or --OnlineApply=Prefer on the command line) | Off |
| Table | OnlineApply in the table's .json | inherits the environment |
| Value | Effect |
|---|---|
Off (default) | The plain statements, exactly as a deploy has always run them. |
Prefer | The online form wherever the engine's version allows it, and the plain form otherwise. |
Require | The online form for each change the table below lists, or the deploy is refused, naming each statement that could not run online. MariaDB cannot take DDL back, so it stops the deploy at that statement. A change the table does not list runs as written, under Require too. |
It is off by default because each online form costs something you did not ask for. Those are deployment-window decisions, so you opt in per environment.
The deployment summary says which form each change used: mode is online, instant or unavailable (the plain form, where the online one could not be used). A change has no mode when OnlineApply is Off, and the progress log says the same thing, with the reason for an offline one.
A table this deploy creates is empty, so its indexes are built the plain way whatever OnlineApply says.
SchemaQuench asks the engine for the lightest form and lets it decide. Each statement below is sent with ALGORITHM=INSTANT where that can apply (MariaDB 10.3 and later), then with ALGORITHM=INPLACE, LOCK=NONE, then on MariaDB 11.2 and later with ALGORITHM=COPY, LOCK=NONE (a copy that does not block writes), and a form the engine refuses moves on to the next. Under Prefer the last step is the statement as written, recorded as unavailable with the engine's reason; under Require the deploy stops at that statement, naming it.
| Change on an existing table | Forms asked for |
|---|---|
| A column added | INSTANT, then INPLACE, LOCK=NONE; the column goes AFTER the declared column before it |
| A column the package no longer declares | dropped INSTANT, then INPLACE, LOCK=NONE |
| A column whose definition changes | INSTANT, then INPLACE, LOCK=NONE (a VARCHAR widened within its length class is instant on MariaDB; a type change needs the MariaDB 11.2 copy) |
| A new index, or one built again because it changed, and an index dropped | INPLACE, LOCK=NONE |
A table whose RebuildPolicy sets OnOrderMismatch, rebuilt only because its columns are out of order | its columns are moved into order in one statement (MODIFY COLUMN … AFTER), instant on MariaDB 10.4 and later, instead of the rebuild. A table with a generated column is still rebuilt; a system-versioned table is not moved in place either, and the rebuild it would need is refused, so the deploy stops |
The deployment summary records instant, online (INPLACE, LOCK=NONE) or unavailable. Under WhatIf the preview shows each statement with its position and the forms it would ask for, and the preview's changes carry no mode: only the engine can say which form it accepts.
Under Off a new column is added at the end of the table, as it always has been. Under Prefer or Require it goes where the package declares it, so the table needs no rebuild to put its columns in order. MariaDB adds a column instantly anywhere from 10.4 (10.3 only at the end); elsewhere the add runs INPLACE, LOCK=NONE.
The engine refuses both forms for some changes, and they run as written under Prefer: a column added to a table that has a full-text index, for example.
MariaDB does not roll DDL back, so a Require refusal stops the deploy at that statement, with the changes before it in place. Full-text indexes, keys and foreign keys run as before, outside OnlineApply; on MariaDB 10.4 and later, a full-text index added to a table that already has rows is built by copying the table, which blocks writes while it runs.
Dropping by absence is only safe if SchemaQuench knows which tables are its to drop. A database holds tables from more than one product, tables a DBA made by hand and tables another tool manages, and “not in this package” describes all of them. So SchemaSmith marks what it deploys, and every by-absence drop, and every refusal to touch someone else's table, reads that mark. This is the model behind DropTablesRemovedFromProduct, DropIndexesRemovedFromProduct, DropUnknownIndexes and PreventDrop.
Becoming owned. On the first deploy that finds a declared table physically present, SchemaQuench marks it with the product's name, as a row in SchemaSmith_ProductOwnership naming the product, the database and the object, with its template column left empty. The mark is written during the table work of that run, after the table exists, and refreshed on every run while the table is in the package; the sticky PreventDrop marker lives beside it. Indexes are marked the same way, and by declaration rather than by who built them: every index the package declares carries the mark once it exists, whether this run created it or found it already in place. An index on a declared table that the package does not declare, and that carries no mark, is unknown.
Another owner's table. Before the table step creates or renames anything, it reads the owner of every table the package declares — under its new name, or under its OldName when the rename has not happened yet — and refuses the deploy if any owner is a different product. The refusal names one conflicting table: Table orders is already owned by another product: Billing. The refusal fires under --WhatIf too, and because it runs before the missing-table step, the table step of a refused deploy has renamed, added and dropped nothing. Steps that run ahead of it, such as Setup scripts and object scripts, have already run on a live deploy. To hand a table from one product to another, change its mark on purpose — the ownership row — with a migration script.
What reads the mark.
| Control | What it looks at |
|---|---|
DropTablesRemovedFromProduct | A table this product owns that the package no longer declares. A table owned by another product, or by nobody, is never a candidate. |
DropIndexesRemovedFromProduct | An index this product owns, on a declared table, that the package no longer declares. |
DropUnknownIndexes | An index on a declared table that the package does not declare and that this product does not own — one made by hand or by another tool. Off by default, because nothing in the package could put it back. |
PreventDrop | The marker stored with the ownership mark, read even after the table has left the package. |
ShouldApplyExpression | A gate that is false makes an owned object “not declared”, and the controls above treat it as removed. See A gate that turns off an existing object. |
Ownership is reconciled against the live catalog each run: a mark whose table is gone is pruned. Tables and indexes are dropped by absence per product and database, not per template; a scheduled event's row records its template, but its drop by absence is scoped the same way.
When DropTablesRemovedFromProduct is true (the default), ModifiedTableQuench drops tables that:
This keeps the database clean as tables are removed from the schema package over time.
The setting resolves across three tiers — environment → product → template — evaluated from broadest to narrowest:
DropTablesRemovedFromProduct in SchemaQuench.settings.json (or the SmithySettings_DropTablesRemovedFromProduct environment variable). Controls all products deployed in that environment.DropTablesRemovedFromProduct in Product.json. Controls a single product regardless of environment.DropTablesRemovedFromProduct in Template.json. Controls a single template within a product.Explicit false is sticky. A false set at any tier locks the effective value to false for all lower tiers — a true below can never override an ancestor's false. Absent means inherit. So an environment (or product) that sets false is a hard guardrail that suppresses the drop pass regardless of what any lower tier declares. Unlike the per-type flags, DropTablesRemovedFromProduct has no table tier — see Per-type drop protection.
| Environment | Setting | Rationale |
|---|---|---|
| CI and local dev | true | Catch product areas that reference tables you plan to remove. |
| Test/staging | true | Same rationale, but verify the drop is intentional before promoting to production. |
| Production | Often false | Dropping a table is a hard drop with no built-in recovery. Teams that need rollback-friendly deployments should leave this off in production. |
DropTablesRemovedFromProduct: false in the production config.For an alternative that keeps auto-drops on while still protecting data, see Recyclebin — soft-drop and restore hooks (drop-but-recoverable via the SchemaSmith_CustomTableDrop / SchemaSmith_CustomTableRestore hooks).
The run fails instead. A partitioned table holds data spread across every partition, and no declaration can tell SchemaSmith that data is disposable. So a guard inspects each table selected for drop-by-absence and, on finding it partitioned, refuses to drop it and fails the run closed (exit code 2) rather than proceeding. This applies however the table came to be partitioned — one a DBA partitioned by hand and one SchemaSmith itself deployed from a declared Partitioning block are equally protected. The failure names the table and tells you to drop it manually or mark it PreventDrop:
Partitioned table(s) skipped by drop-by-absence guard; drop manually or mark PreventDrop.
Partitioned table removed from product, not dropped (data-loss guard): <table>
Partition detection reads INFORMATION_SCHEMA.PARTITIONS.
This is a safety net for the case where a partitioned table was never marked, not the primary mechanism. PreventDrop takes precedence and remains the intended way to protect a table from drop-by-absence: a table marked PreventDrop never reaches the guard at all — the drop is skipped, the run succeeds, and the skip is recorded as Table <name> removed from product but PreventDrop is set — skipping drop (protected).
The Drop…RemovedFromProduct flags gate the by-absence drop pass, so they only see a table whose definition is still present. Delete a table's .json and there is nothing left to carry a false — the table becomes a drop candidate. PreventDrop closes that gap: set it on a table and SchemaSmith persists the intent in the database itself, so the protection outlives the table's own definition.
It is a per-table boolean, default false. When true, the table is never dropped by absence — even after you remove it from the package entirely.
{
"Name": "`Orders`",
"PreventDrop": true,
"Columns": [ /* ... */ ]
}
The protection is persisted in SchemaSmith's ownership tracking, so it survives the table leaving the package. On MariaDB it is a PreventDrop column on the ProductOwnership tracking table. Each run, while the table is still in the package, SchemaSmith refreshes the marker to match the package value — so the stored protection always tracks what your JSON declares.
When a protected table is later removed from the package, SchemaSmith reads the persisted marker, logs that it is retaining the table, and skips the drop. Its inbound foreign keys — constraints on other tables that reference the protected table — are preserved too, so the table stays fully wired into the schema rather than left as an orphan.
Unlike DropTablesRemovedFromProduct (an environment → product → template cascade that suppresses the drop pass), PreventDrop is a positive, per-table guard that lives with the table and persists in the database. The cascade flag answers “should this deployment run the drop pass at all?”; PreventDrop answers “should this specific table ever be a drop candidate?” — and keeps answering it after the definition is gone.
Because the marker is sticky, clearing it is a deliberate, reviewed step — you cannot un-protect a table by deleting its JSON, since that is exactly the case the stickiness defends against. Two ways:
PreventDrop: false and re-deploy while the table is still in the package. That run refreshes the sticky marker to false. Remove the table on a later deployment and it drops normally.PreventDrop at all.If a protected table is dropped out-of-band — by a migration script, a DBA, or a manual change — SchemaSmith prunes its ownership record, including the sticky marker, because the table no longer exists in the catalog. No stale protection lingers to confuse a future deployment; the marker only ever protects a table that is actually there.
Per-table PreventDrop protects tables one at a time. The environment-level setting is the blanket: an entire target where the deployment tool is simply not allowed to remove anything by omission — production, a shared staging fleet, anywhere an accidental drop is unacceptable.
Set PreventDrop: true in SchemaQuench.settings.json (or the SmithySettings_PreventDrop environment variable) and, for the whole run, SchemaQuench suppresses every drop-by-absence pass — tables, columns, foreign keys, check constraints, product-owned indexes, unknown out-of-band indexes and scheduled events — and none of those passes drops anything for being absent from the product, regardless of what any package, template, or table declares. Off by default.
{
"PreventDrop": true
}
It doesn't drop — it doesn't explode. A protected run still completes normally (exit code 0). SchemaQuench applies every additive and modifying change as usual, skips the drops, and logs each table, column, foreign-key, constraint and index drop it withheld, recording them in the deployment summary under a preventDrop manifest — a precise list of what was not removed (objectType + objectName) without the run failing. The scheduled-event drop pass is simply off under protection, so an event is not listed.
Transient drops are untouched. Protection suppresses only removal by absence. An object that is still declared but has to be dropped and recreated to apply a change — modifying an index or a constraint, for example — reconciles exactly as it always does.
Beyond whole tables, SchemaQuench reconciles individual object types removed from a table's JSON — columns, foreign keys, check constraints, and indexes. Each has its own Drop…RemovedFromProduct flag, all default true, and each gates only removal by absence: an object whose definition merely changed is always dropped and recreated so the new definition takes effect. The callouts below cover the flags that sit outside this shape.
Four-tier cascade — environment → product → template → table. The per-type flags add a fourth, table-level tier that DropTablesRemovedFromProduct does not have: a table's own .json can tighten a flag to false to protect its objects even when higher tiers permit drops — but it can only tighten, never re-enable. Explicit false stays sticky at every tier. For the full cascade across every drop-control flag, see Drop control.
Default true — columns absent from the schema package are dropped, keeping the deployed table in sync with the product definition. Set it false when the drop is unsafe: a production column other systems still read, a column you want to retire gradually with a migration script, or any environment where you want human review before structural column removal. Before this flag existed, the only way to suppress column-drop-by-absence was UpdateTables: false, which also blocks column additions and type changes; this is the narrower knob.
Default true — foreign keys absent from the schema package are dropped. Set it false to preserve an out-of-band constraint or require review before removal. Only by-absence removal is gated: a modified foreign key — one whose name still appears in the product but whose columns, referenced table/columns, or ON DELETE / ON UPDATE action changed — is always dropped and recreated regardless of this flag. On MariaDB, foreign-key cleanup is governed by this flag alone; it does not depend on DropUnknownIndexes.
Default true. Governs table-level CHECK constraints — the CheckConstraints array. A column-level check, driven by a column's CheckExpression, is reconciled by the column passes, not this flag. Only by-absence removal is gated; a check whose expression merely changed is always dropped and recreated.
Default true — a product-owned index (one SchemaSmith created and tracks) that dropped out of the definition is removed. Applies to secondary indexes SchemaSmith manages; a primary key is never dropped by this path. This is distinct from DropUnknownIndexes below.
DropUnknownIndexes defaults to false, unlike the per-object-type flags above. Where DropIndexesRemovedFromProduct targets indexes SchemaSmith owns, DropUnknownIndexes targets out-of-band indexes SchemaSmith never created. It defaults off because most teams adopting SchemaSmith inherit environments with years of index drift — turn it on only after every index you need is captured in your repository. See Drop control for its full cascade and adoption guidance.
DropEventsRemovedFromProduct controls whether SchemaQuench removes a scheduled event — a job the database runs on a schedule — that exists on the server but no longer appears in your package. This is an environment-level setting only, configured in SchemaQuench.settings.json or via the SmithySettings_DropEventsRemovedFromProduct environment variable; events live in a template's Events/ folder rather than under a table, so there is no per-table level for the setting to cascade to. It defaults to off because a package that contains no events is not necessarily asserting the database should have none — it may predate the point where you began declaring events in your repository. SchemaQuench removes only events it created; hand-written events, or those loaded from a .sql script in the same folder, are never touched. For the declared event format see Declared objects.
DropPeriodsRemovedFromProduct controls whether SchemaQuench removes an application-time period — a pair of columns that define the interval a row is valid for, such as the dates a price applied — that exists on a table but no longer appears in your package. It resolves at the environment level and can be overridden per table by setting it in that table's .json file. It defaults to off because a package with no periods declared is not necessarily asserting that tables should have none: packages written before periods could be declared have no such entry, and neither does one extracted from a MariaDB catalog that cannot report periods yet. Dropping a period is not destructive to row data — the columns remain with all their contents intact, and only the period definition and the check constraint enforcing it are removed.
When RunScriptsTwice is true, the Objects-slot scripts are executed twice in succession during step 7 of the database quench sequence. On the second pass, all scripts are reset to unquenched and processed through the dependency retry loop again. Both runs must succeed — if either fails, the deployment fails.
This is an idempotency testing tool, not a dependency resolution mechanism. Dependency resolution is already handled by the retry loop, which retries failed scripts as long as progress is being made. RunScriptsTwice answers a different question: "Can my [ALWAYS] scripts and object scripts run again safely?"
[ALWAYS] scripts are truly idempotent. If a script fails on the second run, you have caught an idempotency bug before it reaches production.[ALWAYS] scripts.When TrackRunOnceMigrations is false, SchemaQuench treats all migration scripts as if they had the [ALWAYS] suffix — no script is recorded in CompletedMigrationScripts, no script is skipped based on prior runs. Every migration script in every slot runs on every deployment.
When tracking is off, PruneObsoleteMigrationTracking is forced off regardless of its configured value.
For how this flag fits partial-package deployments, see Data fixes — the datafix profile.
When PruneObsoleteMigrationTracking is true (the default), SchemaQuench removes entries from CompletedMigrationScripts for scripts that no longer exist in the current package. This is correct for full release deployments where the package represents the complete truth.
When false, existing tracking entries are left alone regardless of what scripts are in the current package. This setting is ignored when TrackRunOnceMigrations is false (no tracking means no pruning). For how this flag fits partial-package deployments, see Data fixes — the datafix profile.
When Target:Templates or Target:Databases is set, prune is restricted to the iterations that ran in that deployment. A prune pass only examines tracking rows that match the active (template, database) scope for each executed iteration — it does not touch rows belonging to templates or databases the filter excluded.
This is correctness-critical, not a limitation. Without it, a deployment scoped to tenant_newco would delete tracking rows for tenant_acme, tenant_beta, and every other database excluded from the run — rows that are correct records of migrations already applied against scopes you explicitly chose not to touch. The boundary of the prune exactly matches the Target filter.
ShouldApplyExpression is a SchemaQuench feature that lives on the schema package side. Whenever SchemaQuench evaluates a table component that has a ShouldApplyExpression set, it resolves any tokens in the expression, runs the expression against the target database, and when the result is false leaves the component out of this deploy: one that does not exist is not created, and one that already exists is dropped (see A gate that turns off an existing object below). A predicate that evaluates to NULL counts as true, so the component deploys. This means a single table file can declare components that only apply on certain databases, certain environments, or certain server versions — no per-environment file copies, no branching logic in your deployment pipeline. See Conditional application for the JSON shape and worked examples, and Custom Properties as drivers for how to drive ShouldApplyExpression values from team-defined metadata.
The same primitive works one level up: a script folder can carry a ShouldApplyExpression too. Put it on any product- or template-level folder definition (alongside ServerToQuench / QuenchSlot). Blank deploys the folder as always; a non-blank expression is evaluated against the target and the folder's scripts deploy only when it returns true — false skips the entire folder (and its sub-folders), logged so you can see why.
A folder expression runs as a query against the target: write a bare predicate and SchemaQuench wraps it, or a SELECT that returns a number or boolean — 0, NULL or no row is false, any other number is true, and a string such as 'false' fails the deploy. For example, SELECT {{ServerMajorVersion}} >= 1006 deploys a folder only to MariaDB 10.6 and later targets. It can read @@version, call an environment-type function your team already has, query a control table, or reference resolved tokens — template-folder gates get the script tokens, {{ServerMajorVersion}} and {{CompatibilityLevel}}; product-folder gates get a narrower set, below. No folder gate gets a query token. Product folders are evaluated per server; template folders are evaluated per database, so the same folder can deploy to one target and be skipped on another in a single run.
A product-folder expression runs against the server's admin connection (information_schema), because product-level scripts are server-scoped — no database is selected yet. Use server-scoped predicates there (server properties, version, edition). Of the resolved tokens, only {{ServerMajorVersion}} is available at this scope (the server connection already exists); {{CompatibilityLevel}} is not, and referencing it reaches the server as literal, unresolved text and fails the deployment rather than silently evaluating to the wrong thing. A template-folder expression runs against the actual target database, so it can also query target-database state and use {{CompatibilityLevel}} — though, like every folder gate, not a query token.
A folder's ShouldApplyExpression must return a number or boolean (or be a bare predicate). If it errors — a SQL mistake, a missing function — the deployment fails with a clear message naming the folder, rather than silently skipping it. A gate that quietly dropped schema folders would be the dangerous failure mode, so the engine fails closed.
The most common gate is “apply this only on a new enough target.” The {{ServerMajorVersion}} and {{CompatibilityLevel}} script tokens expose the version SchemaSmith already detects, so you write one portable integer comparison instead of each engine's native version SQL. On MariaDB, {{CompatibilityLevel}} resolves to the same value as {{ServerMajorVersion}}.
// A folder that uses a server-version-only capability. Gate on the binary.
"ShouldApplyExpression": "{{ServerMajorVersion}} >= 1006"
The tokens resolve per target database. See Script tokens — gate syntax on compatibility level, gate features on server version for the cross-engine {{CompatibilityLevel}} fallback.
On a product folder, only {{ServerMajorVersion}} is available — there's no database selected yet at that scope, so {{CompatibilityLevel}} doesn't resolve.
Every gate is evaluated against a live connection, but not at the same moment or against the same thing. Knowing which is which tells you what a predicate can see.
| Gate | When | Against |
|---|---|---|
A table, column, index, foreign key or check constraint (ShouldApplyExpression in the table JSON) | At the start of the table work for each database, as the table JSON is parsed into the working set. Script and custom-property tokens in the expression were resolved when the package loaded; {{ServerMajorVersion}} and {{CompatibilityLevel}} are substituted for the target before the parse. | The target database. A row whose predicate is false is deleted from the working set before anything is compared. |
| A template folder | Once per database, after the version is detected and before any slot runs. | The target database. Script tokens were resolved when the package loaded; the version tokens are resolved for the target. |
| A product folder | On each server it runs on: a Before folder before the Before scripts, an After folder at the After Product step. | The server's admin connection. Script tokens were resolved when the package loaded; {{ServerMajorVersion}} is the only token resolved for the server. |
A DataDelivery block | Once per database, at the delivery step, before any content file is read. | The target database. See Gated deliveries and variants. |
| A sequence | Inside the procedure that deploys it, per target. | The target database. |
A folder gate is run as a scalar query: write it as a SELECT that returns a number or boolean, or as a bare predicate, which SchemaQuench wraps in SELECT CASE WHEN (…) THEN 1 ELSE 0 END. No folder gate can use a query token: query tokens are kept out of the load-time pass and are only ever applied to scripts. A component gate is a bare predicate (a leading SELECT is stripped). For example:
"ShouldApplyExpression": "DATABASE() LIKE '%_dev'"
A declared component whose expression evaluates false is, for this deploy, not declared. The parse removes it from the working set before any comparison, so nothing downstream can tell it from a component deleted from the package: an existing table the product owns is dropped under DropTablesRemovedFromProduct, an existing column under DropColumnsRemovedFromProduct, and an index, foreign key or check constraint under its own Drop…RemovedFromProduct flag — on MariaDB the log line reads Drop index not declared for this deploy. A gate is a declaration about this target, not a pause. To keep an object on a target where its gate is false, set the matching Drop…RemovedFromProduct flag to false for that environment, or mark the table PreventDrop.
A folder gate has no such effect: the scripts of a gated-off folder are not run, and their run-once tracking rows are kept, because the scripts are still in the package.
ShouldApplyExpression covers skip decisions a SQL expression can make from outside the script. When the decision requires logic that can only run from inside the script — querying row state, checking role membership, branching on a result from a prior batch — the script raises a sentinel error instead. SchemaQuench recognizes the sentinel as an intentional skip, logs it, and continues the deployment without an error.
SCHEMASMITH: SHOULD NOT APPLY
The match is trimmed and case-insensitive. The message must be the entire error message — an unrelated error that merely contains the phrase does not trigger a skip. Any error with a different message still surfaces as a real failure. On MariaDB, raise it with:
SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'SCHEMASMITH: SHOULD NOT APPLY';
The sentinel may appear in any batch of a multi-batch script, not only at the top. When it fires, SchemaQuench stops processing the remaining batches. Earlier batches that already ran are committed — the engine does not wrap the script in a transaction, so the user owns the partial-work semantics.
A migration script (in the Before, BetweenTablesAndKeys, AfterTablesScripts, or After slot) that raises the sentinel is recorded in CompletedMigrationScripts as completed — it will not be retried on the next deployment. Tracking is per-database, so a skip in one database never affects another.
| Surface | Sentinel honored |
|---|---|
| Before / After scripts | Yes |
| Object scripts (procedures, views, functions) | Yes |
| Migration scripts | Yes |
[ALWAYS] scripts | Yes |
| Validation scripts | No — express N/A through conditional logic inside the validation |
| Tool-generated SQL | No — use ShouldApplyExpression on the component |
A pipeline reads one number from SchemaQuench, so each code means one kind of outcome: done, done but not everything asked for, failed for a reason you can fix, a defect, or the logs could not be kept. This table is SchemaQuench's own; the shared table in Logging — Exit codes covers every tool.
| Code | Meaning |
|---|---|
0 | Successful quench, or a passing --TestConnection, --PreviewTargets or --Validate (warnings alone from --Validate still exit 0). All databases quenched, logs backed up. Also a run with no arguments on an install nobody has configured, which prints what to fill in and runs nothing. |
1 | Finished, but not everything the package declares is in place: a feature the target lacks was downgraded under UnsupportedFeaturePolicy: warn, and the deployment summary lists each one. With --ExitNonZeroOnWarning (or the setting), also any run that would have exited 0 but logged a warning; the log then says so. |
2 | Failed for a reason you can fix. A command-line argument was not recognized (nothing runs); a required setting is missing (the product has no Platform); the package could not be loaded; a validation script, product script or version check failed, a target was refused or a TemplateTargets rule was broken; one or more database quenches failed, in continue mode or not; the connection to the target was lost mid-deploy; a --TestConnection / --PreviewTargets pre-flight found a connection error, version violation or required-template target miss; or a --Validate pass found an Error-severity finding. |
3 | Unhandled exception — a defect in the tool. The exception is in both logs; please report it with them. |
4 | Unable to back up log files. The quench itself finished; check permissions and disk space in the log directory. |
Exit codes tell a pipeline whether the run passed. When a run fails, the engine's own error code tells you what went wrong. MariaDB prints its classic error message along with the numeric code.
| Failure | Code |
|---|---|
| Foreign-key violation (orphan) | 1452 |
| NOT NULL violation | 1048 |
| Duplicate / unique-key | 1062 |
| String or binary truncation | 1406 |
| Type / conversion mismatch | 1366 |
| Deadlock (retried automatically) | 1213 |
Deadlocks are retried for you — SchemaSmith detects the deadlock and re-runs the operation with backoff, so a transient lock collision resolves itself rather than failing the deploy. To recognize the same fault across engines, see per-platform error codes.
Reference data doesn't have to live in a pile of hand-rolled scripts. Each table that participates carries a DataDelivery block in its JSON; SchemaQuench walks every table JSON, keeps the ones that declare delivery, orders them by foreign key dependencies, and merges each one. On MariaDB, delivery is applied with INSERT ... ON DUPLICATE KEY UPDATE plus a conditional delete pass — MariaDB has no native MERGE, so SchemaQuench composes the equivalent idiom from primitives every MariaDB version supports. Tables without a DataDelivery block are left untouched. See Data delivery for the full property reference and worked examples.
A deleting delivery refuses a cascading foreign key. When a delivery whose MergeType deletes (Insert/Update/Delete) targets a table that another table references with ON DELETE CASCADE, data delivery for that database stops before any table is merged, because the deletes would cascade into the other table: Table <table> uses MergeType=Insert/Update/Delete but is referenced by FK <name> on <child> with ON DELETE CASCADE. Change the MergeType to Insert/Update, or remove the CASCADE rule.
A table's DataDelivery block can also be an array of independently-gated deliveries, each with its own ShouldApplyExpression. SchemaQuench evaluates every delivery's gate against each database it delivers to, before any content file is read, and every delivery whose gate passes applies — not just the first match. A delivery whose gate evaluates false is logged as skipped and never touches the table; a delivery whose gate expression itself errors aborts the deployment (fail-closed), the same way a folder-level gate does.
A delivery's gate resolves only {{ServerMajorVersion}} and {{CompatibilityLevel}} for version gating (see Gating on the target version above) — not the product's script tokens, which a folder gate also receives.
Gate evaluation also runs under WhatIfONLY, so a dry run reports the same deliver-vs-skip decisions a real quench would make. The Insert/Update/Delete CASCADE-FK check (above) only considers deliveries whose gate is currently passing — a Delete variant that's gated off this run can't abort the deployment over a CASCADE FK it will never execute.
See Data delivery — Multiple deliveries for the JSON shape, the common gating patterns, and the delete-overlap warning for multi-delivery tables that mix Insert/Update/Delete with overlapping MergeFilters.
Foreign keys turn "load the data" into a graph problem, which SchemaQuench solves automatically:
A circular dependency among NOT NULL foreign keys fails the dependency sort — SchemaQuench logs the cycle and the quench fails. Make one side of the cycle nullable so delivery can break the loop.
Insert — missing rows inserted; existing and extra rows left alone. The seed-data pattern.Insert/Update — missing rows inserted, changed rows updated; extra rows left alone. Good for reference tables environments may append to. What the demo products use.Insert/Update/Delete — full sync: missing rows inserted, changed rows updated, and target rows not present in the source deleted.MergeType has no default: a delivery that omits it, or sets None, is not run.
You can use both. For each target database, SchemaQuench first delivers every table with a DataDelivery block in FK order, then runs any .sql files you dropped into the template's TableData-slot folders through the dependency retry loop. Use declarative DataDelivery for bulk reference data and keep the script slot for special cases — conditional seeds, one-off rebuilds, procedural loads.
Long deployments fail. Network blips, transient lock timeouts, a migration script that tripped on bad data at step 14 of 20. Without checkpointing, a failure in the final stretch means the next run starts from zero — re-running every step you've already successfully applied.
SchemaQuench writes checkpoints as it goes. Every completed checkpointed step (see Checkpoint scopes below) and every completed script is recorded to disk. On the next run, already-completed work is skipped and execution resumes at the first incomplete step.
schemaquench --ResumeQuench
With --ResumeQuench, SchemaQuench reads the existing checkpoint files (if any) and skips anything already recorded as complete. Without the switch, the resume logic is off — every step executes regardless of prior state, and each database the run reaches starts a fresh checkpoint.
SchemaQuench --CheckpointDirectory:C:\schemasmith\checkpoints
schemaquench --CheckpointDirectory:/var/schemasmith/checkpoints
By default, checkpoints live in %TEMP%/schemaquench-checkpoints (or the platform equivalent). Override with --CheckpointDirectory:<path> when you need them on a specific volume — for a CI runner with ephemeral temp storage, a shared build server, or a mounted volume that outlives the container. The directory is created if it doesn't exist.
The same value can be set in SchemaQuench.settings.json via the CheckpointDirectory key. The CLI switch wins if both are present.
Checkpoint files are named by product, template, server and database, not by run, so two runs at the same time that share those names write to the same files. Only --ResumeQuench reads them, so that never changes what a run does — but if you may need to resume one of two concurrent runs, give each its own CheckpointDirectory.
Progress is recorded per database: one checkpoint file per {product, template, server, database} combination. A resumed run enters every template again and each database continues from its own file. Product-level Before and After scripts are not checkpointed, so a resumed run runs them again, as every deployment does.
| Step name | What it covers |
|---|---|
ValidateBaseline | Baseline validation script. |
SequenceQuench | Sequence deployment. |
ModifiedTables | Altering existing columns, generated columns, dropping tables. |
IndexesAndConstraints | Creating missing indexes, check constraints, defaults. |
TableDataDelivery | Both passes of FK-aware data delivery for tables with DataDelivery blocks. |
ForeignKeys | Creating, modifying, and dropping foreign keys. |
EventQuench | Scheduled event deployment. |
VersionStamp | Version stamp script. |
Kindling the helper procedures and adding missing tables and columns are never checkpointed: they rebuild session state the later steps need, so a resumed run always repeats them. Both are safe to repeat.
In addition, each template slot (Setup, Before, Objects, BetweenTablesAndKeys, AfterTablesScripts, AfterTablesObjects, TableData, After) records the exact scripts that ran, so resumed runs skip each individual script that already succeeded.
A checkpoint records names, not content: a step by its step name, a script by the full path it was loaded from, not its path within the template. Nothing in it describes what the package declared when the step ran, and a resumed run does not compare the two. So, between the failed run and the resume:
--ResumeQuench, while the completed steps, recorded by name, are still skipped.ModifiedTables is skipped.Resume is for finishing the run that failed, with the fix confined to what failed. After editing anything else in the package, run without --ResumeQuench and let the full sequence converge it.
Checkpoints exist to protect against failures. When the quench completes without error, SchemaQuench deletes the checkpoint files of the databases it deployed. Another database's checkpoint — a failed deploy of the same product to a different target, with a different settings file — is left in place, so that deploy can still be resumed. A failed run leaves its checkpoint files in place, ready for the next --ResumeQuench invocation.
A 90-minute deployment to a large production database fails at minute 75 because a migration script hit a transient deadlock. You fix the data, re-run the deployment:
schemaquench --ResumeQuench
SchemaQuench reads the checkpoints, repeats the kindling and the missing-table step (they are never checkpointed, and both are safe to repeat), sees that ValidateBaseline, the table modifications, indexes, constraints, and every Objects-slot script already succeeded, logs what it's skipping, and picks up at the first incomplete step. Minutes of work instead of starting from the top.
Use --ResumeQuench when you specifically expect that a prior run may have left partial state — typically when re-running after a real failure in a non-trivial deployment.
A deploy that fails halfway is a question every DBA asks before the first run: what is in the database now? The answer is the engine's, not SchemaQuench's. SchemaQuench opens no transaction of its own — the only transactions in a run are the ones the engine wraps around each statement, the ones a few procedures open for themselves, and the ones your own scripts write — so what a failure leaves behind follows directly from how the engine treats DDL.
On MariaDB, every DDL statement commits implicitly and cannot be rolled back, so a failed step leaves every statement before the failing one applied, and the procedures do not pretend otherwise. RebuildTable orders its work so the irreversible part is as short as possible: the shadow table is built and filled first (a failure strands only the shadow, which the next run refuses to overwrite and names), the swap is one atomic RENAME TABLE, and only then are the old table's keys dropped and the old table removed — a failure there leaves the live table complete and a parked …_SchemaSmithOld copy holding the pre-rebuild rows. Data delivery and migration scripts are DML and commit per statement unless the script starts a transaction.
What a failure leaves. The result is a database somewhere between the old and the new declared state, with each completed statement in place. The log carries the error message — with the script's path when the failure is in one of your scripts — and, with WriteDebugSql on, the path of the file holding the resolved SQL that was running, for your scripts and the generated steps that write one; see Log files and the Failure triage roll-up. Other databases in the same run continue or stop per ContinueOnDatabaseFailure.
Recovery is a re-run. Because every step compares the live state with the declared state, running the deploy again after the cause is fixed picks up where the failure left off: what applied is found in place and left alone, what did not is applied. --ResumeQuench does the same with less work, skipping the steps and scripts the failed run recorded as complete. What neither can do is undo a completed statement; for that, deploy the previous package, as Rollback and recovery describes, with the same caveat about DDL that this section started from.
One command fans out across dozens of tenants, and one of them comes back red. Which target? Which phase? Was it the migration script or a modified table? Did the whole run drag because a single database took ninety seconds in one slot? The deployment summary report is the machine-readable receipt for the run — every target, every timing, every failure, and every verified object change, in one structured file you can read, diff, or feed to a dashboard.
Every quench writes one. You don't ask for it, you don't switch it on — it lands next to your logs on success, on partial failure, and even when the run hard-aborts.
The report is two files carrying the same run, in two shapes: a Summary.json for machines and a Summary.md for humans. Both are produced from the identical in-memory model, so they never disagree — the JSON is the contract, the Markdown is the same facts rendered to read at a glance. By default both land in the log directory alongside the run's other logs:
SchemaQuench - Summary.json
SchemaQuench - Summary.md
They're archived with the rest of the logs when a run finishes, so a report travels with the progress log, the errors log, and the failure roll-up it describes — one bundle per run, nothing to collect separately.
The default location keeps the report with its logs, which is what you want most of the time. But CI pipelines often want the summary at a known path — a build artifact to publish, a file a later step parses — independent of wherever the logs happen to rotate. The --report switch pins both files wherever you name them.
schemaquench --report:./artifacts/deploy-summary
That writes ./artifacts/deploy-summary.json and ./artifacts/deploy-summary.md. You give the path without an extension; SchemaQuench appends .json and .md to the base you provide. Omit the switch and both files fall back to SchemaQuench - Summary.json / .md in the log directory.
Attach the value with : or =, as with every other SchemaSmith switch — not with a space. A space-separated --report ./artifacts/deploy-summary leaves the switch with no value and the path standing alone as an argument the tool will never read, so the run stops before anything connects: Not recognized: ./artifacts/deploy-summary. Nothing was run., exit 2.
A big fan-out has a long tail. Most targets finish in a second or two; a handful crawl. The report's bottlenecks list exists to surface exactly those outliers — the individual slot-on-a-target measurements that ran long enough to be worth a look — without you scanning every timing by hand. The cutoff is one setting.
BottleneckThresholdMs sets the millisecond bar an individual slot measurement must exceed to be listed as a bottleneck. The default is 30000 (30 seconds). Lower it to catch smaller stalls on a fast fleet; raise it on a heavy release where a minute per slot is normal and you only care about the true stragglers.
schemaquench --BottleneckThresholdMs=10000
Set it in the settings file ("BottleneckThresholdMs": 10000), as an environment variable (SmithySettings_BottleneckThresholdMs=10000), or on the command line as above. It only governs which measurements appear in timing.bottlenecks — every slot is still timed and rolled up in bySlot and byDatabase regardless of the threshold. See Reading Summary.json for the full field reference, and objectChanges for the verified-change data.
Writing the report is wrapped so that a failure to assemble or serialize the summary can never disrupt the run's real logging, exit code, or control flow — a broken report never breaks a deployment. If it can't be written, you get a one-line warning in the progress log and the run proceeds exactly as it would have.
Success, partial failure, and every hard-abort site funnel through the same writer, and it's idempotent — an aborting run writes the report once on its way out. A run that died is exactly the run whose report you most want to read, so the report is there for it.
The JSON is the frozen contract: camelCase keys, enum values as their names, indented for reading. Here it is end to end for a small two-tenant run, annotated — the field tables below define every key.
{
"schemaVersion": "1.2", // contract version of this report shape
"tool": "SchemaQuench",
"toolVersion": "2.8.0.0",
"run": {
"product": "Northwind",
"platform": "MariaDb", // SqlServer | PostgreSQL | MySQL | MariaDb
"startedUtc": "2026-07-09T14:03:11.204Z",
"finishedUtc": "2026-07-09T14:03:47.881Z",
"durationMs": 36677, // run wall-clock
"mode": "Quench", // Quench | WhatIf
"outcome": "Success", // Success | Incomplete | PartialFailure | Aborted
"exitCode": 0,
"resumedFromCheckpoint": false
},
"targets": [
{
"server": "primary",
"database": "TenantA",
"schema": null, // MariaDB targets carry no schema
"template": "Tenant",
"outcome": "Success", // Success | Failed | Skipped
"durationMs": 14820,
"databaseSource": "DatabaseIdentificationScript",
"schemaSource": "(regular template)",
"slots": [
{
"slot": "ModifiedTables",
"durationMs": 9120,
"scriptsRun": 3
},
{
"slot": "ObjectScripts",
"durationMs": 4110,
"scriptsRun": 12
}
]
}
],
"migrationScripts": [
{
"path": "MigrationScripts/0007-backfill-region.sql",
"slot": "MigrationScripts",
"template": "Tenant",
"schema": null,
"server": "primary",
"database": "TenantA",
"outcome": "Ran" // "Ran", or "Skipped" when it raised SHOULD NOT APPLY
}
],
"timing": {
"totalMs": 36677,
"bySlot": [
{ "slot": "ModifiedTables", "totalMs": 18240, "targetCount": 2 }
],
"byDatabase": [
{ "database": "TenantA", "totalMs": 14820 }
],
"bottlenecks": [
{
"scope": "[primary].[TenantA]",
"slot": "ModifiedTables",
"durationMs": 31210
}
]
},
"failures": [], // one entry per failed scope; empty on a clean run
"whatIf": null, // populated only for a WhatIf-mode run
"objectChanges": {
"instrumented": true,
"created": {
"tables": 1,
"columns": 2,
"indexes": 4,
"constraints": 2,
"foreignKeys": 1,
"procedures": 0,
"views": 0,
"functions": 0
},
"modified": {
"tables": 1,
"columns": 3
},
"dropped": {
"tables": 0,
"indexes": 1,
"constraints": 0,
"foreignKeys": 0
},
"scriptsRan": 12,
"scriptsUnchanged": 3, // object scripts left alone because nothing changed since their last apply
"details": [
{
"objectType": "table",
"objectName": "Orders",
"action": "created",
"server": "primary",
"database": "TenantA"
},
{
"objectType": "column",
"objectName": "Orders.Region",
"action": "modified",
"server": "primary",
"database": "TenantA"
},
{
"objectType": "index",
"objectName": "Orders.IX_Region",
"action": "dropped",
"server": "primary",
"database": "TenantA"
},
{
"objectType": "procedure",
"objectName": "Procedures/GetOrders.sql",
"action": "ran",
"server": "primary",
"database": "TenantA"
}
]
},
"preventDrop": null, // null unless the environment's PreventDrop is on
"unsupportedDowngrade": null // null unless a feature was degraded for the target version
}
| Key | Meaning |
|---|---|
schemaVersion | Contract version of the report shape — currently "1.2". |
tool | Always "SchemaQuench". |
toolVersion | The CLI version that wrote the report — the same string --version prints. |
run | Run-level facts: product, platform, timing, mode, outcome. |
targets | One entry per (server, database, schema) target the run touched. |
migrationScripts | One entry per migration script that ran. |
timing | Aggregate timing plus the bottleneck outliers. |
failures | One entry per failed scope — the same content as the failure roll-up log. |
whatIf | The would-apply / would-skip / would-deliver plan; null unless the run was WhatIf mode. |
objectChanges | Verified DDL changes and object-script runs — its own section below. |
preventDrop | The no-drop protection manifest: what the run would have dropped by absence and withheld. null unless the environment's PreventDrop is on. |
unsupportedDowngrade | Features the package declared that the target version couldn't take, emitted in a degraded form and recorded. null when nothing was degraded. |
| Key | Meaning |
|---|---|
product | The product name from Product.json. |
platform | SqlServer, PostgreSQL, MySQL, or MariaDb. |
startedUtc / finishedUtc | Run start and end, UTC. |
durationMs | Wall-clock milliseconds for the whole run. |
mode | Quench (a real deploy) or WhatIf (a dry run). A --Validate run writes no report: it exits with its findings before a deployment starts. |
outcome | Success; Incomplete (every target finished, but a feature was downgraded on a target that lacks it — see unsupportedDowngrade — exit code 1); PartialFailure (some targets failed, others succeeded); or Aborted. |
exitCode | The process exit code the run returned. |
resumedFromCheckpoint | true when the run resumed a prior interrupted deployment. |
| Key | Meaning |
|---|---|
server / database / schema | The target's coordinates; schema is null when the target has no schema. |
template | The template that produced this target. |
outcome | Success, Failed, or Skipped. A target skipped because a TemplateTargets database does not exist and CreateIfMissing is false is listed as Skipped. |
durationMs | Milliseconds spent on this target. |
slots[] | Per-slot timing for this target: slot, durationMs, scriptsRun. |
databaseSource / schemaSource | Where each axis of this target came from — the discovery script, or a TemplateTargets override naming the template and key. This is the run's source-disclosure audit trail: it answers “was this tenant selected by the script, or overridden in config?” per target. MariaDB has no schema templates, so every target carries schemaSource: "(regular template)". Empty on a run with no source information recorded. |
| Key | Meaning |
|---|---|
path | Package-relative path of the migration script. |
slot | The slot it ran in. |
template / schema / server / database | Where it ran; schema and database are null when not applicable. |
outcome | "Ran", or "Skipped" when the script raised the SHOULD NOT APPLY sentinel. Either way it is recorded as done and not run again; the Markdown marks a skipped one. A script appears here only when it was run this time. |
Applied before the failure. Nothing a failed run applied is rolled back, so the Markdown of a failed or aborted run adds an "Applied Before The Failure" section: every migration script that ran, every object script that ran, and every table whose data was delivered before the run stopped, under a heading for each server and database it reached, so a fleet run shows what each target had applied. --ResumeQuench continues from there. The JSON carries the same facts in migrationScripts[] and objectChanges.details[].
| Key | Meaning |
|---|---|
totalMs | Run wall-clock, matching run.durationMs. |
bySlot[] | Per-slot rollup across all targets: slot, totalMs, targetCount. |
byDatabase[] | Per-database rollup: database, totalMs. |
bottlenecks[] | Individual slot-on-a-target measurements exceeding BottleneckThresholdMs: scope, slot, durationMs. |
Empty on a clean run. Each entry mirrors the failure triage roll-up exactly — same content, same backup directory, no new exposure.
| Key | Meaning |
|---|---|
phase | The phase the failure occurred in. |
scopeKey | The failed scope — a tenant, a per-server script, or a product-level phase. |
error | The engine's error text for the failure. |
contextTail[] | The captured tail of log lines leading up to the failure. |
artifactPath | Path to the resolved-SQL artifact for the failed scope, when one was written. |
null for a real quench. On a WhatIf-mode run it holds the plan, split three ways — and no entry carries a SQL body: a script entry carries its path, a DataDelivery entry the table's name. This block is the script-level plan; the engine-generated structural changes a WhatIf run would make (tables, columns, indexes, constraints, foreign keys) preview in objectChanges with would* actions.
| Key | Meaning |
|---|---|
wouldApply[] | Scripts the run would apply, product scripts included: scope, script. |
wouldSkip[] | Changes it would skip. |
wouldDeliver[] | Data it would deliver: a Table Data script's path, or a table's DataDelivery as the table's name (with [variant] when the delivery names one). |
null unless the environment-level PreventDrop is on. When it is, the run skips every drop-by-absence and this block is the receipt for what it withheld, so a protected environment can see what a full deploy would remove without removing it.
"preventDrop": {
"enabled": true,
// empty when protection was on but nothing was suppressed
"wouldDrop": [
{ "objectType": "table", "objectName": "sales.LegacyOrders" },
{ "objectType": "column", "objectName": "sales.Orders.Region" }
]
}
| Key | Meaning |
|---|---|
enabled | Always true when the block is present. |
wouldDrop[] | One entry per object that would have been dropped by absence and was kept: objectType names the kind (tables, columns, foreign keys, check constraints, indexes), objectName the object. Only by-absence removals are listed; a drop-and-recreate for a declared change never is. |
In Summary.md the same block renders under a PreventDrop (no-drop protection) heading, as Protection active — no drops were suppressed this run. or Protection active — N drop(s) suppressed … with one bullet per object. These suppressed drops are not objectChanges.details[] rows: they belong here, because nothing changed.
Timing tells you where the run spent its seconds; objectChanges tells you what it did to your schema. This is the section a DBA reads after a release: how many tables were created, which columns were modified, what got dropped. But it draws a hard, honest line between changes SchemaSmith verified and scripts it merely ran — and understanding that line is the whole point of the section.
Verified counts. As SchemaSmith's quench procedures run DDL, they record each real change to a session-scoped audit that SchemaSmith drains back in-process. Those captured rows are the created, modified, and dropped counts — genuine, observed structural changes to tables, columns, indexes, constraints, and foreign keys. If the count says one table created and three columns modified, that is what happened, read back from the engine.
Under WhatIf. A WhatIf run records what it would change with the parallel actions wouldCreate / wouldModify / wouldDrop, which roll into the same created / modified / dropped buckets — so a dry run's objectChanges previews the structural changes it would make rather than reporting an empty section. The counts read the same as a real run; the report's mode field (WhatIf vs Quench) is how you tell a preview from an applied change.
Scripts that ran. Object scripts — your stored procedures, views, and functions — are a different story. A script SchemaSmith runs is re-applied idempotently, so it executes whether or not its body changes anything. SchemaSmith refuses to guess. It will not tell you a procedure was "created" or "modified" when all it honestly knows is that the script ran. So object scripts never touch the created/modified counts. Instead they contribute to scriptsRan (a count) and to details[] rows carrying "action": "ran". An object script that was not re-run because nothing changed since its last apply counts under scriptsUnchanged instead, with a details[] row carrying "action": "unchanged" — the report says which scripts it left alone as plainly as which it ran.
| Bucket | Object types counted |
|---|---|
created | tables, columns (columns added to an already-existing table — a new table's own columns count under that table's creation, not here), indexes, constraints, foreignKeys, plus procedures / views / functions fields that stay 0 by design (object scripts don't count as created). |
modified | tables, columns. |
dropped | tables, indexes, constraints, foreignKeys. |
scriptsRan | Total object scripts that ran this run. |
scriptsUnchanged | Total object scripts left alone because their text and the module the server renders are both as they were after the last apply. |
Where the counts are the summary, details[] is the itemized list — one row per recorded change or run, each with objectType, objectName, and action. The actions you'll see are created, modified, dropped, ran and unchanged on a real quench — plus rebuilt on a table that RebuildPolicy replaced wholesale, and reapplied on a procedure or function whose grants were put back after it was dropped and re-created — and their wouldCreate / wouldModify / wouldDrop / wouldRebuild / wouldReapply previews on a WhatIf run (an unchanged script is unchanged under WhatIf too, since the probe is read-only).
details[] also carries object types that have no dedicated count bucket. The verified-change audit records more kinds of object than the count fields cover, and those surface here rather than being dropped:
fullTextIndex — a full-text index created or dropped. MariaDB supports multiple per table.sequence — a sequence created or modified.dataDelivery — a table's DataDelivery that ran (delivered), or under WhatIf would run (wouldDeliver). The name is the table's, with [variant] when the delivery names one.database — a database created because its TemplateTargets entry or template sets CreateIfMissing (created, or wouldCreate under WhatIf).These appear as details[] rows with their real objectType and action even though no top-level count field aggregates them — the detail is preserved even where the summary doesn't bucket it.
A row also carries mode when OnlineApply decided how the change ran: online, instant, or unavailable for the plain statement where the online one could not be used. A WhatIf row carries no mode, since only the engine can say which form it accepts. A row has no mode key at all when nothing chose a form, so a deploy with OnlineApply off reports exactly what it did before the field existed (schema version 1.2 added it).
Each row also names where the change was made: server and database. A fleet run makes the same change in many places, and these say which. Server-level rows, such as a database created for CreateIfMissing, carry the server and the database they created. Schema version 1.2 added these keys too.
| Value | Meaning |
|---|---|
true | The run's engine produced a real audit read; the counts and details are populated. |
false | The engine couldn't read the audit (for example, kindling was suppressed), so every count is 0 and details[] is empty. |
instrumented: false means unknown, not nothing happened. A run whose audit couldn't be read reports honestly-empty change data rather than pretending zero changes occurred. Read the progress log for what the run actually did in that case.
The report shape is identical on every supported engine — same keys, same nesting, same enum values. The platform field tells you which engine produced it, and a few details[] object types are engine-specific (the full-text index and sequence types above), but the contract is one shape everywhere. A dashboard that parses a SQL Server report parses a MariaDB one unchanged.
Reporting a re-applied procedure as "modified" every time it runs would be a lie that made every report look busy. An honest report says exactly what it knows: verified structural changes as counts, idempotent re-applies as "ran". When you see scriptsRan: 12, twelve object scripts executed — the report is not claiming twelve objects changed.
Free schema-as-code for SQL Server, PostgreSQL, MySQL, and MariaDB.
The source is on GitHub for anyone to read.
Get Started on GitHub