Course 4 · Module 0 — Driving the tools

You’ve hit the ceiling before — a label that should’ve done something, a token you wanted to read back at deploy time, a value that didn’t live anywhere in the package. You can declare a table, quench it to three engines, fan a template across a hundred schemas, gate a change on the environment it lands in. You know the tools. This course is about how much further they go than you think.

Because the levers you’ve been treating as labels — the metadata you hang on an object, the tokens you sprinkle through a script — aren’t labels at all. They’re controls. The engine reads them at deploy time and acts on them. Declare the right thing in the right place and the tools do the work for you.

Metadata that does something

There are two kinds of metadata in a schema package. One kind sits there — a comment, a note, a tag nobody reads but you. The other kind drives. The difference is whether the engine reads it at deploy time and changes what it does.

A custom property — anything you drop in an object’s Extensions bag — is the driving kind. SchemaSmith turns it into a {{token}} and substitutes it into the expression fields it evaluates: ShouldApplyExpression, Default, CheckExpression, and the script bodies it runs. Your own value, attached to your own object, steering the deploy. And when a script needs the whole picture, {{TableSchema}} hands it every table’s model — Extensions and all — as JSON it can read and act on.

You met the basics of this in Course 2. This course is about the ceiling — what a creative hand can actually drive with it.

This is a cookbook — flip to what you need

The rest of Course 1, 2, and 3 told one story start to finish. Course 4 doesn’t. It’s a cookbook: six independent recipes, each its own self-contained lesson and lab against the same little e-commerce shop. Work them in order or jump straight to the one that solves the problem in front of you.

Recipe 1 · The environment-aware schema — one package, a different physical shape in production than in non-prod, with zero per-environment file copies.
Recipe 2 · Policy that enforces itself — declare a retention rule once on the table; the column default and the check constraint carry it, and follow it when it changes.
Recipe 3 · The package asks the server — pull a live value off the target database at deploy time, before any script runs.
Recipe 4 · Assets that travel with the schema — ship a logo or a reference dataset inside the package, landing as the right binary literal on every engine.
Recipe 5 · Scripts that write scripts — generate per-table DDL from the model you declared, so the generated object never drifts from the schema.
Recipe 6 · Surviving a destructive rebuild — keep a table’s data when a change forces SchemaSmith to drop and recreate it.

Different levers, one idea underneath: declare your intent on the object, and let the tools read it instead of guessing.

Where the deep reference lives

Each recipe links the reference page behind it. The two that anchor this whole course are the Custom Properties reference — every supported object, the token-scope rules, validation — and the Script Tokens reference — the full token syntax, the advanced tags, and the automatic tokens like {{TableSchema}}. Keep both within reach as you cook.

Check yourself: What's the difference between metadata that just sits in your schema and metadata that drives behavior?

Driving metadata is read by the engine at deploy time — a custom property becomes a {{token}} in an expression, or the whole model (Extensions included) is read by a script through the {{TableSchema}} token — so declaring it once changes what actually gets deployed. Metadata that just sits is never read by the engine; it changes nothing.

Think of it this way. Every part you forge has its standard dimensions — the stuff the tools already know how to make. But you also stamp it with your own marks: what it’s for, how it’s meant to be handled, what rule it has to hold. In this course those marks stop being decoration and start being instructions. The metal moves to them. You declare the intent; the tools strike to it.

Got a workflow you’re trying to picture in this shape — a per-environment difference, a policy you keep restating, an asset you keep hand-loading? Email me at forgebarrett@schemasmith.com — I read every one.

Next up: Course 4 · Recipe 1 — The environment-aware schema, where one package deploys a Production-only index and a non-prod-only column, switched by a single tag.

Until then, may every value you set pull its weight in the fire, and the tools forge exactly what you told them.

— Forge

Mark this lesson complete