SQL Server Walkthrough

SchemaQuench Walkthrough — SQL Server

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 SQL Server — the SchemaQuench cycle in 15 minutes.

Prerequisites Start the demo environment Deploy with SchemaQuench Make a change Preview and apply
SchemaQuench: declarative deployment for SQL Server

Your declared state is about to harden into a live database.

Prerequisites

You need three things before starting the walkthrough — the SchemaSmith binaries, a SQL Server you can write to, and the demo schema package this walkthrough drives.

SchemaSmith tools

Download self-contained ZIP packages from the latest GitHub release and extract them anywhere on your PATH. No .NET runtime required.

A database server

Either an existing SQL Server instance or Docker (recommended). The SchemaSmith repository includes a Docker Compose file that starts the demo server for you.

The demo files

Clone the repository or download just the Demos/ folder:

git clone https://github.com/Schema-Smith/SchemaSmithyFree.git
cd SchemaSmithyFree

Step 1: Start the Demo Environment

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 SQL Server demo:

cd Demos\SqlServer
run-demo.cmd
cd Demos/SqlServer
./run-demo.sh

The launcher runs build-schemaquench.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 SQL Server instance on port 1440, 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/SqlServer/.env:

Setting Value
SQL Server localhost,1440
User TestUser
Password (see Demos/SqlServer/.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.

Create a SchemaQuench configuration file called quench-deploy.json:

{
  "Target": {
    "Server": "localhost,1440",
    "User": "TestUser",
    "Password": "your-password-here"
  },
  "WhatIfONLY": false,
  "SchemaPackagePath": "./demo/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 — SchemaSmith migrates, it doesn't create databases

SchemaQuench migrates schemas onto existing databases — it doesn't create databases itself. So how does NorthwindClone come into existence on an empty Docker demo? The shipped ./demo/Northwind package includes a second template called Initialize with a Before script that runs CREATE DATABASE if the target name doesn't yet exist. That script is the bootstrap for the empty Docker demo.

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,1440 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 demo/Northwind/Templates/Northwind/Tables/dbo.Shippers.json. 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": "NVARCHAR(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 actually touching the database. Run SchemaQuench in WhatIf mode by setting "WhatIfONLY": true in a copy of your settings file:

{
  "Target": {
    "Server": "localhost,1440",
    "User": "TestUser",
    "Password": "your-password-here"
  },
  "WhatIfONLY": true,
  "SchemaPackagePath": "./demo/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. No changes were applied — WhatIf mode is read-only. 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 dbo.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 TOP 1 [CompanyName], [Phone], [Email] FROM [dbo].[Shippers];

The Email column is there, right where you declared it. The file is the truth, the database matches, and your next commit records the change for posterity.

The SchemaQuench Cycle

You just ran the SchemaQuench leg of the SchemaSmith workflow:

  1. Deploy. SchemaQuench built a complete database from the declared schema package, reproducibly.
  2. Change. You edited a JSON file to declare a new column.
  3. Preview. WhatIf mode showed you the computed change without touching the database.
  4. Apply. SchemaQuench made the target match the declared state, changing only what needed to change.
  5. Verify. You connected to the database and confirmed the declared state matched reality.

No migration scripts. No ordered chains of ALTERs. No guessing what the target looks like. You declare the state you want, and SchemaSmith gets you there. Every time.

Last reviewed May 2026 by the SchemaSmith Team.

What's Next

What's Next

You just did state-based schema deployment. The natural next step is bringing reference data along with the schema through DataTongs. The third leg of the workflow — extracting a live database into version-controlled files with SchemaTongs — is one step back if you haven't worked through it yet.