Enforce a contract on every table other teams read

How to do it

Lineage shows who reads a table, and a contract states what they may rely on. Removing a column, changing its type or dropping a not-null constraint breaks readers. Adding a column does not. dbt model contracts, for example, check names and types before the build and flag breaking changes against the last release. Publish the new shape under a new version name. Keep the old one for the notice period in Give notice before removing a column people use, then drop it. Contracts on the inputs follow Treat each source schema as a contract.

Examples

YAML example

models:
  - name: fct_orders
    config:
      contract:
        enforced: true
    columns:
      - name: order_id
        data_type: bigint
        constraints:
          - type: not_null
      - name: total_cents
        data_type: bigint

Python example

def breaking_changes(released: dict[str, str], proposed: dict[str, str]) -> list[str]:
    return [f"{column}: {kind} -> {proposed.get(column, 'removed')}"
            for column, kind in released.items() if proposed.get(column) != kind]

JavaScript example

export const breakingChanges = (released, proposed) =>
  Object.entries(released)
    .filter(([column, kind]) => proposed[column] !== kind)
    .map(([column, kind]) => `${column}: ${kind} -> ${proposed[column] ?? 'removed'}`);

How to check

Every table marked as shared in its metadata has an enforced contract. In CI, a change that renames a column of a contracted table fails the build, and a change that adds a column passes.

Sources

• dbt model contracts

Related rules

• DEN-21 Give notice before removing a column people use in Data engineering
• EVT-5 Treat each source schema as a contract in Integration and events