Add versions: [v: 1] to the existing model YAML and set latest_version: 1 to declare the initial version
When introducing a breaking schema change, add v: 2 to the versions list and create the corresponding SQL file with the _v2 suffix convention
Set latest_version: 2 so that new ref() calls without a version argument resolve to v2; existing refs with version: 1 continue to point to v1
Use dbt ls --select model_name to see both version materializations and confirm both are active
Deprecate v1 by setting the deprecation_date in the YAML and communicate the cutover date to downstream consumers
Known gotchas
Without explicit version: in a ref() call, dbt resolves to the latest_version; incrementing latest_version is a breaking change for any downstream model that relied on the old column set without specifying a version
Both model versions are materialized as separate physical objects in the warehouse (e.g., model_v1 and model_v2); this doubles compute and storage costs during the migration window
The deprecation_date field currently only emits a warning, not an error; teams must separately enforce removal via CI linting if they need a hard deadline
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp