Course contents

The Analytics Engineer’s Field Guidedbt 2: make it trustworthyStep 10: Contracts & versions

Contracts & versions

Part 2 · dbt · step 10

Contracts and versions: a model is a promise

Once people depend on your table, its shape is an interface. Write it down, and change it safely.

· · ·

Alice's marts are good enough that other teams now build on them, which is exactly when they get fragile. The day a dashboard or another team starts reading fct_orders, its columns and their types stop being her private business. They're a promise. Rename a column or change a type and something downstream breaks, often silently, often noticed days later. dbt gives you two tools for exactly this: contracts to enforce the shape, and versions to change it without breaking everyone at once.

Contract vs test: proactive vs reactive
A contract checks the shape before the model is built: right column names and types, or the build halts. A test checks the values after the table exists: no nulls, no duplicates. Contracts guard the shape up front, tests guard the data once it's there. You want both.

Contracts: enforce the shape at build time

A contract is you writing down the columns a model returns and their types. With the contract enforced, dbt checks the model's output against that promise before it builds. How, before? It first runs your query wrapped to return zero rows, which costs almost nothing. Snowflake reports the column names and types, and dbt compares them with the YAML. A missing column or a wrong type fails the build, loudly, in your pull request, not in a dashboard next week.

# models/marts/_models.yml
models:
  - name: fct_orders
    config:
      contract: {enforced: true}
    columns:
      - name: order_id
        data_type: int
        constraints:
          - type: not_null
          - type: primary_key
      - name: amount_eur
        data_type: numeric(38,2)   # 38 digits, 2 after the point
      - name: country
        data_type: varchar
what the SQL returns
  • order_idnumber
  • amount_eurnumber
  • countryvarchar
CONTRACTchecked BEFORE the build:names + types must match
✓ shape matchesthe model builds
✗ column driftedbuild halts, in the PR

Constraints: more than just the type

dbt compares type families, not precision or scale, so Snowflake's NUMBER output matches int and numeric(38,2). The scale you declare is what the table gets: a bare numeric means numeric(38,0) on Snowflake, so declare it for euros and 10.50 is silently rounded to 11. int and numeric also exist in DuckDB, so the same contract runs in the local loop (step 15); Snowflake's own number doesn't.

Beyond names and types, a contract can carry constraints: not_null, unique, primary_key, foreign_key and check. On Snowflake, only not_null is truly enforced. So keep not_null as a constraint, and check uniqueness and business rules with data tests. Here's fct_orders again, once it turns incremental (step 4):

# models/marts/_models.yml
models:
  - name: fct_orders
    config:
      materialized: incremental
      unique_key: order_id
      on_schema_change: fail   # refuse a silent column change
      contract: {enforced: true}
    columns:
      - name: order_id
        data_type: int
        constraints:
          - type: not_null     # enforced by Snowflake
          - type: unique       # written to the CREATE TABLE, not enforced
        data_tests:
          - unique               # so the real check is a test
      - name: amount_eur
        data_type: numeric(38,2)    # money: never float, it's approximate
        data_tests:
          - dbt_utils.expression_is_true:
              arguments:
                expression: ">= 0"   # the business rule, as a test
      - name: country
        data_type: varchar

Note on_schema_change here sits under config: in YAML, while step 4 put it in {{ config(...) }} in the SQL file. Any config can go in three places: the SQL file, the model's YAML, or dbt_project.yml with a +. The most specific wins, in that order.

Two gotchas
primary_key, unique and foreign_key go into the DDL (the CREATE TABLE statement) as metadata nothing checks. Some BI and diagram tools read them to suggest joins. check isn't supported at all: dbt warns and skips it. Second, dbt maps generic type names like string to Snowflake's own before comparing. To compare exactly as written, use contract: {enforced: true, alias_types: false}.

Where contracts pay off: CI and the catalog

A contract isn't just a build-time guard, it's metadata. Two places make use of it:

  • In your catalog. The contract lands in manifest.json, so dbt's docs site or a catalog tool like DataHub can show the promised columns.
  • In CI. Every dbt command writes target/manifest.json, a snapshot of the whole project. Production's job saves its copy after each run: the "prod artifacts". The platform team sets CI up to download it into a folder, then run this on every pull request:
# only what your branch changed (state:modified), plus everything downstream (+)
dbt build --select state:modified+ --state prod-artifacts/

dbt also compares each contract with production's. A removed column or a changed type is a breaking change, flagged right next to the diff. On a versioned model (next section) it's an error, on an unversioned one a warning. That's not a loophole. If your SQL and your YAML disagree, the build still fails. This check catches something else: you changed both on purpose, they agree, and consumers will still break. For that, dbt's answer is a new version.

Without a contract
A rename slips throughThe build succeeds, the shape changed.
Downstream breaks laterA model or dashboard fails days afterward.
You debug in prodFar from the change that caused it.
With a contract
The build fails at once"column amount_eur not found", clearly.
Caught in the PRBefore anything reaches production.
Fixed at the sourceYou see it the moment you cause it.

Versions: change the shape without breaking everyone

Sometimes you genuinely must change a model: drop a column, rename one, split it. You don't edit in place and break every consumer at once. You publish a new version beside the old one. Consumers move to v2 on their own schedule. Once everyone's across, you retire v1. Say Alice wants country out of fct_orders: it belongs in dim_customer (step 3).

# models/marts/_models.yml
models:
  - name: fct_orders
    latest_version: 1           # bare ref() stays on v1 until you bump this
    config:
      contract: {enforced: true}
    columns:                       # the full list, shared by every version
      - name: order_id
        data_type: int
      - name: amount_eur
        data_type: numeric(38,2)
      - name: country
        data_type: varchar
    versions:
      - v: 1                       # no columns key: takes all three, the old shape
        config:
          alias: fct_orders          # v1 keeps the old table name
        deprecation_date: 2027-03-01   # warnings only, never a failure
      - v: 2                       # built as fct_orders_v2
        columns:
          - include: all
            exclude: [country]   # v2 drops the column

Read it one piece at a time:

  • Columns. The top-level list is the full menu. v1 takes all of it, v2 drops country.
  • Files. Each version is its own SQL file: fct_orders_v1.sql and fct_orders_v2.sql.
  • Tables. dbt builds FCT_ORDERS_V1 and FCT_ORDERS_V2 by default, so the plain FCT_ORDERS would go stale. The alias keeps v1 at that name, and dashboards keep working.
  • Dashboards. They can't write ref(), so they pick a version by table name.
  • Default. latest_version: 1 keeps every bare ref('fct_orders') on v1 until you bump it.
  • Warnings. Both versions build on every run until you delete v1. Past the deprecation date, each run's log warns about models still on v1: your terminal, or the Airflow task log.

How to ref a versioned model: the three calls

-- three consumers, three choices
SELECT * FROM {{ ref('fct_orders') }}        -- no pin: follows latest_version, moves when you bump it
SELECT * FROM {{ ref('fct_orders', v=1) }}  -- old shape, frozen: for teams not migrated yet
SELECT * FROM {{ ref('fct_orders', v=2) }}  -- new shape, won't move if a v3 appears
fct_orders · v1old shape · deprecation warned
reads FCT_ORDERS (v1) · not migrated yet
Finance dashboardmigrates on its own schedule
fct_orders · v2new shape · fct_orders_v2
ref('fct_orders', v=2) · already moved
Growth team modeldone, reads the new shape
both versions build side by side · v1 retires the day its last consumer moves

The migration, as a playbook

1
Publish v2 beside v1Rename fct_orders.sql to fct_orders_v1.sql, copy it to fct_orders_v2.sql and make the change there. Add the versions: block above. Both build, and everyone still reads v1.
2
Announce v2Post it in the team channel. Early movers pin v=2 in dbt, or read FCT_ORDERS_V2 from a dashboard.
3
Make v2 the defaultOn the announced date, set latest_version: 2. Every bare ref('fct_orders') moves to v2. Teams not ready pin v=1, nudged by the deprecation warning.
4
Retire v1Once nothing reads v1, delete fct_orders_v1.sql and its - v: 1 entry. dbt never drops tables, and your role can't touch PROD_DB, so the platform team drops the old FCT_ORDERS. v2 stays FCT_ORDERS_V2 (dbt 1.12+ can add a plain-named view that follows the latest version).
✓ The shape changed, and nobody's Saturday was ruined.
When it's worth it
Contracts and versions are for your public marts, the models other teams and dashboards depend on. Your internal staging and intermediate models don't need the ceremony. Put a contract on the handful of tables that are real promises, and leave the rest light.
And tell people
A contract change is a social event, not just a technical one. Post it to the team channel. Once Airflow runs the pipeline (part 3), make downstream jobs wait for dbt build to pass. Consumers then find out from the pipeline, not from a broken dashboard.

Lesson quiz

  1. How does an enforced contract differ from a data test?

    1. Both check values, but the contract only ever runs against the production target
    2. The contract checks values after the build; tests check types before it
    3. The contract covers not_null and unique, so the tests become optional
    4. The contract checks columns and types before the build; tests check values after
  2. You must drop a column from fct_orders, which other teams read. What's the safe path?

    1. Drop it in place and warn every team in the channel first
    2. Rename the model and point every consumer at the new name
    3. Disable the contract for one run, then drop the column
    4. Publish v2 beside v1, let consumers migrate, then retire v1
  3. fct_orders has versions 1 and 2 with latest_version: 1, and v1 is aliased to the table FCT_ORDERS. Finance uses ref('fct_orders', v=1), marketing uses a bare ref. Alice sets latest_version: 2 and keeps v1. What changes?

    1. The bare ref moves to v2; the pin and FCT_ORDERS stay on v1
    2. v1 stops building, so the aliased FCT_ORDERS table goes stale
    3. Nothing changes until v1's deprecation_date passes
    4. Every ref moves to v2, finance's pinned one included