SchemaSmith CLI: install and connect

A schema tool you can’t install — or can’t point at a database — is just a README. So let’s get SchemaSmith onto your machine and talking to a live database, on whatever engine you run.

Get the tools

SchemaSmith ships as four self-contained executables — schemaquench, schematongs, datatongs, and schemashears. No runtime to install, no service to configure. One command and all four are on your PATH. You’ll live in schemaquench for most of this course; the others come out when you extract an existing database (Course 1, Module 4) and when you carve a patch (Course 6).

Windows: choco install schemasmith or winget install SchemaSmith.SchemaSmith. winget installs the x64 build; on an ARM64 machine it runs under emulation.
Linux / macOS: curl -fsSL https://schemasmith.com/dl/install.sh | sh
Any Docker host — nothing to install: docker run --rm schemasmithyfree/schemaquench --version. The multi-arch image (amd64/arm64) on Docker Hub carries the same schemaquench — mount your package folder, hand it the same config, and the container does the quench. Nothing touches your PATH. Made for a CI runner or a locked-down box.

Every other channel — .deb, .rpm, manual download, signature verification — is in the Installation guide. Pick your path, then confirm the install:

schemaquench --version

SchemaQuench - Version: 2.8.0.0

Command not found? The CLI isn’t on your PATH yet — the install guide has the fix per platform. One tool, one check, done.

Curious what a tool does before you’ve told it anything? Run it bare:

schemaquench

SchemaQuench 2.8.0.0 -- deploys a schema package to a database.

Nothing is configured yet, so nothing was run.

Fill in these settings in <install folder>\SchemaQuench.settings.json:
  Target:Server      the server to deploy to
  SchemaPackagePath  the folder that holds your package's Product.json

Or set them as environment variables (SmithySettings_Target__Server=...),
or name your own settings file with --ConfigFile:<path>.

Exit 0. Nothing broke — the tool read the blank settings file it was installed with and told you what it needs. The other three do the same with their own settings. You won’t fill that file in for this course: every lab hands the tool its own settings with --ConfigFile.

Stand up a sandbox

You need a database to connect to — and there are two ways to get one. Pick whichever fits how you work.

Option A — the Docker sandbox. A clean throwaway. The Module 1 lab ships a four-engine sandbox — SQL Server, PostgreSQL, MySQL, and MariaDB, all at once. From the lab’s docker folder:

docker compose up -d
./verify-sandbox.sh

When all four report PASS, you’ve got a learn database waiting on every engine. Spin it up, work the labs, tear it down.

Option B — a server you already run. Got SQL Server, PostgreSQL, MySQL, or MariaDB up already? Skip the containers. Point the lab’s helper at it and it forges the same empty learn database for you:

./deploy-to-endpoint.sh --engine postgres --server your-host --port 5432 --user you --password '…'
# --engine: sqlserver | postgres | mysql | mariadb   (Windows: deploy-to-endpoint.ps1 -Engine … -Server …)

It only ever touches a learn database it stamped — your own databases stay untouched. Then point each engine folder’s connect.settings.json at your host instead of the sandbox.

Docker for a clean throwaway, your own server when you’ve already got one warmed up — either way you land on the same learn database, ready for the forge. Full setup and credentials are in the lab README and the use-your-own-server guide.

Connect — kindle the forge

Here’s the thing: SchemaSmith doesn’t have a “ping” button. It proves a connection by doing the first real piece of work — connecting and kindling the forge. That’s the one-time setup that installs SchemaSmith’s helper routines into a target database. We’ll run a tiny starter package that has no tables yet, just to make first contact.

From the lab’s sqlserver folder (or postgres, or mysql):

schemaquench --ConfigFile:connect.settings.json

Watch the log. The lines that matter:

localhost,11433 (…) connection succeeded
Validate Server
Locate Databases To Quench (localhost,11433)
[localhost,11433].[learn] Begin Quench
[localhost,11433].[learn]   Kindling the forge
[localhost,11433].[learn] Successfully Quenched
Completed quench of LearnConnect

There’s your proof. SchemaSmith connected, validated the server, found the learn database, and kindled the forge. No tables in the package yet, so nothing else deployed — exactly right. Run the other engine folders and you’ll see the same three-act story with different connection details: SQL Server, PostgreSQL, MySQL, MariaDB — same flow.

That starter package isn’t throwaway. It’s the anvil for Module 2 — next time, you’ll lay your first table on it and quench it for real.

What the forge leaves in your database

Kindling isn’t invisible, and a DBA inventorying learn will spot it. On SQL Server and PostgreSQL there’s a SchemaSmith schema; on MySQL and MariaDB, which have no schemas inside a database, the same objects carry a SchemaSmith_ prefix. Most of it is helper procedures and functions — the machinery a deploy calls. The tables are the part worth knowing by name, because they’re SchemaSmith’s memory:

Table	What it remembers	Safe to clear?
`CompletedMigrationScripts`	which run-once scripts have already run	No. Clear it and every run-once script runs again.
`ProductOwnership`	which product owns which table, and its `PreventDrop` flag (SQL Server keeps most of that in extended properties instead)	No. It’s how a deploy knows what’s yours to drop and what belongs to someone else.
`ScriptStamp`	what each view, function, procedure and trigger script last left behind, so an unchanged one isn’t re-run	Yes — the next deploy re-runs each object script once.
`ExpressionMap`	what each check, default and computed expression was written as, and what the engine stored	Yes — the next deploy verifies instead of rebuilding (Course 12, Module 5).
`KindleStamp`	which version of the helpers is installed	Yes — the next deploy re-kindles.
`ChangeAudit`	what this run changed, read back for the deployment summary	Yes — each run empties its own rows when it’s done.

MySQL and MariaDB add one more, SchemaSmith_StatusMessages: those engines’ procedures can’t print, so they leave their log lines there for the run to read. The short version: the two that record decisions — what already ran, what’s yours — are the two you leave alone.

Check yourself: What two things must be true before SchemaQuench can deploy to a target?

The CLI is installed and on your PATH, and it has a working connection — host, port, and credentials — to the target database.

Tools on your PATH, a forge kindled on every engine you care about. That’s the cold, fiddly part behind you — from here on, it’s shaping metal.

Hit a snag getting installed or connected — a stubborn PATH, a connection that won’t take? Email me at forgebarrett@schemasmith.com — I read every one.

Next up: Module 2 — Your first schema package. We declare a table and quench it into being.

Until then, may your forge light on the first strike and your connection hold true.

— Forge

Mark this lesson complete