How to build schema change management

What matters here

• Watch the schema, not only for failures. The changes that break loudly are the easy ones.
• A renamed picklist value breaks nothing and silently corrupts every report grouping by it.
• Resolve what depends on a field before alerting. "Field removed" is noise; "these four dashboards break" is actionable.
• Classify by impact: additive is safe, a type change or removal is breaking, a rename is the dangerous middle.
• Alert the owner of what breaks, not the owner of the source system. They did not know you were reading it.

Who this is for

You run data or analytics engineering. Source systems change without telling you, and the first sign is a dashboard that looks wrong or a pipeline that failed overnight.

How it works in practice

What happens between a source system changing and a report being wrong.

1. 1

   Source schemas are snapshotted on a schedule

   Fields, types, picklist values and required flags, so a change is detectable at all.

2. 2

   Each snapshot is diffed against the last

   Additions, removals, type changes, renames and picklist changes.

3. 3

   Changes are classified by impact

   Additive is safe, removals and type changes break, renames are the dangerous middle.

4. 4

   Dependencies are resolved for anything breaking

   Which models, dashboards and syncs use that field.

5. 5

   The owner of what breaks is told before the run

   Not the owner of the source system, who did not know you were reading it.

6. 6

   Breaking changes can pause the pipeline

   Better a stale dashboard that says so than a current one that is wrong.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Set up and snapshot the source schemas

   Without a baseline there is no change, only a surprise.

   Headless skills build-workflow

   Copy

   Use build-workflow. The systems in play are Salesforce, NetSuite and
   Snowflake, or whatever we run in those seats.
   
   Snapshot each source schema on a schedule. From Salesforce that means
   describe on every object in scope, Account, Opportunity, Lead, Contact
   and any __c object: field names, types, whether each is required, and
   for a picklist every accepted value. Do the same for the NetSuite
   records and the Snowflake information schema.
   
   Store snapshots with a timestamp. This is the baseline, and without one
   every change is a discovery, not a detection.
   
   Include picklist values explicitly. They are the most commonly changed
   thing and the least commonly monitored, because changing one breaks
   nothing at all.

2. 2

   Diff and classify by impact

   The changes that break loudly are the easy ones.

   Headless skills build-workflow

   Copy

   Use build-workflow. Diff each snapshot against the previous and classify:
   
     Safe: a new optional field, a new picklist value nobody groups by
     Breaking: a field removed, a type changed, a field becoming required,
     a picklist value removed that data still uses
     Dangerous: a field renamed, a picklist value renamed, a field
     repurposed to mean something different
   
   The dangerous category is the point. A renamed picklist value fails
   nothing. The pipeline runs, the dashboard renders, and a new category
   appears that nobody notices while the old grouping quietly under-counts.
   
   Flag any field whose distribution changes sharply without a schema
   change. That is usually a repurposed field, which no schema diff can
   see.

   A field that silently changes meaning is the hardest case here and the one worth the distribution check, because nothing in the schema itself moves.

3. 3

   Resolve what actually depends on it

   "Field removed" is a puzzle; "these four dashboards break" is a task.

   Copy

   For every breaking or dangerous change, resolve the dependents before
   alerting:
   
     Which dbt models reference the field
     Which dashboards use those models
     Which reverse ETL syncs write or read it
     Which other pipelines consume it
     Which downstream tables would be affected
   
   Then alert with that list. Field X removed from object Y is a puzzle
   somebody has to investigate. The revenue dashboard and two reverse ETL
   syncs will break because field X was removed is a task somebody can size
   in seconds and act on.

4. 4

   Tell the right person, before the run

   The source system owner did not know you were reading it.

   Headless skills tray-gotchas

   Copy

   Use tray-gotchas, then alert the owner of what breaks, not the owner of
   the source system.
   
   The Salesforce administrator who renamed a field was doing their job and
   had no idea a warehouse model depended on it. Alerting them produces
   confusion; alerting the model owner produces a fix.
   
   Alert before the next scheduled run wherever possible, so the choice is
   still available.
   
   Offer to pause the affected pipeline. A dashboard that is stale and says
   so is better than one that is current and wrong, and that is a choice the
   data team should make deliberately, not discover.
   
   Handle: a change in a sandbox that has not reached production yet, which
   is a warning rather than an alert; a field added and removed between two
   snapshots, which is noise; and a change during a known migration, which
   should be suppressible with an expiry.

5. 5

   Report the changes that actually cost something

   Volume of schema changes is not interesting.

   Copy

   Report: breaking changes detected and how many were caught before a
   failure, dashboards affected, time from detection to fix, and changes
   that reached production before detection.
   
   That last one is the coverage measure. Every instance is a snapshot
   cadence that is too slow, or a source not being watched at all.
   
   Also report the sources that change most often. A system changing weekly
   needs a tighter snapshot cadence and possibly a conversation with
   whoever owns it about telling you first.
   
   Do not report total schema changes. Most are additive, harmless and
   frequent, and counting them buries the handful that matter.

6. 6

   Check it end to end, then hand the sources to analytics engineering

   Because new sources appear and cadence differs by system.

   Copy

   Run the per-step schema checks and the whole-workflow audit before this
   touches production. Introduce a deliberate breaking change in a sandbox
   and confirm the alert names the right dashboards and the right owner.
   
   Then open the same workflow in Tray Build so analytics engineering can
   add sources, adjust snapshot cadence and change the classification rules
   in the visual canvas.

What it connects to

Changes happen at the source and consequences land downstream.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Related guides