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.
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: - 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(_ models. yml 38, # 38 digits, 2 after the point - name: country data_type: varchar2)
- order_idnumber
- amount_eurnumber
- countryvarchar
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: - name: fct_orders config: materialized: incremental unique_key: order_id on__ models. yml schema_ 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(change: fail # refuse a silent column change 38, # money: never float, it's approximate data_tests: - dbt_2) utils. arguments: expression: ">= 0" # the business rule, as a test - name: country data_type: varcharexpression_ is_ true:
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.
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: dbt build --select state:modified), plus everything downstream (+) 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
With a contract
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: - name: fct_orders latest__ models. yml 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, - 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_2) date: 2027-03-01 # warnings only, never a failure - v: 2 # built as fct_orders_ columns: - include: all exclude: [country] # v2 drops the columnv2
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.sqlandfct_orders_v2.sql. - Tables. dbt builds
FCT_ORDERS_V1andFCT_ORDERS_V2by default, so the plainFCT_ORDERSwould go stale. Thealiaskeeps 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: 1keeps every bareref('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_ -- no pin: follows latest_orders') }} version, moves when you bump it SELECT * FROM {{ ref('fct_ -- old shape, frozen: for teams not migrated yet SELECT * FROM {{ ref(orders', v=1) }} 'fct_ -- new shape, won't move if a v3 appearsorders', v=2) }}
ref('fct_orders', v=2) · already movedThe migration, as a playbook
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.v=2 in dbt, or read FCT_ORDERS_V2 from a dashboard.latest_version: 2. Every bare ref('fct_orders') moves to v2. Teams not ready pin v=1, nudged by the deprecation warning.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).dbt build to pass. Consumers then find out from the pipeline, not from a broken dashboard.
