SchemaSmith organizes database schema as declarative packages that deploy predictably. Explore the concepts that make schema version control possible.
SchemaSmith centers on one artifact: the schema package. A package is a folder (or zip file) containing everything needed to version, validate, and deploy schema changes across SQL Server, PostgreSQL, or MySQL. Inside that package lives a declarative model — tables expressed as JSON, migration scripts organized by execution slot, configuration that controls deployment behavior, and script tokens that inject environment-specific values at deploy time.
The concepts here cluster into three natural axes. First is what you declare: schema packages (the container), products (deployment units inside the package), templates (reusable schema definitions), and tables (the JSON-based table model). Second is how it deploys: migration scripts with slot-based ordering, script tokens for dynamic substitution, and rollback mechanics that let you recover from a release when you decide one is needed. Third is how it's configured: configuration loading order (CLI, environment, files), environment variables (the SmithySettings_* convention), logging (structured output for CI integration), and exit codes (for automation handoff).
A reading path for newcomers: schema packages → products & templates → defining tables → script tokens → configuration loading → environment variables → migration scripts → logging → rollback & recovery. Start with the structure (what's in a package), then the schema model (how tables are declared), then the deployment mechanics (scripts and tokens), then operations (configuration and logging). Rollback comes last because it's the recovery lens on concepts you've already learned.
Each concept has its own deep-dive reference page. Pick by topic or follow the recommended reading order.
The folder and zip organization of a schema package. What each directory contains, how the package travels through source control and deployment, and how it's portable across platforms.
What a Product is (a deployment unit inside a package) and what a Template is (a reusable schema definition). How they relate to each other and how they compose within the package structure.
How to declare tables in the JSON schema format. Columns, indexes, foreign keys, constraints, and extensions — the declarative model that version-controls your schema.
Declare a table's reference data once — source rows, merge behavior, key columns — and let SchemaQuench merge it in foreign-key order across every platform.
The {{Token}} substitution system for environment-specific values. How tokens are defined, resolved at deploy time, and used inside SQL scripts for dynamic configuration.
ShouldApplyExpression scopes schema components to specific databases, environments, or server versions. One file, many targets, no per-environment branching.
One config spine across all three tools: CLI switches, settings files, environment variables, connection configuration. Override rules and precedence for multi-environment deployments.
The SmithySettings_* environment variable convention for overriding settings without editing files. Common in CI/CD pipelines and containerized deployments.
Run-once vs. run-every-deploy script tracking. Slot ordering (Before, Objects, AfterTablesObjects, After) and how scripts execute in dependency order across releases.
Partial-package deployments that run migration scripts only — backfills, compliance scrubs, emergency repairs — without touching table structure or tracking state.
Log file location, structured log format for parsing, and exit codes for CI integration. How to monitor deployments and automate downstream workflows based on outcomes.
Recovering from a schema release. Declarative rollback declarations let you re-deploy a previous release when you decide one is needed — rolling back is always your call, never automatic.