Model versions

Model versioning allows data teams to introduce breaking changes to widely used models without breaking downstream consumers. By defining versions in YAML, dbt builds version one and version two side by side in the warehouse, giving downstream teams time to migrate their queries on their own schedule.

Why versioning matters

When a foundational table like dim_customers serves twenty dashboards and fifteen downstream models, changing a column name or altering row grain causes immediate disruptions. Without versioning, the data team must coordinate a high-risk cutover across multiple departments at the exact same moment.

Model versioning decouples the release of a new schema from consumer adoption. The producer team publishes version two while keeping version one active and running in production.

Syntax for authors and consumers

You manage versioning through YAML configuration and separate model files. In YAML, you declare the versions and specify which version is current:

models:
  - name: dim_customers
    latest_version: 2
    versions:
      - v: 1
        defined_in: dim_customers_v1
      - v: 2
        defined_in: dim_customers_v2
        deprecation_date: 2026-12-31

Consumers can reference a specific version or default to the latest release:

-- Explicitly pin to version 1
select * from {{ ref('dim_customers', v=1) }}

-- Uses the latest_version (version 2)
select * from {{ ref('dim_customers') }}

Downstream models choose when to upgrade their dependency references.

Deprecation and rollout strategy

Setting a deprecation date in the version configuration creates an explicit migration timeline. Whenever another model references a deprecated version during compilation, dbt issues a clear deprecation warning in the terminal logs:

• The warning tells consumers that the version is scheduled for retirement.
• Upstream authors can inspect manifest.json lineage to see which models still reference version one.
• Once all downstream references migrate to version two, the team drops version one from the project safely.

This structured migration pattern prevents chaotic breaking changes across shared analytical assets.