Course 3 · Module 1 — Team workflow & code review

A teammate adds a column to the Customer table and drops a migration script in the queue: ALTER TABLE Customer ADD LoyaltyTier NVARCHAR(20) .... You’re the reviewer. Staring at that one line, can you tell whether the column lands next to the right neighbors? Whether it collides with an index? Whether some foreign key three columns over cares? You can’t — not without opening the live schema in another window and rebuilding the whole table in your head. That’s not review. That’s archaeology.

Here’s the better way: review the desired state, not the script that gets there.

The change is a diff, not a script

Your schema lives in source control as files. So when a teammate adds LoyaltyTier, the change isn’t a fresh imperative script bolted onto a pile — it’s an edit to the table’s definition. One file, one Customer.json, and the pull request shows it as a plain diff:

"Columns": [
  { "Name": "CustomerId", "DataType": "INT IDENTITY(1,1)" },
  { "Name": "Name", "DataType": "NVARCHAR(100)" },
  { "Name": "Email", "DataType": "NVARCHAR(200)" }
  { "Name": "Email", "DataType": "NVARCHAR(200)" },
  { "Name": "LoyaltyTier", "DataType": "NVARCHAR(20)", "Nullable": true, "Default": "N'Standard'" }
],
"Indexes": [
  { "Name": "PK_Customer", "PrimaryKey": true, "Clustered": true, "IndexColumns": "CustomerId" }
]

Look at what the reviewer gets for free. The new column sits right next to its neighbors. The primary key is two lines down. If there were an index touching this column, or a foreign key, they’d be in the same file, in view, in context. The reviewer isn’t asked “will this script execute?” — they’re asked the question that actually matters: “is this the right design?”

Now picture the same change as an ALTER:

ALTER TABLE Customer ADD LoyaltyTier NVARCHAR(20) NULL DEFAULT 'Standard';

It’s not wrong. But it’s a verb with no scene. To review it you have to imagine the table it’s mutating, remember what’s already there, and trace the side effects yourself. The diff brings the whole table to you. The script makes you go find it.

It rides the workflow you already trust

Because the change is a file, it flows through the exact path your application code already does — no new ceremony to learn:

Pull request. The schema edit is a diff a teammate reads and comments on, line by line, like any other code change.
Review on the design. The reviewer evaluates the shape — type, nullability, default, where it lives — not whether a hand-written script runs cleanly.
WhatIf on the gate. CI runs a preview against a database and shows exactly what the quench would do before anyone approves. No surprise strikes at deploy time.

No out-of-band migration folder. No “who runs the script, and when?” The reviewed file is the deployed file.

Prove it deploys

A clean review is worth nothing if the change doesn’t apply. So the lab closes the loop. You’ll diff the starter and solution copies of Customer.json to see the artifact a reviewer reads — that + block above — then quench the solution against a live database and watch LoyaltyTier land. One command. The same column the reviewer signed off on, hardened into the table.

That’s the whole point of schema-as-code in a team: the thing you reviewed and the thing that ships are the same thing. No translation step where a script drifts from intent. The diff is the deploy plan.

Want the deeper treatment of how schema changes move through review and approval — who signs off, where the gate sits, how it plugs into your branching model? Read the Database change approval workflows guide on the SchemaSmith site, and the end-user guide’s Working with your team chapter.

Check yourself: Why is a state-based JSON diff easier to review than the equivalent ALTER script?

The diff shows the column in the context of the whole table — its neighbors, indexes, and FKs are right there — so the reviewer evaluates the design, not whether a script executes correctly.

Think of it this way. An ALTER script is a single hammer-blow described on a sticky note: you know the strike, but not the metal it lands on. The JSON diff hands the reviewer the whole piece on the anvil — the column glowing in its place, every neighbor visible, the jig that holds it all still in frame. They judge the work, not the wording. Same change, far more light to see it by.

Got a review workflow you’re trying to reshape — where the gate goes, how a schema PR threads through your branch protection, who needs to sign? Email me at forgebarrett@schemasmith.com — I read every one.

Next up: Course 3 · Module 2 — CI/CD, where that WhatIf preview stops being a thing you run by hand and becomes the gate your pipeline enforces on every change.

Until then, may every change you send out read clean to the eyes that judge it, and land true on the metal that takes it.

— Forge

Mark this lesson complete