dbt_project_evaluator

[!IMPORTANT]

Using dbt v1? This README is for version 2, which requires dbt 2.0 or later. Stay on 1.x

(see the README of the 1.x branch)

and cap the version in your packages.yml so that dbt deps doesn't upgrade you: version: [">=1.0.0", "<2.0.0"]

This package highlights areas of a dbt project that are misaligned with dbt Labs' best practices. Specifically, it checks:

1. __Modeling__ - your dbt DAG for modeling best practices
2. __Testing__ - your models for testing best practices
3. __Documentation__ - your models for documentation best practices
4. __Structure__ - your dbt project for file structure and naming best practices
5. __Performance__ - your model materializations for performance best practices
6. __Governance__ - your best practices for model governance features

Why version 2?

• Native. Run the rules with dbt check, and configure them in dbt_project.yml like any other resource.
• Checked before every build. A rule set to severity: error stops a build that breaks it.
• Fast. About 15 seconds for a project of 1,900 models, against about 2 minutes for the 1.x dbt build.
• Selectable. --select and state:modified report only the violations on the resources you changed.
• No warehouse needed. No credentials and no compute cost, so CI needs no secrets.

Install

# packages.yml
packages:
  - package: dbt-labs/dbt_project_evaluator
    version: [">=2.0.0", "<3.0.0"]

The checks then run before every dbt build, and on demand with dbt check. They are advisory by default (severity: warn).

Use

dbt check                                                       # every check
dbt check fct_root_models                                       # one check
dbt check --select state:modified --state path/to/main/target   # only what a pull request changes

Set the severity of a category or of a single check in your dbt_project.yml:

checks:
  dbt_project_evaluator:
    structure:
      +severity: error          # block dbt build on violations
    documentation:
      fct_undocumented_models:
        +enabled: false         # turn off one rule

More options, in the documentation:

• accept some violations as exceptions
• change a threshold or a naming convention
• exclude a package or a path
• run the checks in CI

Coming from version 1?

The rules are the same, but they are checks now instead of models, so the configuration changes: severity is set with checks:, exceptions are a var instead of a seed, and the 1.x tables are gone. scripts/migrate_to_v2.py converts your exceptions seed. See the migration guide for all the changes.

Agent skills

The package ships three skills that teach a coding agent (Claude Code, Cursor, Codex...) how to run the checks, fix the violations and migrate from 1.x. Set ai_provider under flags: in your dbt_project.yml and run dbt deps to install them. See Agent skills.

Documentation

The rules, the configuration options, the exceptions and how to run the checks in CI are on the documentation site.