SchemaQuench Walkthrough — MariaDB
Configure a connection, deploy a demo schema, edit a JSON table file to add a column, preview the delta with WhatIf, and apply it to MariaDB — the SchemaQuench cycle in 15 minutes.
By the SchemaSmith Team · Last reviewed
Your declared state is about to harden into a live database.
Prerequisites
You need three things before starting the walkthrough — the SchemaSmith binaries, a MariaDB server you can write to, and the demo schema package this walkthrough drives.
SchemaSmith tools
Get the latest release from the downloads page.
A database server
Run the demo in containers if you have Docker and the .NET SDK, or on your own server if you already run MariaDB. The containers path uses the SchemaSmith repository's Docker Compose file, which starts the demo server for you. To use your own server, see the Use your own server section of the getting-started page, which shows how to deploy the demo databases onto it. If you do, use your own server address and login wherever the steps below show the demo's localhost:3317 and TestUser.
The demo files
Clone the whole repository at the release the downloads page serves, so the demo scripts match the tools you installed. The demo packages live under Demos/, but the helpers that stand them up live in the folders above them, so do not download one folder on its own:
git clone --branch v2.8.0 https://github.com/Schema-Smith/SchemaSmith.git
cd SchemaSmith
The checkout stays on the tagged release, so git prints a "detached HEAD" notice. That is expected and harmless for running the demo.
Step 1: Start the Demo Environment
Run this step to start the MariaDB demo in containers. If you deployed the demo databases onto your own server with the deploy-to-endpoint helper on the getting-started page, you already have what this step produces, so skip to Step 2.
Each platform has its own demo folder under Demos/ with a run-demo launcher, a docker-compose.yml, and a .env credentials file. From the repository root, launch the MariaDB demo:
cd Demos\MariaDB
run-demo.cmd
cd Demos/MariaDB
./run-demo.sh
The launcher runs build-schemaquench.cmd / .sh to compile the SchemaQuench binary (requires the .NET SDK on the host), then docker compose up --build packages that binary into a local Docker image, starts a MariaDB instance on port 3317, and deploys the demo databases using SchemaQuench. The launcher blocks until the completed service exits, which signals the databases are ready. Credentials live in Demos/MariaDB/.env:
| Setting | Value |
|---|---|
| MariaDB | localhost:3317 |
| User | TestUser |
| Password | (see Demos/MariaDB/.env) |
Step 2: Deploy with SchemaQuench
Here's where it gets powerful. Let's deploy — quench — the Northwind schema to a completely empty database on the same server. Your declared state is about to harden into a live database.
From Demos/MariaDB/ (the folder Step 1 leaves you in, or the folder you ran the deploy-to-endpoint helper from), create a SchemaQuench configuration file called quench-deploy.json:
{
"Target": {
"Server": "localhost",
"Port": "3317",
"User": "TestUser",
"Password": "your-password-here"
},
"WhatIfONLY": false,
"SchemaPackagePath": "./Northwind",
"ScriptTokens": {
"NorthwindDb": "NorthwindClone"
}
}
Notice the ScriptTokens section: we're telling SchemaQuench to use NorthwindClone as the database name instead of Northwind. The {{NorthwindDb}} token in the template's scripts resolves to this value at run time. The full token system is documented in the SchemaQuench reference.
Note — How the demo creates NorthwindClone
SchemaQuench deploys into databases that already exist, unless a TemplateTargets entry sets CreateIfMissing, in which case it creates the database first. The demo package does not use that setting. So how does NorthwindClone come into existence on an empty server? The shipped ./Northwind package includes a second template called Initialize, whose Before script runs CREATE DATABASE when the target name doesn't yet exist. That script is what bootstraps the demo on an empty server, whether the server is the Docker demo or your own.
In production you wouldn't ship an Initialize template like this — the target database is already there, provisioned as part of your infrastructure setup. Packages produced by SchemaTongs (like ./my-northwind/ from the SchemaTongs walkthrough) capture database objects, not database creation — pre-create the target database on the server before you quench.
Run the deployment:
schemaquench --ConfigFile:quench-deploy.json
SchemaQuench reads the schema package, connects to the target server, and runs the templates in order. The Initialize template fires first — its Before script creates NorthwindClone if it doesn't yet exist — then the Northwind template deploys all the tables with their columns and indexes, all views, and all stored procedures. Connect to localhost:3317 with any SQL client and you'll find NorthwindClone with the full Northwind schema.
One package. One command. A complete database — built exactly as declared, every time. That's what quenching looks like.
Step 3: Make a Change
Now for the payoff. Let's modify the schema and watch SchemaSmith figure out exactly what needs to change.
Open Demos/MariaDB/Northwind/Templates/Northwind/Tables/Shippers.json (relative to the SchemaSmith repository root). The file declares the current state of the table: columns, indexes, the primary key. Add a new column for tracking email addresses. Insert this entry into the Columns array after the `Phone` column:
{
"Name": "`Email`",
"DataType": "varchar(100)",
"Nullable": true,
"OldName": ""
}
You just declared the desired state: "the Shippers table should have an Email column." You didn't write an ALTER TABLE script. You didn't check whether the column already exists. You described what the table should look like. You decide the shape. The forge handles the rest.
Step 4: Preview and Apply
Now let's see what SchemaSmith will do — without changing your schema. Run SchemaQuench in WhatIf mode by setting "WhatIfONLY": true in a copy of your settings file:
{
"Target": {
"Server": "localhost",
"Port": "3317",
"User": "TestUser",
"Password": "your-password-here"
},
"WhatIfONLY": true,
"SchemaPackagePath": "./Northwind",
"ScriptTokens": {
"NorthwindDb": "NorthwindClone"
}
}
Save this as quench-whatif.json and run:
schemaquench --ConfigFile:quench-whatif.json
In the output, you'll see [WhatIf] entries showing the computed changes. SchemaQuench compared the declared state (your JSON with the new Email column) against the live NorthwindClone database (which has no Email column) and determined that an ALTER TABLE ... ADD is needed. None of your objects were changed. WhatIf does install or update SchemaSmith's own helper schema on the target, the same one a real run uses, so it needs the same permissions. Preview before you commit. Confidence before you deploy.
Now apply it for real. Re-run the original quench-deploy.json from Step 2 — it already has WhatIfONLY: false, so this run actually writes the change:
schemaquench --ConfigFile:quench-deploy.json
SchemaQuench connects to the NorthwindClone database, sees that Shippers is missing the Email column, and adds it. Every other table, view, and procedure is already in sync, so nothing else changes. Exactly the right delta, computed automatically. No more, no less.
Step 5: Verify the Change
Connect to the database with whatever SQL client you prefer and look at the Shippers table:
SELECT `CompanyName`, `Phone`, `Email` FROM `Shippers` LIMIT 1;
The Email column is there, just as you declared it. The file is the truth, the database matches, and your next commit records the change for posterity.