Module 3 — Change it and redeploy

🧪

Hands-on lab

Run this module yourself — the `before/` source, the three-engine sandbox, and the worked solution to diff against.

Demos/Learn/module-03 →

Schemas never sit still. The Widget you built last module already needs more — a wider name, a price column. The old way: hand-write an ALTER TABLE, guard it so it doesn’t blow up if it’s already run, figure out whether prod is even in the state your ALTER expects, and slot one more script onto the pile. Let’s not. Let’s change the declaration, see exactly what SchemaSmith would do, and then let it do it.

Reshape the declaration

You don’t write the change. You change the shape you want and let the forge work out the change. Open the Widget table from Module 2 and edit two things — widen Name to 200, and add a Price column:

{
  "Schema": "dbo",
  "Name": "Widget",
  "Columns": [
    { "Name": "WidgetId", "DataType": "BIGINT" },
    { "Name": "Name", "DataType": "NVARCHAR(200)" },
    { "Name": "Quantity", "DataType": "INT", "Nullable": true },
    { "Name": "Price", "DataType": "DECIMAL(10,2)", "Nullable": true }
  ],
  "Indexes": [
    { "Name": "PK_Widget", "PrimaryKey": true, "Clustered": true, "IndexColumns": "WidgetId" }
  ]
}

That’s the whole edit. No ALTER TABLE, no IF COL_LENGTH(...) guard, no migration number. You changed 100 to 200 and added one line. The file still describes the destination — it just describes a slightly bigger one now. PostgreSQL and MySQL are the same edit with their own type names (the lab has all three).

Preview it first — WhatIf

Here’s the part that changes how you deploy. Before you touch the database, you can ask SchemaSmith: what would you do? That’s WhatIf — a dry run. It computes the exact difference between your file and the live table and prints the SQL it would run, but applies none of it.

The lab ships a whatif.settings.json that’s identical to your deploy config with one line flipped — "WhatIfONLY": true. Run it:

schemaquench --ConfigFile:whatif.settings.json

[localhost,11433].[learn]       ALTER TABLE [dbo].[Widget] ADD [Price] DECIMAL(10,2) NULL;
[localhost,11433].[learn]       ALTER TABLE [dbo].[Widget] ALTER COLUMN [Name] NVARCHAR(200) NOT NULL;
[localhost,11433].[learn] Successfully Quenched

There it is — the two statements SchemaSmith worked out on its own, printed among the run’s [WhatIf] markers before a single byte of the table moves. (PostgreSQL prints ADD "Price" NUMERIC(10,2) and ALTER COLUMN "Name" SET DATA TYPE VARCHAR(200) — DECIMAL and NUMERIC are the same type there. MySQL prints ADD COLUMN \Price` DECIMAL(10,2) NULLandMODIFY COLUMN `Name` VARCHAR(200) NOT NULL`.)

And the table itself? Untouched. Check it and Name is still 100, with no Price in sight. WhatIf looked, did the math, told you the plan — and left the metal cold. Review the diff, and when it’s what you meant, deploy for real. Every setting behind WhatIf is in the SchemaQuench reference.

Quench the change

Same package, the deploy config this time:

schemaquench --ConfigFile:deploy.settings.json

[localhost,11433].[learn]         Adding 1 new columns to [dbo].[Widget]
[localhost,11433].[learn]         Altering Column [dbo].[Widget].[Name]
[localhost,11433].[learn] Successfully Quenched
Completed quench of LearnConnect

Exactly the two changes WhatIf promised — no more, no less. The column’s added, the type’s widened, the primary key never moved. Run it again and you get silence: the declared state matches the database now, so the difference is zero. That’s the quench converging your table to the shape you drew.

Compare that to the migration way. There, evolving this table means writing the ALTER yourself, knowing precisely what state the target’s in, and adding script 006 to a chain you have to keep ordered forever. Here, you edited a file and previewed the result. SchemaSmith wrote the ALTER, checked the target for you, and applied only the gap.

Check yourself: What does WhatIf give you that running the deploy directly does not?

A preview of exactly the changes SchemaSmith would make, computed against the live database but without touching it — so you can review the diff before you apply.

---

Change the file, preview the diff, quench the difference. That’s the whole loop, and it’s the thing that makes declarative click: you never hand-write the change, and you never deploy one you haven’t seen first.

Got a gnarly table change you’re not sure how SchemaSmith would handle? Email me at forgebarrett@schemasmith.com — I read every one.

Next up: Module 4 — Bring an existing database under management. We flip the whole flow around — point SchemaTongs at a database that’s already out there and cast it into a package you can manage.

Until then, may every change ring true and your previews never surprise you.

— Forge

Mark this lesson complete