SchemaQuench for MariaDB

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

SchemaQuench: a stacked database being quenched with water and ember sparks

Take your declared schema and harden it onto a live database — that's what SchemaQuench does.

Overview

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.

Installation and invocation

SchemaQuench is included in the SchemaSmith distribution. Run it from the directory containing SchemaQuench.settings.json:

schemaquench

Common switches

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.

Configuration reference

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.

Target connection settings

KeyTypeDefaultDescription
Target:Serverstring(required)Database server hostname or IP.
Target:Portstring3306TCP port for MariaDB.
Target:Userstring(empty)Login username.
Target:Passwordstring(empty)Login password.
Target:ConnectionPropertiesobject{}Arbitrary key-value pairs appended to the connection string. Platform-specific keys — see Connection configuration.

Target scope settings

KeyTypeDefaultDescription
Target:Templatesstring array[]Run only these templates. Empty array means no filter — all templates run. See Target.
Target:Databasesstring array[]Run only against these databases. Empty array means no filter — all discovered databases run. See Target.
Target:TemplateTargetsobject{}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.

Behavior settings

KeyTypeDefaultDescription
SchemaPackagePathstring(required)Path to the schema package directory or ZIP file.
WhatIfONLYboolfalseDry-run mode. Generates SQL without executing. The --WhatIf switch turns it on for one run.
KindleTheForgebooltrueDeploy SchemaSmith helper procedures and the migration tracking table to each target database before quenching.
ForceReKindleboolfalseRe-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.
UpdateTablesbooltrueApply table structure changes (columns, indexes, constraints, foreign keys) from the schema package.
OnlineApplystringOffOff, 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.
RebuildPolicyModestring(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.
RebuildPolicyThresholdint(unset)With THRESHOLD, the number of pending column modifications that triggers a rebuild.
RebuildPolicyOnOrderMismatchbool(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.
SystemVersioningAlterHistorystring(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.
DeliverDatabooltrueRun 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.
RunScriptsTwiceboolfalseRun object scripts twice to verify idempotency. A CI/testing tool.
Target:SkipUnchangedObjectsbooltrueDo 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:UnsupportedFeaturePolicystringwarnWhat 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.
TrackRunOnceMigrationsbooltrueTrack run-once migration scripts. When false, all scripts run on every deployment.
PruneObsoleteMigrationTrackingbooltrueRemove tracking entries for scripts no longer in the package. When Target filters are active, prune is restricted to the targeted scope — see PruneObsoleteMigrationTracking.
CheckpointDirectorystring""Directory for checkpoint files used by --ResumeQuench. When blank, defaults to a per-platform temp location. See Checkpoint and Resume.
MaxThreadsint10Maximum parallel work units. Range 1–20; a value outside it, or one that is not a whole number, falls back to 10. See MaxThreads.
ScriptTokensobject{}Config-level overrides for product script tokens.

Drop control settings

KeyTypeDefaultDescription
PreventDropboolfalseEnvironment-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.
DropTablesRemovedFromProductbooltrueDrop tables that exist in the database but aren't defined in the schema package. Also settable as a Product.json property — see DropTablesRemovedFromProduct.
DropColumnsRemovedFromProductbooltrueDrop 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.
DropForeignKeysRemovedFromProductbooltrueDrop 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.
DropCheckConstraintsRemovedFromProductbooltrueDrop 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.
DropIndexesRemovedFromProductbooltrueDrop 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.
DropUnknownIndexesboolfalseDrop 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.
DropPeriodsRemovedFromProductbool(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.
DropEventsRemovedFromProductboolfalseDrop 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.

Logging and diagnostics settings

KeyTypeDefaultDescription
VerboseLoggingboolfalseHas no effect on MariaDB: SchemaQuench does not log informational messages from MariaDB scripts. SchemaSmith's own progress messages always appear.
WriteDebugSqlboolfalseWrite 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.
ArtifactPathstring(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.
FailureContextLinesint25How 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.
BottleneckThresholdMsint30000The milliseconds an individual slot measurement must exceed to be listed as a bottleneck in the deployment summary. See Deployment summary report.
ExitNonZeroOnWarningboolfalseExit 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.
LogHygieneobject(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.

Full settings file example

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.

Target — selective execution scope

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.

Filter dimensions

MariaDB has no schema-inside-database concept, so there is no Target:Schemas dimension — scope narrows by template and database only.

KeyTypeDefaultDescription
Target:Templatesstring array[]Run only these templates. Empty array means no filter — all templates run.
Target:Databasesstring 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.

Onboarding example

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.

Prune is scoped to the filter

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.

TemplateTargets

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).

Databases

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."

CreateIfMissing

Boolean. Default false. Controls what happens when an entry in Databases doesn't exist on the target server:

StateCreateIfMissing: trueCreateIfMissing: false (default)
Target existsDeploy normallyDeploy normally
Target missingProvision (DDL), then deploySkip 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.

Validation

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.

Filter composition

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.

The schema axis does not apply on MariaDB

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.

Provisioning requires elevated privileges

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.

When to reach for it

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.

MaxThreads

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.

Serial queue for AllowParallel: false

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

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.

ContinueOnDatabaseFailure

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

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.

Deployment execution flow

When SchemaQuench runs, the product quench executes these steps in order:

  1. Log product info. Logs the product name, platform, template order, validation script, and any configured script tokens.
  2. Test server connection. Opens a connection to the target server and runs a MariaDB liveness check. Aborts if the connection fails.
  3. Validate server. If Product.ValidationScript is configured, executes it against information_schema. Aborts if the result is falsy.
  4. Validate baseline. If Product.BaselineValidationScript is configured, executes it. Aborts if the result is falsy.
  5. Load and check templates. Loads every template in 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.
  6. Product Before scripts. Executes scripts from Before Product folder(s) against the administrative connection.
  7. Quench each template. For each template in scope, in Product.TemplateOrder:
    • Executes DatabaseIdentificationScript against information_schema to discover target databases.
    • Creates one work unit per discovered database (MariaDB has no schema templates, so there are no (database, schema) pairs).
    • Dispatches all work units to a pool of up to MaxThreads concurrent workers. Each worker runs the full database quench sequence for its assigned database.
    • If any iteration fails, logs the failure. Failure routing follows the template's ContinueOnDatabaseFailure setting.
  8. Product After scripts. Executes scripts from After Product folder(s).
  9. Stamp product version. If Product.VersionStampScript is configured, executes it.
  10. Log completion. Logs "Completed quench of {ProductName}".

After the quench returns, the calling program backs up log files to a numbered directory and exits with code 0 (see Exit codes).

Database quench sequence

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.

  1. Target checks. A template with SkipIfReadOnly skips a read-only target (a replica) and counts it as a success.
  2. Detect the version. The server version is read once, up front, and becomes the {{ServerMajorVersion}} token; {{CompatibilityLevel}} resolves to the same value on MariaDB.
  3. Folder gates. Every template folder with a 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.
  4. Kindle the Forge. Installs or refreshes SchemaSmith's helper procedures, functions and tables, stamp-gated so an up-to-date database pays one read. Never checkpointed; skipped when KindleTheForge is false. See KindleTheForge and What SchemaSmith installs in your database.
  5. Validate baseline. Executes Template.BaselineValidationScript if configured; a falsy result or an error stops the deploy. Checkpointed as ValidateBaseline.
  6. Setup scripts. Executes scripts from any folder in the 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.
  7. Objects, first pass. Executes the 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.
  8. Sequences. Deploys the template's declared sequences, before the tables, because a default can call nextval(). Checkpointed as SequenceQuench.
  9. Add tables and columns. Parses 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.
  10. Objects, second pass. Retries the token-free Objects-slot scripts, now that missing tables exist, then resolves the template's query tokens into every slot's scripts.
  11. Before scripts. Executes migration scripts from any folder in the Before slot. Sequential and tracked.
  12. ModifiedTableQuench. Drops tables removed from the product (their inbound foreign keys first), elects tables for a rebuild, drops modified or removed indexes, foreign keys and check constraints, alters existing columns, drops columns removed from the product, and converges table attributes (engine, collation, comment, row format, encryption, compression, auto-increment seed and system versioning). Checkpointed as ModifiedTables.
  13. Vector index rebuild (MariaDB 11.7 and later). Drops a VECTOR index whose M or Distance changed, for step 16 to build again as declared.
  14. AfterTablesObjects pass. Executes 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.
  15. BetweenTablesAndKeys. Executes migration scripts from any folder in the BetweenTablesAndKeys slot. Sequential and tracked.
  16. MissingIndexesAndConstraintsQuench. Adds generated columns, missing indexes, defaults, check constraints and full-text indexes. An index-only template runs IndexOnlyQuench here instead. Checkpointed as IndexesAndConstraints.
  17. Record expressions. Records what each expression-bearing object was applied with, so the next deploy compares against it. A failure here is logged and does not fail the deploy.
  18. AfterTablesScripts. Executes migration scripts from any folder in the AfterTablesScripts slot. Sequential and tracked.
  19. Final object pass. Runs the Objects- and AfterTablesObjects-slot scripts not yet applied, with the final attempt's failures reported as errors.
  20. Table data delivery. Merges table data described by per-table 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.
  21. ForeignKeyQuench. Creates, drops and modifies foreign keys to match the schema package; after the data, so delivered rows satisfy them. Checkpointed as ForeignKeys.
  22. Scheduled events. Deployed through the EventQuench procedure when the template declares any. Checkpointed as EventQuench.
  23. Re-apply permissions. Puts back the grants captured off any module a script dropped and re-created.
  24. After scripts. Executes migration scripts from any folder in the After slot. Sequential and tracked.
  25. Stamp version. Executes 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.

Engine version compatibility

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.

Supported engine floors

These are the minimum versions SchemaSmith supports for deployment:

PlatformMinimum supported
SQL Server2008 (major version 10)
PostgreSQL12
MySQL5.7.22 on the 5.7 line; 8.0.23 on the 8.0 line
MariaDB10.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.

MinimumVersion pre-flight gate

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.

The detected version is reported in each engine's own form

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.

PlatformDetected version reads likeWhy that precision
SQL Server16.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
PostgreSQL16 (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
MySQL8.0.45Feature boundaries land mid-major — CHECK constraints at 8.0.16 — so a major alone cannot answer the question
MariaDB11.4.12-MariaDB-ubu2404Same 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.

Version-adaptive code generation

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 featureRequiresBelow that version, SchemaSmith…
Column rename (RENAME COLUMN)MariaDB 10.5.2reproduces the rename with CHANGE COLUMN, reconstructing the current column definition (same end state)
Index rename (RENAME INDEX)MariaDB 10.5.2drops 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.4adds 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.2runs 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 constraintsMariaDB 10.2.22applies 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.6stores 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.3stores 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.8stores 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.4refuses 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.3creates 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.3creates the key over the period's end and start columns, without WITHOUT OVERLAPS, and records a downgrade
Vector index (IndexType: VECTOR)MariaDB 11.7skips 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.7keeps 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.3creates 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.5creates 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 columnMariaDB 10.2.37 / 10.3.28 / 10.4.18 / 10.5.9, on each linecreates 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 AUTOMariaDB 10.9.1creates 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.4creates the column without the exclusion and records a downgrade — the column survives, the exclusion does not
Declared sequence (Sequences/*.json)MariaDB 10.3skips the sequence and records a downgrade
Sequence data type (DataType other than bigint)MariaDB 11.5creates 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 versionskips the index and records a downgrade
Column SRID restriction (SRID n on a spatial column)No equivalent on MariaDB at any versioncreates 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.

Native DDL on MariaDB

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.

  • An index is hidden with CREATE INDEX … IGNORED, and its visibility is read back from the IGNORED column of INFORMATION_SCHEMA.STATISTICS, where 'YES' means the index is ignored.
  • A check constraint is dropped with the generic 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.

Collation in the SQL you write on MariaDB 11.4 and later

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.

Name case on MariaDB

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.

SettingDatabase and table namesUsual default on
0Case-sensitive: Orders and orders are two tablesLinux
1Stored in lowercase; any spelling finds the tableWindows
2Stored as declared, compared case-insensitivelymacOS

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:

  • Extraction: SchemaTongs run against a server on setting 1 writes lowercase table names, because the server holds no other spelling. Setting 2 keeps the declared spelling.
  • Case-colliding tables: a template that declares two tables whose names differ only in case is refused (exit code 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.

Triggers and views on MariaDB

Two things a deploy does on MariaDB, because the engine gives no other way:

  • A changed trigger is dropped and created again. MariaDB cannot alter a trigger in place, so a trigger script is 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.
  • A redeployed view belongs to the deploying account. 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.

Server settings on MariaDB

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 settingWhat SchemaSmith does
sql_modeCreates 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_timestampTurned 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_zoneDataTongs 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 deliveryNO_AUTO_VALUE_ON_ZERO is added, so a row whose AUTO_INCREMENT key is 0 keeps 0.
innodb_force_primary_keySchemaSmith's own tables all have primary keys. Your tables must declare one, because the server refuses any table without it.
lower_case_table_namesSee Name case on MariaDB.

Upgrading MariaDB under a package

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.

FromWhat changesWhat to do
11.4The 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.8innodb_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.8A 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.3CONVERSION 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.

Quench slots

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.

Template quench slots

SlotExecution style
SetupSequential, every deploy
BeforeSequential, tracked
ObjectsDependency retry loop
BetweenTablesAndKeysSequential, tracked
AfterTablesScriptsSequential, tracked
AfterTablesObjectsDependency retry loop
TableDataDependency retry loop
AfterSequential, tracked

The Setup slot

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.

Product quench slots

SlotExecution style
BeforeSequential
AfterSequential

Product scripts run against the administrative connection, outside the per-database template loop.

  • Sequential, tracked — scripts run in alphabetical order and are recorded in CompletedMigrationScripts so they only run once (unless marked [ALWAYS]).
  • Sequential, every deploy — scripts run in alphabetical order on every deploy and are not recorded, so [ALWAYS] has nothing to add. The first script that fails stops the deploy; the ones after it do not run.
  • Dependency retry loop — scripts are retried in rounds until all succeed or no progress is made. See Dependency retry loop. An 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.

WhatIf mode

See exactly what SchemaQuench would do before it touches a single table. Set WhatIfONLY to true to perform a dry run. In WhatIf mode:

  • Validation scripts execute normally (server validation, baseline validation).
  • SchemaSmith's own helper procedures and tables are installed or updated on the target, as on a real run, so WhatIf needs the same permissions. None of your objects change.
  • Table quench procedures run with p_WhatIf = 1, generating the SQL that would be executed and logging it without applying changes.
  • Migration scripts show detailed status for each script:
    • Would APPLY: {script} for scripts that haven't yet been tracked.
    • Would SKIP (previously quenched): {script} for scripts already recorded in CompletedMigrationScripts.
  • Object scripts (Objects, AfterTablesObjects, Table Data) are logged but not executed.
  • Product Before/After scripts are logged but not executed.
  • Template version stamp isn't executed; a log message indicates the stamp would occur.

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.

Important limitation

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.

What WhatIf does and does not show

The gaps a dry run has are each explained where the feature is; this is the one list of them.

  • The top level only. The cascade limitation above: a change that only exists once an earlier change has applied is not in the preview.
  • Helpers are installed. Kindling runs as on a real deploy, so the target gets SchemaSmith's procedures and the run needs the same permissions.
  • Table steps preview. Every quench procedure runs with its WhatIf flag, logs the SQL it would run and records would* actions for the deployment summary — the foreign-key and event steps included.
  • Scripts are listed. Setup scripts are logged as 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.
  • Unchanged is a skip. The stamps are read and a script that would not re-run is reported SKIP (unchanged); nothing is recorded. See Unchanged object scripts.
  • Deliveries are decided. Delivery gates are evaluated and each delivery is reported as it would run or be skipped. See Gated deliveries and variants.
  • No copy check on MariaDB. The scratch-copy comparison of an expression SchemaSmith has not recorded is skipped on MariaDB, where the copy would be a real table, so such an expression previews as a change. See Expression change detection.
  • No mode on MariaDB rows. A MariaDB preview row carries no OnlineApply mode, because only the engine can say which form it accepts. See objectChanges.
  • Refusals still fire. What the real run would refuse, the preview refuses: a table another product owns, a rebuild of a system-versioned table, a partitioned table due for drop by absence, a DataDirectory move and the removal of IsSystemVersioned. The exception is the foreign-key refusal in Column changes, which runs only on a live deploy.
  • Nothing is created. A database CreateIfMissing would create is reported, not created, and its work units do not run: each logs one line saying every object the template declares would be created. See CreateIfMissing.
  • Ownership not stamped. Ownership rows and markers are a real write, so the preview skips them. See Table ownership.
  • No map is recorded. Nothing is recorded.

Debug SQL output

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.

When to use WhatIf

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.

Pre-flight diagnostics

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.

--Validate

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:

  • Package load — anything that would otherwise crash mid-deployment. A failure that takes down the whole package short-circuits everything else, so it's the only finding on that run; a component file or template that fails to load is excluded instead, and every other check still runs.
  • Duplication — two entries sharing a name at the same level, told apart from a legitimate set of conditional variants gated by ShouldApplyExpression.
  • Cross-object coherence — every foreign key and index, confirming the columns it references actually exist, plus the further checks listed in the table below. Names match without regard to case.
  • Token validation — every {{Token}} reference across every script and JSON file in the package, resolved as raw text.
  • Schema lint & staleness — your package against its committed .json-schemas/*.schema files, in a staleness pass followed by a structural and governance pass.
  • File naming — a table or declared-object file's on-disk name against the canonical name derived from its content.
  • Deprecated aliases — a template still using 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.

CodeSeverityMeaning
SS-LOAD-001ErrorEither 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-002ErrorA 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-003ErrorProduct.json does not declare a Platform. Every check depends on the target engine, so nothing further is checked. Add "Platform": "MariaDb".
SS-DUP-001ErrorSame-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-002WarningEvery entry in the group is gated (a legitimate variant set), but not every entry declares VariantName — label them for clarity.
SS-FK-001ErrorA foreign key's Columns entry names a column that doesn't exist on the local table.
SS-FK-002WarningA 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-004ErrorA foreign key's RelatedColumns entry names a column that doesn't exist on the related table.
SS-FK-005ErrorColumns and RelatedColumns have different entry counts — the column lists must be the same length.
SS-FK-006WarningTwo 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-009WarningA 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-010WarningA 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-001ErrorAn index's IndexColumns entry names a column that doesn't exist on the table.
SS-IDX-002ErrorAn index sets WithoutOverlaps but is not a primary key or unique key, so the clause would not be emitted.
SS-IDX-003ErrorAn index sets WithoutOverlaps but its last IndexColumns part is not one of the table's Periods.
SS-IDX-005ErrorA 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-006ErrorA table declares more than one VECTOR index. MariaDB allows one per table (error 1235); the second and later are reported.
SS-COL-002WarningA 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-005WarningA column is declared NVARCHAR, NCHAR or NATIONAL ..., which creates a utf8mb3 column. Declare VARCHAR or CHAR with CharacterSet: utf8mb4.
SS-COL-007WarningA 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-008WarningA 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-001ErrorA 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-002WarningA 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-001ErrorA 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-001ErrorA 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-002ErrorA 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-002WarningA 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-001WarningA 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-001ErrorA table sets PageCompressed together with RowFormat: "COMPRESSED". MariaDB refuses that combination (errno 140) and the error does not name the option.
SS-CO-002WarningA table sets PageCompressionLevel without PageCompressed, so the level is ignored.
SS-EVT-001ErrorA 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-002WarningAn 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-001ErrorA 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-002WarningA 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-003ErrorA 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-004ErrorA HASH or KEY partition declares a Values boundary. Those methods assign rows by hashing and have none.
SS-PART-005ErrorA 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-006ErrorA 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-007ErrorA table partitions by a method other than SYSTEM_TIME but declares no Expression.
SS-PART-008ErrorA 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-010ErrorPartitionCount and the named Partitions disagree on how many partitions there are; the engine refuses the table.
SS-PART-011ErrorA 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-012ErrorSubpartitioning under a method other than RANGE or LIST. Only those can be subpartitioned, and under SYSTEM_TIME the clause would be dropped.
SS-PART-013ErrorSYSTEM_TIME partitioning with both Interval and Limit. MariaDB takes one or the other.
SS-PART-014ErrorSYSTEM_TIME partitioning with Auto and neither Interval nor Limit, which AUTO adds history partitions by.
SS-PART-015ErrorSYSTEM_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-016WarningA partitioning value the deploy ignores: SystemTime outside SYSTEM_TIME, Expression under SYSTEM_TIME, KeyAlgorithm outside KEY, or SystemTime.StartsAt without an Interval.
SS-PER-001ErrorA period's StartColumn or EndColumn names no column of the table; MariaDB refuses the period.
SS-PER-002ErrorA table declares more than one period; MariaDB allows one application-time period per table.
SS-TOK-001ErrorA {{Token}} reference has no matching definition anywhere in the package.
SS-TOK-002ErrorA file contains an unmatched {{ with no closing }}.
SS-TOK-003WarningA ScriptTokens entry is defined but never referenced anywhere in the package.
SS-TOK-004ErrorA <*File*>/<*BinaryFile*>/<*QueryFile*> ScriptTokens entry points at a file that doesn't exist (or can't be read).
SS-STALE-001ErrorThe committed schema no longer matches what the current domain model would generate — regenerate it.
SS-STALE-002ErrorA committed schema file could not be parsed. It is unusable, so any Extensions governance authored in it was not applied this run.
SS-STALE-003WarningThe 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-001ErrorA 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-003WarningA 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-001WarningA 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.

--TestConnection

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:

  • Connects to the configured server
  • Enforces the product's MinimumVersion floor against the server's detected version

Exit codes: 0 on pass, 2 on any connection failure or version violation.

--PreviewTargets

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.

Not a WhatIf preview

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.

KindleTheForge

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.

When to set it false

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.

ForceReKindle

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.

Safe to run concurrently

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.

Re-kindle without touching config

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.

What SchemaSmith installs in your database

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:

TableWhat it holds
KindleStampOne row: a hash of the helper scripts as installed. Compared at the start of every quench to decide whether kindling has anything to do.
CompletedMigrationScriptsThe run-once record: one row per migration script that has applied, per product and template. See Migration script tracking.
ScriptStampFor 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.
ExpressionMapFor 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.
ProductOwnershipWhich 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.
ChangeAuditA 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.
StatusMessagesThe 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.

Permissions

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.

  • Connects and reads. The pre-flight opens a connection to each configured server's admin database (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.
  • Kindles. Unless KindleTheForge is 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.
  • Uses its own tables. KindleStamp is read on every run; CompletedMigrationScripts is read before each tracked slot and written after each script (see When the record cannot be read or written); ScriptStamp is read before and written after each object script; ExpressionMap is written at the start of the table work, for an existing expression a scratch copy of its table proves unchanged, and again at the end, for what the run applied — a failure at the end is logged, not fatal, while one at the start fails the step; ChangeAudit is written by the procedures and read and cleared by SchemaQuench; StatusMessages likewise.
  • Changes your tables. With UpdateTables on, the procedures create, alter, rename and drop tables, columns, indexes and constraints, and write descriptions and ownership marks on them. What else they execute on MariaDB is below.
  • Runs your scripts. Object, migration, setup and product scripts run as written, under the deploy login. A script that creates a trigger, event, procedure or function needs the engine's right to do so.

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.

Expression change detection

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 movedWhat SchemaSmith does
NothingLeaves the object alone, however differently the two texts read.
Your declarationApplies 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 versionRe-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.

Modular quench procedures

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:

ProcedureResponsibility
TableQuenchThe 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.
BootstrapTableQuenchA minimal create-or-rename-or-add-columns procedure with no dependency on the other helpers; it installs SchemaSmith's own tables during kindling.
MissingTableAndColumnQuenchRenames tables and columns declared with OldName, creates tables that exist in the schema package but not in the database, and adds missing columns.
ModifiedTableQuenchDrops 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.
MissingIndexesAndConstraintsQuenchAdds generated columns, and creates the indexes, check constraints, defaults and full-text indexes the package declares and the database lacks.
ForeignKeyQuenchCreates, modifies and drops foreign keys to match the schema package. Runs late in the sequence so all referenced tables, columns and data exist.
IndexOnlyQuenchAlternative 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:

ProcedureResponsibility
EventQuenchDeclared scheduled events: created, dropped and re-created on change, dropped by absence under DropEventsRemovedFromProduct.
SequenceQuenchDeclared 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.

Calling procedures directly from migration scripts

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.

Parameter reference

TableQuench parameters. The parameters, in declared order. MariaDB has no parameter defaults: the six positional arguments are the whole signature.

ParameterDefault
ProductNameRequired
DatabaseNameRequired (second)
TableDefinitions (JSON)Required
WhatIfRequired
DropUnknownIndexesRequired
DropTablesRemovedFromProductRequired
RebuildPolicyModesession variable
RebuildPolicyThresholdsession variable
RebuildPolicyOnOrderMismatchsession variable
OnlineApplysession 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.

Migration script tracking

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:

ColumnDescription
IdAuto-increment primary key.
ProductNameThe product name from Product.json.
QuenchSlotThe slot the script belongs to.
ScriptPathThe relative path of the script within the template.
template_nameThe template the script ran under.
schema_nameAlways empty — schema templates do not apply on MariaDB.
QuenchDateTimestamp 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.

Execution rules

  • On each quench run, SchemaQuench checks which scripts in each slot have already been recorded.
  • Scripts that appear in the tracking table are skipped.
  • Scripts that don't appear are executed, and on success a tracking entry is inserted.

The [ALWAYS] suffix

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.

Ordering

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

Obsolete entry cleanup

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.

Forcing re-execution

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).

When the record cannot be read or written

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:

  • Cannot read the record. Before a tracked slot runs, SchemaQuench reads which of its scripts are already recorded. On MariaDB, only an absent table reads as “nothing has run yet” — a database that was never kindled, because kindling is switched off. Any other failure, such as a login with no 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.
  • Applied, not recorded. A script that ran but whose row could not be inserted is reported as failed — 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.

Dependency retry loop

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:

  1. Execute all pending (not yet quenched) scripts in the slot.
  2. For each script, attempt to execute all its batches. If any batch fails, record the error and move on.
  3. If at least one script succeeded in this iteration, loop back to step 1 with only the remaining failed scripts.
  4. If zero scripts succeeded in an iteration, the loop terminates.

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.

Unchanged object scripts

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.

A module the engine rewrites is still unchanged

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.

Preserved permissions

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.

Column changes

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.

ChangePathTaken down and put back
Type, character set, collation, nullability, default, comment, ON UPDATE, invisibility, SRIDIn 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 policyFor 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 STOREDDrop and re-add the columnThe 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 changeMariaDB carries a generated column that reads the column across the rename itself.
Removed from the packageDropped under DropColumnsRemovedFromProductForeign keys that reference it first.
Column orderA 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 stopsA 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.

Refused before the change

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.

OnlineApply

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.

ScopeWhere to setDefault
EnvironmentOnlineApply in SchemaQuench.settings.json (or the SmithySettings_OnlineApply environment variable, or --OnlineApply=Prefer on the command line)Off
TableOnlineApply in the table's .jsoninherits the environment
ValueEffect
Off (default)The plain statements, exactly as a deploy has always run them.
PreferThe online form wherever the engine's version allows it, and the plain form otherwise.
RequireThe 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 tableForms asked for
A column addedINSTANT, then INPLACE, LOCK=NONE; the column goes AFTER the declared column before it
A column the package no longer declaresdropped INSTANT, then INPLACE, LOCK=NONE
A column whose definition changesINSTANT, 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 droppedINPLACE, LOCK=NONE
A table whose RebuildPolicy sets OnOrderMismatch, rebuilt only because its columns are out of orderits 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.

Table ownership

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.

ControlWhat it looks at
DropTablesRemovedFromProductA table this product owns that the package no longer declares. A table owned by another product, or by nobody, is never a candidate.
DropIndexesRemovedFromProductAn index this product owns, on a declared table, that the package no longer declares.
DropUnknownIndexesAn 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.
PreventDropThe marker stored with the ownership mark, read even after the table has left the package.
ShouldApplyExpressionA 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.

DropTablesRemovedFromProduct

When DropTablesRemovedFromProduct is true (the default), ModifiedTableQuench drops tables that:

  • Exist in the target database.
  • Aren't defined in any table JSON file in the schema package.
  • Were previously managed by this product.

This keeps the database clean as tables are removed from the schema package over time.

Three-tier cascade

The setting resolves across three tiers — environment → product → template — evaluated from broadest to narrowest:

  • Environment — DropTablesRemovedFromProduct in SchemaQuench.settings.json (or the SmithySettings_DropTablesRemovedFromProduct environment variable). Controls all products deployed in that environment.
  • Product — DropTablesRemovedFromProduct in Product.json. Controls a single product regardless of environment.
  • Template — 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 guidance

EnvironmentSettingRationale
CI and local devtrueCatch product areas that reference tables you plan to remove.
Test/stagingtrueSame rationale, but verify the drop is intentional before promoting to production.
ProductionOften falseDropping a table is a hard drop with no built-in recovery. Teams that need rollback-friendly deployments should leave this off in production.

The rollback-friendly removal pattern

  1. Remove the table from your product definition.
  2. Keep DropTablesRemovedFromProduct: false in the production config.
  3. Write a migration script that renames or archives the table (or verifies no dependencies remain).
  4. After the retention period, either enable the setting for one deployment or add an explicit DROP in a migration script.

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).

Partitioned tables are never dropped by absence

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).

PreventDrop

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": [ /* ... */ ]
}

Sticky by design

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.

Removed, not dropped

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.

Not a cascade flag

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.

Un-protecting a table

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:

  1. Refresh, then remove. Set 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.
  2. Drop via migration script. Migration scripts run outside the drop-by-absence pass, so they are not gated by PreventDrop at all.

Ownership is reconciled every run

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.

Environment-level protection

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.

Per-type drop protection

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.

DropColumnsRemovedFromProduct

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.

DropForeignKeysRemovedFromProduct

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.

DropCheckConstraintsRemovedFromProduct

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.

DropIndexesRemovedFromProduct

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 — the out-of-band case

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 — the environment-only case

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 — the per-table override

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.

RunScriptsTwice

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?"

When to use

  • CI pipelines — Verify that [ALWAYS] scripts are truly idempotent. If a script fails on the second run, you have caught an idempotency bug before it reaches production.
  • Local development — Verify idempotency as you author [ALWAYS] scripts.

When not to use

  • Production deployments — It doubles the execution time for the object script phase with no production benefit. This is a testing tool.

TrackRunOnceMigrations

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.

PruneObsoleteMigrationTracking

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.

With Target scope

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.

Why the scope restriction matters

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 and conditional deployment

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.

Folder-level gating

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.

Where the expression runs

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.

Fails closed on error

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.

Gating on the target version

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.

When each gate is evaluated

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.

GateWhenAgainst
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 folderOnce 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 folderOn 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 blockOnce per database, at the delivery step, before any content file is read.The target database. See Gated deliveries and variants.
A sequenceInside 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 gate that turns off an existing object

Warning

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.

Script-level runtime skip

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.

Sentinel constant

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';

Batch and tracking semantics

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.

Script surface coverage

SurfaceSentinel honored
Before / After scriptsYes
Object scripts (procedures, views, functions)Yes
Migration scriptsYes
[ALWAYS] scriptsYes
Validation scriptsNo — express N/A through conditional logic inside the validation
Tool-generated SQLNo — use ShouldApplyExpression on the component

Exit codes

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.

CodeMeaning
0Successful 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.
1Finished, 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.
2Failed 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.
3Unhandled exception — a defect in the tool. The exception is in both logs; please report it with them.
4Unable to back up log files. The quench itself finished; check permissions and disk space in the log directory.

Engine error codes

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.

FailureCode
Foreign-key violation (orphan)1452
NOT NULL violation1048
Duplicate / unique-key1062
String or binary truncation1406
Type / conversion mismatch1366
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.

Table data delivery

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.

Gated deliveries and variants

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.

Two-pass FK-aware delivery

Foreign keys turn "load the data" into a graph problem, which SchemaQuench solves automatically:

  1. Pass 1 — Tables whose required (NOT NULL) foreign keys all point to already-loaded tables are merged first. Nullable FK columns pointing to tables not yet delivered are deferred — the initial merge inserts rows with those columns NULL so the load doesn't block on a row that doesn't exist yet.
  2. Pass 2 — After every pass-1 table is delivered, each deferred table's nullable FK columns are back-filled by re-merging the same data with only the deferred columns in play.

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.

MergeType options

  • 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.

DataDelivery vs hand-written Table Data scripts

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.

Checkpoint and resume

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.

Enabling resume

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.

Where checkpoints live

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.

Checkpoint scopes

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 nameWhat it covers
ValidateBaselineBaseline validation script.
SequenceQuenchSequence deployment.
ModifiedTablesAltering existing columns, generated columns, dropping tables.
IndexesAndConstraintsCreating missing indexes, check constraints, defaults.
TableDataDeliveryBoth passes of FK-aware data delivery for tables with DataDelivery blocks.
ForeignKeysCreating, modifying, and dropping foreign keys.
EventQuenchScheduled event deployment.
VersionStampVersion 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.

Resuming after the package changed

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:

  • A script you add to a slot runs; a script you rename runs under its new path; a script you edit in place, whose old version had completed, is skipped. A package folder reached by a different SchemaPackagePath — a fresh checkout in another directory, say — matches none of the completed scripts, so each is handled as on a run without --ResumeQuench, while the completed steps, recorded by name, are still skipped.
  • A table step recorded as complete is skipped even if the table JSON has changed since. The steps that add missing tables and columns are never checkpointed, so a column added to the JSON still arrives; a type changed in the JSON does not, because 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.

Automatic cleanup after success

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.

Practical resume workflow

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.

When to leave resume off

  • Normal, clean deployments — The resume flag is opt-in. Without it, every step executes, and at the end the checkpoint files get cleaned up regardless. There's no cost to leaving it off for fast, green runs.
  • CI pipelines that rebuild databases from scratch — Each run is a fresh slate, so resume has nothing to do.

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.

Transactions and atomicity

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.

Deployment summary report

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.

What SchemaQuench writes

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.

Redirecting the report

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.

Tuning bottleneck detection

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.

Best-effort, and written on every exit path

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.

Reading Summary.json

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
}

Top-level fields

KeyMeaning
schemaVersionContract version of the report shape — currently "1.2".
toolAlways "SchemaQuench".
toolVersionThe CLI version that wrote the report — the same string --version prints.
runRun-level facts: product, platform, timing, mode, outcome.
targetsOne entry per (server, database, schema) target the run touched.
migrationScriptsOne entry per migration script that ran.
timingAggregate timing plus the bottleneck outliers.
failuresOne entry per failed scope — the same content as the failure roll-up log.
whatIfThe would-apply / would-skip / would-deliver plan; null unless the run was WhatIf mode.
objectChangesVerified DDL changes and object-script runs — its own section below.
preventDropThe no-drop protection manifest: what the run would have dropped by absence and withheld. null unless the environment's PreventDrop is on.
unsupportedDowngradeFeatures the package declared that the target version couldn't take, emitted in a degraded form and recorded. null when nothing was degraded.

run

KeyMeaning
productThe product name from Product.json.
platformSqlServer, PostgreSQL, MySQL, or MariaDb.
startedUtc / finishedUtcRun start and end, UTC.
durationMsWall-clock milliseconds for the whole run.
modeQuench (a real deploy) or WhatIf (a dry run). A --Validate run writes no report: it exits with its findings before a deployment starts.
outcomeSuccess; 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.
exitCodeThe process exit code the run returned.
resumedFromCheckpointtrue when the run resumed a prior interrupted deployment.

targets[]

KeyMeaning
server / database / schemaThe target's coordinates; schema is null when the target has no schema.
templateThe template that produced this target.
outcomeSuccess, Failed, or Skipped. A target skipped because a TemplateTargets database does not exist and CreateIfMissing is false is listed as Skipped.
durationMsMilliseconds spent on this target.
slots[]Per-slot timing for this target: slot, durationMs, scriptsRun.
databaseSource / schemaSourceWhere 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.

migrationScripts[]

KeyMeaning
pathPackage-relative path of the migration script.
slotThe slot it ran in.
template / schema / server / databaseWhere 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[].

timing

KeyMeaning
totalMsRun 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.

failures[]

Empty on a clean run. Each entry mirrors the failure triage roll-up exactly — same content, same backup directory, no new exposure.

KeyMeaning
phaseThe phase the failure occurred in.
scopeKeyThe failed scope — a tenant, a per-server script, or a product-level phase.
errorThe engine's error text for the failure.
contextTail[]The captured tail of log lines leading up to the failure.
artifactPathPath to the resolved-SQL artifact for the failed scope, when one was written.

whatIf

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.

KeyMeaning
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).

preventDrop

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" }
  ]
}
KeyMeaning
enabledAlways 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.

objectChanges — what actually changed

Verified changes versus scripts that ran

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.

The count buckets

BucketObject types counted
createdtables, 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).
modifiedtables, columns.
droppedtables, indexes, constraints, foreignKeys.
scriptsRanTotal object scripts that ran this run.
scriptsUnchangedTotal object scripts left alone because their text and the module the server renders are both as they were after the last apply.

details[]

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.

instrumented

ValueMeaning
trueThe run's engine produced a real audit read; the counts and details are populated.
falseThe engine couldn't read the audit (for example, kindling was suppressed), so every count is 0 and details[] is empty.

Note

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.

Cross-platform

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.

Why "ran", not "changed"

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.

Shape. Strengthen. Succeed.

Free schema-as-code for SQL Server, PostgreSQL, MySQL, and MariaDB.

The source is on GitHub for anyone to read.

Get Started on GitHub