SchemaSmith Glossary

State-Based Migration

A database deployment approach where you define the desired end-state of your schema, and the tool automatically calculates and applies the necessary changes.

How it works: You describe what your database should look like (declarative), not how to change it (imperative). SchemaSmith compares your definition to the actual database and generates the required DDL.

What it gives you:

• Automatic drift correction
• No need to write ALTER statements
• Git conflicts are easier to resolve

Schema Packages

The folder structure that organizes your database metadata: a Product definition at the root, one or more Templates underneath, and tables stored as JSON files with programmable objects as SQL scripts.

Contains:

• Product.json (platform, deployment order, tokens)
• Template directories with Table JSON + SQL scripts
• Migration scripts for data transformations

Product

A collection of templates with validation rules and deployment ordering. Defines how multiple database schemas are deployed together.

Contains:

• List of templates and their deployment order
• Server validation scripts
• Version stamping configuration
• Script tokens for environment-specific values

Template

A reusable metadata definition representing a database schema. One template can be applied to multiple databases.

Use case: You have 50 customer databases with identical structure. Define one template, and SchemaQuench applies it to all 50 databases in parallel.

Think of a template as a "class" and each database as an "instance" of that class.

Casting

The process of extracting an existing database schema into metadata files. SchemaTongs performs casting.

Terminology:

• "Cast your database" = Extract schema to files
• "Casting" = Schema extraction process

The forge metaphor: Just as a blacksmith casts molten metal into a mold, SchemaTongs "casts" your database structure into structured metadata files.

Quenching

The process of applying metadata to target databases, generating and executing required DDL changes. SchemaQuench performs quenching.

Terminology:

• "Quench your databases" = Deploy schema changes
• "Quenching" = Schema deployment process

The forge metaphor: Just as a blacksmith quenches hot metal to harden it, SchemaQuench "quenches" your metadata into a hardened, production-ready database.

Migration Scripts

SQL scripts that run before or after template updates. Used for tasks that can't be handled by automatic schema comparison.

Common uses:

• Data cleanup before adding constraints
• Data transformations after schema changes
• One-time database housekeeping
• Complex dependency handling

Drift

When a database's actual state differs from the defined metadata. Drift occurs when changes are made directly to a database outside of the normal deployment process.

SchemaSmith handles drift by:

• Detecting differences during deployment
• Automatically correcting drift to match metadata
• Reporting what changes were applied

Script Tokens

Variables that are replaced at deployment time, allowing environment-specific configuration without changing the metadata itself.

Example: Use {{DatabaseName}} in scripts, and it gets replaced with the actual database name during quenching.

Token types:

• Simple value tokens
• File tokens (load content from files)
• Query tokens (execute SQL to get values)

WhatIf Mode

A dry-run mode that performs the full deployment logic — validation, token replacement, DDL generation, dependency resolution — without executing any changes against the database.

Use cases:

• Preview deployment impact before applying
• Validate schema changes in CI/CD pull requests
• Audit what DDL would be generated for a target

Idempotent

An idempotent operation produces the same end result no matter how many times it's run. Applying it once or applying it repeatedly leaves the target system in the same state, so re-running it is never harmful.

Why it matters for schema deployment:

• A script can be applied whether the object it defines already exists or not
• No separate logic is needed to decide between creating and altering
• Removes a class of manual guard checks before every deployment
• You write the script using idempotent syntax; SchemaQuench runs it unchanged and lets the database engine handle whichever case applies

Topological Ordering

Topological ordering is a way of sequencing a set of items so that every item comes after everything it depends on. It applies wherever a dependency graph has to be resolved into a linear sequence before anything can be built or run.

The hard part:

• Most dependency graphs are directed and acyclic, so a valid ordering exists
• A cycle, where two items each depend on the other, has no valid linear order and needs a different strategy, such as deferred constraints or a multi-pass deployment
• Ordering that crosses database boundaries usually isn't inferred automatically and has to be stated explicitly

Fix-Forward

Fix-forward is the practice of resolving a bad deployment by shipping a corrective change forward, rather than reverting the system to its previous state. Instead of rolling back, the fix itself becomes the next deployment.

The trade-off:

• Avoids a rollback, which can be difficult once later changes depend on the new state
• Depends on being able to deploy the correction quickly and reliably
• Carries more risk than rollback if the corrective change hasn't been fully validated