Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 41 ยท CI and Best Practices

Model Contracts, Versions and Performance

Make dbt marts safe to depend on: enforced contracts, constraints, model versions, access modifiers, groups, and performance habits that keep builds fast.

As a project grows, some models become public interfaces: dashboards, other teams and other dbt projects depend on them. Changing a column name in one of those is a breaking change, just like changing a function signature in code. dbt (1.5 and newer) gives you tools to say "this is the shape of this model, and I promise not to break it silently": contracts, access modifiers, groups and versions.

These features are configuration for the real dbt engine, so they are shown read-only. The SQL checks a contract performs run in the editors.

Model contracts

A contract declares the exact columns and types a model must produce. With contract: {enforced: true} dbt checks the result before building the table and fails if it does not match.

YAML
models:
  - name: dim_customers
    config:
      contract:
        enforced: true
    columns:
      - name: customer_id
        data_type: int
        constraints:
          - type: not_null
          - type: primary_key
      - name: email
        data_type: varchar
      - name: signed_up
        data_type: date

If your SQL returns an extra column, a missing column or a different type, the run fails with a clear error listing the differences. The comparison, written as SQL against column metadata:

SQL Stand-in: contract versus actual columns

Press Run (or Ctrl + Enter) to see the result here.

signed_up is missing and country is unexpected, so the contract would fail the build before any data is written.

Constraints

constraints become real database constraints where the warehouse supports them (not_null is enforced on most; primary and foreign keys are often declared but not enforced, as in Snowflake and BigQuery). They do not replace tests: keep unique and not_null tests as well, because tests actually check the data. Constraints can also be written at model level (type: primary_key, columns: [order_id, line_number]) and with an expression for check constraints.

Access and groups

By default any model can ref() any other. Use access to protect your internals:

Access Meaning
private Only models in the same group may ref it
protected (default) Models in the same project (or package) may ref it
public Any project may ref it, including other dbt projects
YAML
groups:
  - name: finance
    owner:
      name: Finance analytics
      email: [email protected]

models:
  - name: int_orders_enriched
    group: finance
    access: private
  - name: fct_orders
    group: finance
    access: public
    config:
      contract: {enforced: true}

If a model outside the finance group refs int_orders_enriched, dbt raises an error at parse time. Public models are your supported interface; make them contracted and documented.

Model versions

Breaking a public model must not happen overnight. Versions let two shapes live side by side while consumers migrate:

YAML
models:
  - name: dim_customers
    latest_version: 2
    config:
      contract: {enforced: true}
    columns:
      - name: customer_id
        data_type: int
      - name: full_name
        data_type: varchar
    versions:
      - v: 1
        deprecation_date: 2026-06-30
        columns:
          - include: all
            exclude: [full_name]
          - name: first_name
            data_type: varchar
          - name: last_name
            data_type: varchar
      - v: 2

The files are dim_customers_v1.sql and dim_customers_v2.sql. ref('dim_customers') gives the latest version; ref('dim_customers', v=1) pins the old one. dbt warns anyone still using v1 as the deprecation date nears. Dropping a column, renaming it or changing its type should be a new version; adding a column is usually safe.

flowchart LR
  A["Breaking change needed"] --> B["Create v2 file and YAML entry"]
  B --> C["Consumers migrate to v2"]
  C --> D["Deprecation date passes"]
  D --> E["Delete v1"]

Versions turn breaking changes into a managed migration.

Performance habits

Good structure keeps builds fast; these habits help too:

  • Select only needed columns; avoid select * on wide, large tables outside staging.
  • Filter early and push filters into CTEs before joins.
  • Use incremental models where a table cannot be rebuilt quickly (see incremental basics).
  • Threads: raise threads in profiles.yml so independent models run in parallel, up to what the warehouse handles.
  • Right-size materializations: a chain of five views over a large table can be slower than one table.
  • Find slow models with target/run_results.json (it lists execution_time per node):
SQL Stand-in: slowest models from run results

Press Run (or Ctrl + Enter) to see the result here.

Two models take most of the run, so they are the places to optimize first (incremental, partitioning, clustering, fewer joins).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an enforced contract do?

    dbt checks the query's output against the declared columns before building.
  2. 2. Which access level lets other dbt projects ref a model?

    Public models are the supported cross-project interface.
  3. 3. Which change should be released as a new model version?

    Renames and removals break consumers, so they get a new version with a deprecation window.
  4. 4. Where can you find per-model execution time after a run?

    run_results.json records timing for each node.

Summary

  • Contracts enforce column names and types before a table is built.
  • access and groups mark which models are private, protected or public.
  • Versions manage breaking changes with a deprecation period.
  • Find slow models from run_results.json and fix the biggest first.

Next: Project: Shop Analytics Pipeline