dbt Packages & Tests

Model contracts

An enforced contract that ran successfully, and why contracts are not a substitute for data tests.

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

Verification

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).

Official docs