Versioning a model and retiring the version it replaces

dbt supports model versioning to manage breaking changes to public models without disrupting downstream consumers. By defining multiple versions of a model in YAML and marking older ones as deprecated, teams can migrate consumers on their own timeline while signaling when old versions will be removed.

1 · Learn the must-know

• 1Model versions are configured under the 'versions' key in the model's YAML properties, each with a unique 'v' identifier and optional 'defined_in' to point to a different file name.
• 2The 'latest_version' property controls which version is resolved when downstream code refs the model without specifying a version, allowing you to promote a new version without breaking unversioned refs.
• 3Consumers pin to a specific version using the two-argument ref syntax, e.g. ref('model_name', v=1), ensuring their pipelines are unaffected by changes to the latest version.
• 4Deprecating a version is done by setting a 'deprecation_date' on that version in the YAML; dbt will emit warnings (and can be configured to error) when that date has passed and the version is still referenced.
• 5Only models configured with access: public (or otherwise exposed via groups/contracts) are typical candidates for versioning, since versioning is meant to manage a stable, shared interface across teams.
• 6Versioned models are commonly paired with model contracts to enforce a stable schema per version, so breaking schema changes trigger a new version rather than silently altering an existing one.

2 · Check your understanding