Glossary
SchemaSmith speaks blacksmith. Here’s the full decoder: the forge word, what it actually means, and the tool or setting where you’ll meet it. Lessons link here the first time a term shows up, so there’s nothing to memorize — just somewhere to look.
| Forge word | What it means | Where you’ll meet it |
|---|---|---|
| Forging | Building and managing your schema with SchemaSmith — the whole craft | The toolkit as a whole |
| Casting | Extracting an existing database’s schema into editable, source-controllable files | SchemaTongs |
| Object list | The extraction whitelist — name the objects you want cast and SchemaTongs takes exactly those, leaving everything else (a migration tool’s history table, say) behind by omission | ShouldCast.ObjectList (a SchemaTongs setting) |
| Adopt | What the first quench does to tables that already exist on the target — stamps them as managed and stands up its own bookkeeping, without dropping or recreating them; the next run is a clean no-op | SchemaQuench, on an existing database |
| Quenching | Deploying your declared schema to a live database and hardening it into place | SchemaQuench |
| Data delivery | Shipping the rows that ride along with schema — lookup, seed, and reference data | DataTongs |
Content file (.tabledata) | A JSON array of rows that a table’s DataDelivery block points at; SchemaQuench MERGEs it into the table on deploy | DataDelivery.ContentFile |
| Merge type | How delivered rows reconcile with the target: Insert (add missing), Insert/Update (add + update changed), Insert/Update/Delete (full sync) | DataDelivery.MergeType |
| Kindling | First-time setup that installs SchemaSmith’s helper routines into a target database | KindleTheForge (a SchemaQuench setting) |
| Product | One Product.json package — the unit you decompose a deployment into; named, with its own templates and guardrails | Product.json |
| Common product | The product holding the shared parts every server needs, deployed everywhere so they’re defined once and never duplicated | Product.json |
| Jig (blueprint) | The definition of what a deployment targets — which server, which databases | Product.json |
| Validation script | The deployment guardrail — a SQL check that must pass or the quench aborts before touching anything | ValidationScript (a Product.json setting) |
| Server role | A server’s job — OLTP app, reporting, ETL, DBA admin — used as the line you decompose products along | The Product.json per role |
| Template | One reusable schema definition — tables, indexes, scripts — that a single quench run deploys to many targets at once | Template.json |
| Molds (forms) | Reusable schema definitions deployed across many databases or schemas in one run | Templates |
| Fan-out | One template definition deploying to many targets — every database or schema its identification scripts discover — in a single run | Templates |
| Schema template | A template carrying a SchemaIdentificationScript, so it fans out across schemas — one deployment per discovered schema | SchemaIdentificationScript (a Template.json setting) |
| Database identification script | A SQL query returning database names; the template deploys into every database it returns | DatabaseIdentificationScript (a Template.json setting) |
| Schema identification script | A SQL query returning schema names, run inside each target database; the template fans out into every schema it returns | SchemaIdentificationScript (a Template.json setting) |
{{SchemaName}} | The per-iteration token a schema template resolves to the current schema’s name, so one table file lands in every discovered schema | Schema-template scripts and tables |
| Tenant / multi-tenant | A customer (or workspace) given its own schema inside a shared database; multi-tenant fan-out deploys one workspace definition into every tenant’s schema | Schema templates |
ShouldApplyExpression | A per-target gate evaluated at deploy time — a boolean predicate on an object, or a scalar SELECT on a script folder; true deploys it, false skips it | object & folder conditional deployment |
Sentinel (SCHEMASMITH: SHOULD NOT APPLY) | The exact message a script raises to tell SchemaQuench “skip me” — an intentional skip, not a failure — for decisions a script can only make while running | per-script conditional deployment |
| Run-once migration script | A .sql file in a template script slot (Before Scripts, After Scripts, …) that SchemaQuench runs once per database and records, so it never replays — your data fixes and one-time backfills, tracked for you | CompletedMigrationScripts (the tracking table) |
[ALWAYS] tag | A marker in a script’s filename that opts it out of run-once tracking, so it runs on every quench — for things that must re-run, like a stats refresh or a re-grant | Script filenames in any slot |
| Adjustable dyes | Values resolved per target, so one package fits dev, test, and prod without edits | Script tokens |
| Script token | A {{TokenName}} placeholder in a script, resolved per run — from package defaults, a settings-file override, or an environment variable | ScriptTokens (in Product.json / Template.json / settings) |
| Query token | A token whose value is computed at deploy time by running SQL against the target server, so it’s always current for the server it lands on | <*Query*> (a ScriptTokens value) |
{{TableSchema}} | A system-provided token holding the full JSON of every table in the current template — columns, types, indexes, and custom metadata — for scripts that read your own model | Template scripts |
Custom property (Extensions) | Your own metadata attached to any schema object — classification, owning team, retention, anything — consumed as a token in an expression or read from {{TableSchema}} in a script | Extensions (on a table/column/index/etc.) |
| Maker’s mark | The product name that stamps and identifies your deployment | The product name in Product.json |
| Strike | Applying a single change to a target | General narration |
| WhatIf | A preview run that reports exactly what a quench would change — the diff — without touching the target; the gate a pipeline runs on every change | WhatIf (a SchemaQuench setting) |
| Pipeline | The automated path a change travels from commit to deployed — review, CI checks, and promotion across environments — without anyone running steps by hand | Team workflow & CI |
| Promotion | Moving the same reviewed package forward through environments in order — dev, then staging, then prod — rather than rebuilding it per environment | Team workflow & multi-environment |
| Artifact | A built, versioned schema package in source control — the exact thing that gets deployed and, for rollback, re-deployed | Source control & deployment |
| WhatIf-in-PR | The CI pattern of running a WhatIf preview on every pull request that touches schema — the full deploy logic runs against a database and the change is reported, but nothing is applied, so a change that can’t deploy fails the PR check before it merges | CI/CD pipeline |
| Approval gate | A pause in the pipeline where a human signs off before the next step runs — typically before the production deploy, after staging and tests are green | CI/CD pipeline |
| Env-var config | Supplying any setting through an environment variable (prefix SmithySettings_, __ for nesting) instead of a file, so one built artifact deploys to every environment with only the env vars changing | SmithySettings_* environment variables |
| Rollback | Returning a database to a prior release’s state by deploying that release’s package — SchemaQuench computes the reverting delta, so there are no separate undo scripts to write or run | Rollback & recovery |
| Transactional DDL | Whether an engine lets schema-change statements participate in a transaction so a failed batch unwinds as a unit — PostgreSQL fully, SQL Server for most statements, MySQL not at all (each DDL auto-commits) | Engine behavior during a deploy |
| Data-preservation script | A migration script you run before a rollback to copy out data that a dropped column or table would otherwise destroy — SchemaSmith reverts structure; you handle the data when an operation is destructive | Rollback & recovery |
| Recyclebin | A soft-drop safety net: instead of destroying a table a rollback removes, SchemaQuench moves it aside with its data and restores it automatically if the table reappears in a later release — until a retention window purges it | Rollback & recovery (CustomTableDrop / CustomTableRestore) |
| Zero-downtime | A schema change applied as a sequence of individually-safe steps so the application keeps serving throughout — no maintenance window, no lights out | Multi-environment & live changes |
| Expand/contract | The zero-downtime pattern for changing a column without downtime: add the new column, backfill it, switch the app’s reads/writes, then drop the old — each step independently safe | Live column changes |
| Backfill | Copying existing data into a newly-added column (e.g. UPDATE … SET new = old) so the new column is populated before anything depends on it | Expand/contract step 2 |
New term in a lesson that isn’t on the anvil yet? Tell me — forgebarrett@schemasmith.com — and I’ll add it.
— Forge