Configuration

SchemaSmith is flexible about how you pass switches — pick whichever style feels natural. All switches accept either a double-dash (--) or forward-slash (/) prefix. Separate the switch name from its value with : or =. A single leading dash (-) also works.

--switch:value
--switch=value
/switch:value
-switch:value

Switch names are case-insensitive — --logpath, --LogPath, and --LOGPATH all do the same thing.

Values that contain spaces must be quoted:

--ConfigFile:"C:\configs\my config.json"
/LogPath:"C:\My Logs\SchemaSmith"

Flags that take no value (like --version or --help) are specified without a separator.

SchemaSmith layers configuration so you can set sensible defaults in a file and override just the pieces that change per environment. Later sources override earlier ones. The full chain, from lowest to highest priority:

1. Settings file — <ToolName>.settings.json
2. User secrets — .NET user secrets (debug builds only, not present in release builds)
3. Environment variables — prefixed with SmithySettings_
4. CLI switches — the named switches (--ConnectionString, --ConfigFile, --LogPath) and any --Key=value override (see below)

This means a value set in the settings file can be overridden by an environment variable, and a CLI switch always wins.

Override example

Suppose your SchemaQuench.settings.json sets the server:

{
    "Target": {
        "Server": "dev-server"
    }
}

You can override just the server for a single run using an environment variable:

• Windows
• macOS / Linux

$env:SmithySettings_Target__Server = "staging-server"
SchemaQuench

export SmithySettings_Target__Server=staging-server
SchemaQuench

Or override the entire connection from the command line:

SchemaQuench --ConnectionString:"Host=prod-server;\
    Database=mydb;Username=deploy;Password=s3cret;"

The --ConnectionString switch bypasses all individual connection settings — Server, Port, User, Password, and ConnectionProperties are all ignored when a full connection string is provided.

Overriding any setting

Beyond the named switches, any configuration option can be set or overridden from the command line with a --Key=value switch. This is the same override reach the SmithySettings_ environment variables give you, without touching a file or exporting a variable — ideal for CI and one-off runs.

The rule mirrors the environment-variable grammar exactly: an = separates the key from the value, and a double underscore (__) nests into the configuration hierarchy. Whatever you'd write after SmithySettings_ you write after -- — so every row in the environment variables table has a command-line twin:

• Windows
• macOS / Linux

# Override just the server and skip cert validation for a single run
SchemaQuench --Target__Server=staging-db `
             --Target__ConnectionProperties__TrustServerCertificate=true

# Override just the server and skip cert validation for a single run
SchemaQuench --Target__Server=staging-db \
             --Target__ConnectionProperties__TrustServerCertificate=true

A --Key=value override sits at the top of the hierarchy above — it wins over the settings file, user secrets, and environment variables.

Two things to keep in mind:

• The = is required for an override. The named switches (--LogPath, --ConfigFile, --ConnectionString) accept a : separator, but nesting into arbitrary settings needs the __/= form so a value containing a colon (a Windows path, a host:port) is never mistaken for a key boundary.
• --ConnectionString still bypasses the individual connection settings. If you pass both --ConnectionString and a --Source__Server= / --Target__Server= override, the full connection string wins for connecting.

Environment variables give you a clean way to inject configuration without touching files on disk — exactly what you need in CI/CD pipelines and containers. All three tools read environment variables prefixed with SmithySettings_. The prefix is stripped, and double underscores (__) map to hierarchy separators in the configuration structure.

Mapping rules

The prefix SmithySettings_ maps to the root of the config tree; each __ becomes a : hierarchy separator. Example: SmithySettings_Target__Server → Target:Server → { "Target": { "Server": "..." } }.

SchemaTongs and DataTongs use Source instead of Target for their connection section, so the equivalent variables start with SmithySettings_Source__:

• Windows
• macOS / Linux

# SchemaQuench connection
$env:SmithySettings_Target__Server = "myserver"
$env:SmithySettings_Target__Password = "s3cret"

# SchemaTongs / DataTongs connection
$env:SmithySettings_Source__Server = "myserver"
$env:SmithySettings_Source__Password = "s3cret"

# SchemaQuench connection
export SmithySettings_Target__Server=myserver
export SmithySettings_Target__Password=s3cret

# SchemaTongs / DataTongs connection
export SmithySettings_Source__Server=myserver
export SmithySettings_Source__Password=s3cret

Environment variables are especially useful in CI/CD pipelines and containers where you don't want secrets in files on disk.

Your credentials stay out of the logs. When a tool logs its resolved command-line switches and its active configuration at startup — and when SchemaQuench logs its product and template script tokens — it scrubs any value whose name matches a built-in sensitive-name set, so a log is safe to attach to a support ticket, paste into a CI artifact, or drop into a screenshot.

Switches are scrubbed on the same rules as configuration values: a --Target__Password=... or --ConnectionString=... renders its value as *** while the switch name still prints, so you can confirm what was passed without exposing it. See Startup configuration dump for the full startup output.

The default sensitive-name patterns (case-insensitive, substring match) are Password, Pwd, Secret, ApiKey, Token, ConnectionString, and Credential. A matched value renders as *** while its name still prints, so you can confirm the setting exists without exposing it. An embedded Password= / Pwd= inside a connection-string value is stripped even when the surrounding setting or token is not sensitively named — one leaked connection string is one too many.

A credential inside a URL is also masked. A value shaped like scheme://user:secret@host/path has its password replaced with ***, regardless of the setting name. The username, host, port, and path remain visible, so the log stays diagnosable.

All other values are logged as-is, so you can audit the active configuration from the log. Both exceptions match on the shape of the value rather than its name, so they apply even where you have not told SchemaSmith the value is sensitive.

Configuration:
    Server: myserver
    Port: 5432
    User: deploy
    Password: ***
    ConnectionProperties:
      SslMode: Prefer

Tuning the scrubbing

An optional LogHygiene block in any tool's *.settings.json tunes the behavior. With no block present, the defaults above apply.

"LogHygiene": {
  // Suppress the token-logging section entirely -- one notice line, no token
  // names and no values. For products with hundreds of tokens. Default: true.
  "LogTokens": true,

  // Scrub these exact token names too, beyond the default patterns.
  "ScrubTokens": [ "Handshake", "TenantSeed" ],

  // Extra contains-match patterns (the * is optional).
  "ScrubPatterns": [ "*Salt*", "*PrivateKey*" ],

  // Opt a false positive back out -- log this name verbatim even though it
  // matches a default pattern (e.g. a column literally named "Token").
  "AllowTokens": [ "PublicToken" ]
}

When a token name appears in both AllowTokens and a scrub rule, AllowTokens wins and the value is logged verbatim — but an embedded connection-string password is still stripped.

SchemaSmith removes database objects that no longer appear in the schema package — drop-by-absence — under a family of flags. Most of the Drop…RemovedFromProduct flags compose across tiers — environment → product → template — with the environment tier living here in SchemaQuench.settings.json as a deployment-wide guardrail, independent of any package. The column, foreign-key, check-constraint, exclude-constraint, statistics, index and period flags add a per-table tier; DropTablesRemovedFromProduct and DropUnknownIndexes stop at the template tier. Two sit outside that shape entirely and are covered in their own paragraphs below: DropPeriodsRemovedFromProduct skips the product and template tiers, and DropEventsRemovedFromProduct is environment-only. The PreventDrop row is not part of that cascade: this environment-level form has no Product.json or Template.json tier. The per-table PreventDrop, set in a table's own .json, is a separate control — see below.

Each flag is also settable as an environment variable using the standard prefix — SmithySettings_<FlagName>, for example SmithySettings_DropUnknownIndexes.

DropPeriodsRemovedFromProduct departs from that pattern on both counts. It resolves environment → table — there is no product or template tier — and it defaults to false. That off default is deliberate: a package with no Periods entry is not necessarily asserting that the table has no period. Packages written before periods were supported have no such entry, and neither does one extracted from a MariaDB version whose catalog cannot report periods at all. Defaulting to drop would delete a period on the strength of a silence that means nothing. Turn the flag on when your package is genuinely the authority on the table's periods, or set it on a single table to override the environment setting for that table alone. Dropping a period does not touch your data — the columns it spanned keep everything in them.

DropEventsRemovedFromProduct is the other Drop…RemovedFromProduct flag that defaults to false, and it departs further still: it is a single environment tier. Events live in a template’s Events/ folder rather than under a table, so there is no per-table level to cascade from. It is not a package property and appears in no generated .json-schemas file, so leaving it in a Product.json or Template.json has no effect on a deploy but makes --Validate report an unexpected property (SS-JSON-001, Error) and exit 2. Event removal reaches only events SchemaSmith created — one made by hand, or by a scripted Events/ file, is never touched.

A false at any tier is sticky: it locks the effective value to false for all lower tiers and cannot be re-enabled by a more-specific setting. Absent inherits from the tier above; a true at a lower tier overrides an inherited true but never an ancestor's explicit false. For the flags that expose a per-table tier, a table's own .json can only tighten (set its own false to protect its objects); it can never re-enable a drop a higher tier suppressed.

The environment tier for DropUnknownIndexes is new in this release — previously it was settable only in Product.json and Template.json. Its default is false at every tier, so index-drop-by-absence stays off unless you opt in.

PreventDrop is the blanket. Set it true here (or via SmithySettings_PreventDrop) and the environment never drops an object for being absent from the product — every pass above is suppressed for the whole run, regardless of what any package, template, or table declares. The run still completes normally with exit code 0: SchemaQuench applies every additive and modifying change, logs each drop it withheld, and itemizes them in the deployment summary's preventDrop manifest. Only removal by absence is held back — an object that is still declared but must be dropped and recreated to apply a change reconciles as usual.

A separate per-table PreventDrop boolean, set in a table's .json, protects one named table. Its persistence is a different mechanism from the cascade's sticky false above: SchemaSmith stores the marker in its ownership tracking inside the database, so the protection survives the table leaving the package entirely. For what each flag governs, both PreventDrop layers, the recyclebin-friendly removal pattern, and per-platform behavior, see Drop control and the SchemaQuench reference.

Common invocation patterns for the scenarios above. Copy, paste, adjust the server and credential values for your target.

• Windows
• macOS / Linux

# Run with defaults (settings file in current directory or tool directory)
SchemaQuench

# Custom config file
SchemaQuench --ConfigFile:staging.json

# Custom log directory
SchemaQuench --LogPath:C:\Logs\quench

# Override connection via environment
$env:SmithySettings_Target__Server = "prod-db"
$env:SmithySettings_Target__User = "deploy"
$env:SmithySettings_Target__Password = "s3cret"
SchemaQuench

# Override connection via CLI (platform-appropriate connection string)
SchemaQuench --ConnectionString:"Host=prod-db;`
    Database=mydb;Username=deploy;Password=s3cret;"

# Force a full helper re-kindle (re-install SchemaSmith objects)
SchemaQuench --ForceReKindle

# Environment guardrail: never drop unknown indexes
$env:SmithySettings_DropUnknownIndexes = "false"

# Run with defaults (settings file in current directory or tool directory)
SchemaQuench

# Custom config file
SchemaQuench --ConfigFile:staging.json

# Custom log directory
SchemaQuench --LogPath:/var/log/quench

# Override connection via environment
export SmithySettings_Target__Server=prod-db
export SmithySettings_Target__User=deploy
export SmithySettings_Target__Password=s3cret
SchemaQuench

# Override connection via CLI (platform-appropriate connection string)
SchemaQuench --ConnectionString:"Host=prod-db;\
    Database=mydb;Username=deploy;Password=s3cret;"

# Force a full helper re-kindle (re-install SchemaSmith objects)
SchemaQuench --ForceReKindle

# Environment guardrail: never drop unknown indexes
export SmithySettings_DropUnknownIndexes=false