dbt-bouncer

Configure and enforce conventions for your dbt project.

Documentation

All documentation can be found on dbt-bouncer documentation website.

Aims

dbt-bouncer aims to:

• Provide a 100% configurable way to enforce conventions in a dbt project.
• Be as fast as possible, running checks against dbt artifacts.
• Be as easy as possible to use, with a simple config file written in YAML or TOML.
• Be as flexible as possible, allowing checks to be written in Python.
• Provide immediate feedback when run as a pre-commit hook or as part of a CI pipeline.

Features

• Presets — start with a bundled minimal, standard or strict config, with no config file to write. Run dbt-bouncer run --preset strict.
• Baselines — adopt strict checks on an existing project and fail only on new failures. Record today's failures with dbt-bouncer baseline, or compare against a previous set of artifacts with dbt-bouncer run --state ./base-target.
• Discovery — browse every check with dbt-bouncer list, read one check in detail with dbt-bouncer explain check_model_names, or open the dashboard with dbt-bouncer studio.
• Config linting — catch mistakes in your config before a run with dbt-bouncer validate.
• AI agent integration — expose dbt-bouncer to Claude Code, Cursor and other agents over the Model Context Protocol with dbt-bouncer mcp.
• CI-friendly output — write results as csv, gitlab, json, junit, sarif or tap, and get distinct exit codes for check failures, config errors and artifact errors.
• Configuration anywhere — set every run option in the config file, on the command line, or through a DBT_BOUNCER_* environment variable.

See the CLI reference for all subcommands and options.

TLDR

1. Install dbt-bouncer:

   pip install dbt-bouncer
   

2. dbt-bouncer requires a manifest.json file. If not already present, run:

   dbt parse
   

3. Create a dbt-bouncer.yml config file:

   dbt-bouncer init
   

4. Run dbt-bouncer:

   $ dbt-bouncer run
   Running dbt-bouncer (X.X.X)...
   Loaded config from dbt-bouncer.yml...
   Validating conf...
   
               Parsed artifacts for
             'dbt_bouncer_test_project'
   ╭──────────────────┬─────────────────┬───────╮
   │ Artifact         │ Category        │ Count │
   ├──────────────────┼─────────────────┼───────┤
   │ manifest.json    │ Exposures       │     2 │
   │                  │ Macros          │     3 │
   │                  │ Nodes           │    12 │
   │                  │ Seeds           │     3 │
   │                  │ Semantic Models │     1 │
   │                  │ Snapshots       │     2 │
   │                  │ Sources         │     4 │
   │                  │ Tests           │    36 │
   │                  │ Unit Tests      │     3 │
   │ catalog.json     │ Nodes           │    13 │
   │                  │ Sources         │     0 │
   │ run_results.json │ Results         │    51 │
   ╰──────────────────┴─────────────────┴───────╯
   Assembled 463 checks, running...
   Running checks... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
   `dbt-bouncer` failed. Please see below for more details or run `dbt-bouncer` with the `-v` flag.
   Failed checks
   ╭────────────────────────────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
   │ Check name                         │  Severity  │ Failure message                                                                                                          │
   ├────────────────────────────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
   │ check_model_names:48:orders        │   ERROR    │ Models in the staging layer should always start with "stg_". - `orders` does not match the supplied regex `^stg_`.       │
   ╰────────────────────────────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
   Done. SUCCESS=462 WARN=0 ERROR=1
   

Reporting bugs and contributing code

• Want to report a bug or request a feature? Let us know and open an issue.
• Want to help us build dbt-bouncer? Check out the Contributing Guide.

Code of Conduct

Everyone interacting in dbt-bouncer's codebase, issue trackers, chat rooms, and mailing lists is expected to follow the Code of Conduct.