dbt-versioning

name	dbt-versioning
description	Load when task involves dbt model versioning, creating v2 of a model, or backward-compatible model changes. Covers versions YAML config, defined_in, latest_version, and ref() with version pins.
allowed-tools	Bash(dbt *)

dbt Model Versioning

1. Versioned Model vs Standalone Copy

When a task says "create a v2," "add a new version," or "backward-compatible change," use dbt's native versions: config (dbt-core 1.6+). Do NOT create a standalone model with a _v2 suffix - that produces a separate node (model.project.dim_customers_v2) instead of a version node (model.project.dim_customers.v2).

2. YAML Structure

Declare versions inside the model's .yml file under the model entry:

models:
 - name: dim_customers
    latest_version: 1
    versions:
 - v: 1
 - v: 2
        defined_in: dim_customers_v2

Rules:

• versions: is a list of v: entries inside the models: block, under the model name.
• defined_in: maps a version to its SQL filename (without .sql). Omit defined_in when the filename matches the default <model_name>_v<N>.sql.
• latest_version: controls which version ref('dim_customers') resolves to. If the task says "not yet the primary version," set latest_version to the old version number.

3. File Naming

Version SQL files use the pattern <model_name>_v<N>.sql.

• dim_customers.sql - original model, becomes v1 implicitly.
• dim_customers_v2.sql - new version.

Do NOT rename or move the original SQL file. It remains v1 without changes.

4. How ref() Works with Versions

• ref('dim_customers') resolves to whichever version latest_version specifies.
• ref('dim_customers', v=2) pins to version 2 regardless of latest_version.

Downstream models that need the new version must use ref('dim_customers', v=2). Models using bare ref('dim_customers') continue to get the old version until latest_version is updated.

5. Writing the v2 SQL

Read the original model's SQL first. If the v2 only renames or adds columns, write a thin wrapper:

select
    customer_id,
    customer_name,
    account_status as customer_status  -- renamed column
from {{ ref('dim_customers', v=1) }}

Do NOT duplicate all upstream logic into the v2 file when a SELECT-with-renames suffices.

6. Verification

After creating the versioned model, run:

dbt ls --select dim_customers --output json

Confirm the output contains nodes model.<project>.dim_customers.v1 and model.<project>.dim_customers.v2. If these nodes are missing, the versions: YAML is wrong.

Rules

• NEVER create a standalone _v2 model without versions: YAML - dbt will not register it as a version.
• NEVER rename or move the original SQL file when adding a new version.
• ALWAYS set latest_version explicitly - omitting it defaults to the highest version number, which may break downstream refs.
• ALWAYS read test files in tests/ before writing models - they reveal required dbt features the task may only hint at.