vaquarkhan Schema Evolution And Contract Migrations
Overview
Use this skill when a schema change can ripple through pipelines, models, dashboards, or external consumers. It helps agents make schema evolution deliberate, compatible, and recoverable.
When to Use
- changing input or output schemas
- renaming or dropping columns
- changing data types or nullability
- adding keys or changing grain
- migrating consumers from an old contract to a new one
Do not treat schema changes as isolated SQL edits. They are compatibility events.
Workflow
Classify the change. Decide whether it is:
- additive
- backward compatible
- breaking
- temporary dual-schema support
Map consumers and blast radius. Include:
- upstream producers
- downstream models
- dashboards
- APIs or extracts
- external consumers
Create the migration path. Options may include:
- dual writes
- compatibility views
- phased deprecation
- explicit consumer cutover windows
Validate old and new contracts during the transition.
Remove deprecated paths only after confirmation that consumers moved.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "It is just a column rename." | Renames break dashboards, notebooks, and joins that depend on the old name. |
| "Consumers will update quickly." | Some consumers are undocumented or owned by other teams. |
| "Additive changes are always safe." | New columns can still change file contracts, schemas, and downstream assumptions. |
Red Flags
- no consumer inventory exists
- breaking changes ship without transition support
- type changes are made without data validation
- deprecation timing is based on hope instead of confirmation
Verification
- The change type and compatibility level are classified
- Consumers and blast radius are identified
- A migration and rollback path exists
- Old and new contract behavior are validated during transition