Model contracts
The problem
A downstream consumer (another project, a BI tool, an official Mesh setup) needs customer_count to keep a stable set of columns and types. A data test will not fail the run just because someone renamed customer_count to n_customers and changed it to a bigint — depending on how you wrote the tests, it might not even notice. Official dbt model contracts enforce a declared schema when the model is built.
A working example
{{
config(
materialized='table',
contract={'enforced': true}
)
}}
select
status,
count(*)::integer as customer_count
from {{ ref('stg_customers') }}
group by status
models:
- name: customer_count
config:
contract:
enforced: true
columns:
- name: status
data_type: varchar
- name: customer_count
data_type: integer
data_tests:
- not_null
dbt run in the companion project built customer_count successfully with the contract enforced (dbt-core 1.12.7, dbt-duckdb 1.11.1). not_null on customer_count is a data test and is in addition to the contract, not instead of it.
Official documentation (see the contracts page for your version) describes contracts as a governance / Mesh feature: the declared columns and types are required, and an enforced contract should fail the build if the SQL does not match. Platform type names differ (varchar vs string vs text). Use the type names your adapter expects; this DuckDB run accepted varchar and integer.
The gotcha
A contract is about shape, not about meaning. It will not catch the orphan customer_id 9 that the relationships test caught. It will not catch a status typo. It will not freeze values.
Type names are adapter-specific. A contract that passes on DuckDB may fail on Snowflake if you write varchar where the official Snowflake contract examples expect a different type spelling. Always check the official contracts page and your adapter’s type names. This site did not run the same model on Snowflake.
Contracts also do not replace unit tests. The integer-vs-decimal seed issue in this project would not necessarily have been visible as a contract break on stg_orders unless you had contracted that column as a decimal in the first place — and even then, you want a fixture that proves 10.50 survives.
When not to use this
- A private staging model that no one else depends on. A contract is ceremony until there is a consumer who will be hurt by a rename.
- You have not agreed the column list with the consumer. Enforcing a draft schema just makes the first rename louder.
- You hoped a contract would guarantee data quality. Add data tests.
The enforced contract on customer_count built successfully with dbt-core 1.12.7 and dbt-duckdb 1.11.1. Broader contract semantics are from official dbt documentation and were not exhaustively re-tested (no deliberate failing contract run, and no Snowflake run).