Integrations

dbt Integration

ContractHQ integrates natively with dbt. Map your contracts to dbt sources and models, run checks as part of dbt test, and block deploys when a contract is violated — all without leaving your existing dbt workflow.

Prerequisites

  • dbt Core ≥ 1.5 or dbt Cloud
  • A ContractHQ account with at least one contract defined
  • ContractHQ CLI installed and authenticated

Step 1 — Install the dbt Package

Add the ContractHQ dbt package to your packages.yml:

packages.yml
packages:
  - package: contracthq/dbt_contracthq
    version: "^2.0.0"
terminal
dbt deps
# Installing contracthq/dbt_contracthq@2.0.1...
# ✔ Done

Step 2 — Map Contracts to dbt Sources

In your sources.yml, add the meta.contracthq_contract property to link a source table to a contract file:

models/staging/sources.yml
version: 2

sources:
  - name: raw
    database: ANALYTICS
    schema: raw
    tables:
      - name: user_signups
        meta:
          contracthq_contract: contracts/user_signups.yml
ℹ️
You can map a contract to a dbt model as well as a source. Use the same meta.contracthq_contract property in your schema.yml.

Step 3 — Run Contract Checks

ContractHQ checks are exposed as dbt tests. Run them with:

terminal
dbt test --select source:raw.user_signups

✔ contracthq_schema_match .................. PASS
✔ contracthq_not_null_user_id .............. PASS
✔ contracthq_unique_user_id ................ PASS
✔ contracthq_freshness_created_at .......... PASS

Finished running 4 tests in 3.21s
All 4 contract tests passed.

Step 4 — Enforce in CI

Add a step to your CI pipeline to run contract checks after every dbt build:

.github/workflows/dbt.yml
- name: Run dbt + contract checks
  run: |
    dbt build --target prod
    dbt test --select tag:contracthq --target prod
  env:
    CONTRACTHQ_TOKEN: ${{ secrets.CONTRACTHQ_TOKEN }}
💡
Tag your sources with tags: [contracthq] to make it easy to run only contract tests in your CI pipeline without running all dbt tests.

Auto-generated dbt Tests

The ContractHQ CLI can generate dbt test YAML directly from a contract file:

terminal
contracthq dbt generate-tests contracts/user_signups.yml
# Outputs dbt-compatible test YAML to stdout
contracthq dbt generate-tests contracts/user_signups.yml > models/staging/contracthq_tests.yml
← Versioning RulesSnowflake →