dbt-bouncer

https://godatadriven.github.io/dbt-bouncer/stable
Admin
dbt-bouncer is an open-source tool that enforces conventions in dbt projects by running configurable...
Tokens:85,596
Snippets:610
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install dbt-bouncer and dependencies

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Use these commands to install the project and its required tools in a virtual environment.

```bash
make install
uv run prek install
```

--------------------------------

### Configure dbt-bouncer with TOML

Source: https://godatadriven.github.io/dbt-bouncer/stable/configuration

Example configuration using the TOML format.

```toml
# [Optional] Directory where the dbt artifacts exists, generally the `target` directory inside a dbt project. Defaults to `$DBT_PROJECT_DIR/target` if $DBT_PROJECT_DIR is set, else `./target`.
dbt_artifacts_dir = "target"

[[manifest_checks]]
name = "check_macro_name_matches_file_name"

[[manifest_checks]]
name = "check_model_names"
include = "^models/staging"
model_name_pattern = "^stg_"
```

--------------------------------

### Configure dbt-bouncer with YAML

Source: https://godatadriven.github.io/dbt-bouncer/stable/configuration

Example configuration using the YAML format.

```yaml
# [Optional] Directory where the dbt artifacts exists, generally the `target` directory inside a dbt project. Defaults to `$DBT_PROJECT_DIR/target` if $DBT_PROJECT_DIR is set, else `./target`.
dbt_artifacts_dir: target

manifest_checks:
  - name: check_macro_name_matches_file_name
  - name: check_model_names
    include: ^models/staging
    model_name_pattern: ^stg_
```

--------------------------------

### Install dbt-bouncer via pip

Source: https://godatadriven.github.io/dbt-bouncer/stable/getting_started

Install the package from PyPI using pip or another package manager.

```bash
pip install dbt-bouncer # or via any other package manager
```

--------------------------------

### Configure check_model_has_no_upstream_dependencies

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/lineage

Example configuration for the check_model_has_no_upstream_dependencies rule.

```yaml
manifest_checks:
    - name: check_model_has_no_upstream_dependencies
```

--------------------------------

### Installing documentation dependencies

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Use uv to sync the documentation dependency group from the repository root.

```bash
uv sync --group=docs
```

--------------------------------

### Validation output examples

Source: https://godatadriven.github.io/dbt-bouncer/stable/cli

Displays the console output for both successful and failed configuration validations.

```text
Config file is valid!
```

```text
Found 2 issue(s) in config file:
  Line 1: Check is missing required 'name' field
  Line 3: YAML syntax error: ...
```

--------------------------------

### Configure check_model_max_chained_views in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/lineage

Basic and customized configuration examples for the manifest check.

```yaml
manifest_checks:
    - name: check_model_max_chained_views
```

```yaml
manifest_checks:
    - name: check_model_max_chained_views
      materializations_to_include:
        - ephemeral
        - my_custom_materialization
        - view
      max_chained_views: 5
```

--------------------------------

### Configure check_macro_description_populated

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_macros

Examples for enabling the macro description check in the manifest configuration.

```yaml
manifest_checks:
    - name: check_macro_description_populated
```

```yaml
# Only "common" macros need to have a populated description
manifest_checks:
    - name: check_macro_description_populated
      include: ^macros/common
```

--------------------------------

### Configure check_test_has_meta_keys in YAML

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_tests

Example configuration for the check_test_has_meta_keys manifest check.

```yaml
manifest_checks:
    - name: check_test_has_meta_keys
      keys:
        - owner
```

```yaml
manifest_checks:
    - name: check_test_has_meta_keys
      keys:
        - owner
```

--------------------------------

### Configure check_model_has_constraints

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/columns

Example configuration for the check_model_has_constraints rule in a manifest file.

```yaml
manifest_checks:
    - name: check_model_has_constraints
      required_constraint_types:
        - primary_key
      include: ^models/marts
```

--------------------------------

### Configure check_model_description_populated in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/description

Basic and advanced configuration examples for the model description check.

```yaml
manifest_checks:
    - name: check_model_description_populated
```

```yaml
manifest_checks:
    - name: check_model_description_populated
      min_description_length: 25 # Setting a stricter requirement for description length
```

--------------------------------

### Configure check_model_latest_version_specified

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/versioning

Example configuration for the check_model_latest_version_specified rule in the manifest_checks file.

```yaml
manifest_checks:
    - name: check_model_latest_version_specified
      include: ^models/marts
```

--------------------------------

### Configure check_model_columns_have_meta_keys in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/columns

Example configuration for the manifest check in a YAML file.

```yaml
manifest_checks:
    - name: check_model_columns_have_meta_keys
      keys:
        - owner
        - pii
```

--------------------------------

### Configure check_macro_arguments_description_populated

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_macros

Examples of how to configure the check_macro_arguments_description_populated rule in the manifest_checks configuration file.

```yaml
manifest_checks:
    - name: check_macro_arguments_description_populated
```

```yaml
# Only "common" macros need to have their arguments populated
manifest_checks:
    - name: check_macro_arguments_description_populated
      include: ^macros/common
```

```yaml
manifest_checks:
    - name: check_macro_arguments_description_populated
      min_description_length: 25 # Setting a stricter requirement for description length
```

--------------------------------

### Configure check_snapshot_description_populated in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_snapshots

Examples of how to include the snapshot description check in the manifest_checks configuration.

```yaml
manifest_checks:
    - name: check_snapshot_description_populated
```

```yaml
manifest_checks:
    - name: check_snapshot_description_populated
      min_description_length: 25 # Setting a stricter requirement for description length
```

--------------------------------

### Monorepo dbt-bouncer.yml configuration

Source: https://godatadriven.github.io/dbt-bouncer/stable/faq

Example configuration for dbt-bouncer when running from the root of a monorepo.

```yaml
dbt_artifacts_dir: dbt-project/target
include: ^dbt-project

manifest_checks:
    - name: check_exposure_based_on_non_public_models
```

--------------------------------

### Configure check_model_max_number_of_lines

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/code

Example configurations for limiting the maximum number of lines in a model.

```yaml
manifest_checks:
    - name: check_model_max_number_of_lines
```

```yaml
manifest_checks:
    - name: check_model_max_number_of_lines
      max_number_of_lines: 150
```

--------------------------------

### Configure check_macro_max_number_of_lines

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_macros

Example for enabling the macro line count check in the manifest configuration.

```yaml
manifest_checks:
    - name: check_macro_max_number_of_lines
```

--------------------------------

### Configure check_column_description_populated

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/catalog/columns/description

Examples of configuring the column description check in the catalog_checks configuration file.

```yaml
catalog_checks:
    - name: check_column_description_populated
      include: ^models/marts
```

```yaml
catalog_checks:
    - name: check_column_description_populated
      min_description_length: 25 # Setting a stricter requirement for description length
```

--------------------------------

### Configure check_run_results_max_gigabytes_billed in YAML

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/run_results/check_run_results

Example configuration for the check within a dbt-bouncer configuration file.

```yaml
run_results_checks:
    - name: check_run_results_max_gigabytes_billed
      max_gigabytes_billed: 100
      exclude: ^seeds
```

--------------------------------

### Configure dbt-bouncer in pyproject.toml

Source: https://godatadriven.github.io/dbt-bouncer/stable/configuration

Example configuration embedded within a pyproject.toml file under the [tool.dbt-bouncer] section.

```toml
[tool.dbt-bouncer]
# [Optional] Directory where the dbt artifacts exists, generally the `target` directory inside a dbt project. Defaults to `$DBT_PROJECT_DIR/target` if $DBT_PROJECT_DIR is set, else `./target`.
dbt_artifacts_dir = "target"

[[tool.dbt-bouncer.manifest_checks]]
name = "check_macro_name_matches_file_name"

[[tool.dbt-bouncer.manifest_checks]]
name = "check_model_names"
include = "^models/staging"
model_name_pattern = "^stg_"
```

--------------------------------

### Configure check_seed_columns_are_all_documented

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/catalog/check_catalog_seeds

Example configuration for enabling the seed column documentation check in the catalog_checks section.

```yaml
catalog_checks:
    - name: check_seed_columns_are_all_documented
```

--------------------------------

### View dbt-bouncer artifact summary

Source: https://godatadriven.github.io/dbt-bouncer/stable/getting_started

Example of the summary table displayed after parsing dbt artifacts.

```text
            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 │
╰──────────────────┴─────────────────┴───────╯
```

--------------------------------

### Previewing documentation locally

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Start the Zensical development server to preview documentation changes at http://localhost:8000/dbt-bouncer/.

```bash
uv run zensical serve
```

--------------------------------

### Configure model documentation coverage check

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/description

YAML configuration examples for setting the minimum documentation coverage percentage or enforcing description length.

```yaml
manifest_checks:
    - name: check_model_documentation_coverage
      min_model_documentation_coverage_pct: 90
```

```yaml
manifest_checks:
    - name: check_model_documentation_coverage
      min_description_length: 25 # Setting a stricter requirement for description length
```

--------------------------------

### Configure check_exposure_based_on_model

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_exposures

Examples of how to include the check in your manifest_checks configuration.

```yaml
manifest_checks:
    - name: check_exposure_based_on_model
```

```yaml
manifest_checks:
    - name: check_exposure_based_on_model
      maximum_number_of_models: 3
      minimum_number_of_models: 1
```

--------------------------------

### Building the static documentation site

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Generate the static documentation site in the site/ directory.

```bash
uv run zensical build
```

--------------------------------

### Configure check_model_has_exposure

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/lineage

Example configuration for the check_model_has_exposure rule in a manifest_checks block.

```yaml
manifest_checks:
    - name: check_model_has_exposure
      description: Ensure all marts are part of an exposure.
      include: ^models/marts
```

```python
@check
def check_model_has_exposure(model, ctx):
    """Models must have an exposure.

    !!! info "Rationale"

        Exposures declare how dbt models are consumed by downstream tools such as dashboards, ML pipelines, or applications. Requiring mart models to be referenced in at least one exposure ensures that every curated output has a known consumer, making it easier to assess the impact of changes and avoid maintaining unused models.

    Receives:
        exposures (list[ExposureNode]):  List of ExposureNode objects parsed from `manifest.json`.
        model (ModelNode): The ModelNode object to check.

    Other Parameters:
        description (str | None): Description of what the check does and why it is implemented.
        exclude (str | list[str] | None): Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked.
        include (str | list[str] | None): Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked.
        materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization.
        severity (Literal["error", "warn"] | None): Severity level of the check. Default: `error`.

    Example(s):
        ```yaml
        manifest_checks:
            - name: check_model_has_exposure
              description: Ensure all marts are part of an exposure.
              include: ^models/marts
        ```

    """
    models_in_exposures = {
        node
        for e in ctx.exposures
        for node in (getattr(e.depends_on, "nodes", []) or [])
    }

    if model.unique_id not in models_in_exposures:
        fail(
            f"`{get_clean_model_name(model.unique_id)}` does not have an associated exposure."
        )
```

--------------------------------

### Initialize configuration file

Source: https://godatadriven.github.io/dbt-bouncer/stable/cli

Starts an interactive session to generate a new dbt-bouncer.yml configuration file.

```bash
dbt-bouncer init
```

--------------------------------

### Create a virtual environment with uv

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Initializes a new Python virtual environment in the project root.

```bash
uv venv

```

--------------------------------

### Monorepo directory structure example

Source: https://godatadriven.github.io/dbt-bouncer/stable/faq

A sample directory tree illustrating a monorepo with a dbt project and unrelated code.

```text
.
├── dbt-bouncer.yml
├── README.md
├── dbt-project
│   ├── models
│   ├── dbt_project.yml
│   └── profiles.yml
└── package-a
    ├── src
    ├── tests
    └── package.json
```

--------------------------------

### Configure check_model_columns_have_types

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/columns

Example configuration for the check_model_columns_have_types rule in a manifest file.

```yaml
manifest_checks:
    - name: check_model_columns_have_types
      include: ^models/marts
```

--------------------------------

### Configure check_model_max_upstream_dependencies in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/lineage

Example configuration for the check in a dbt_bouncer manifest file.

```yaml
manifest_checks:
    - name: check_model_max_upstream_dependencies
      max_upstream_models: 3
```

--------------------------------

### Run performance tests

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Execute performance benchmarks using bencher and hyperfine.

```bash
make test-perf
```

--------------------------------

### Configuration for check_columns_are_all_documented

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/catalog/columns/description

Example configuration snippet for enabling the check that ensures all database columns are defined in YAML files.

```yaml
catalog_checks:
    - name: check_columns_are_all_documented
```

--------------------------------

### Configure check_model_depends_on_macros

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/lineage

Example configuration for enforcing macro dependencies in dbt models.

```yaml
manifest_checks:
    - name: check_model_depends_on_macros
      required_macros:
        - dbt.is_incremental
    - name: check_model_depends_on_macros
      criteria: one
      required_macros:
        - my_package.sampler
        - my_package.sampling
```

--------------------------------

### Configure check_model_number_of_grants

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/access

Example configuration for limiting the number of privileges granted to a model.

```yaml
manifest_checks:
    - name: check_model_number_of_grants
      include: ^models/marts
      max_number_of_privileges: 1 # Optional
      min_number_of_privileges: 0 # Optional
```

--------------------------------

### Configure Source Description Check

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/sources/description

Basic configuration for the source description check in the manifest file.

```yaml
manifest_checks:
    - name: check_source_description_populated
```

```yaml
manifest_checks:
    - name: check_source_description_populated
      min_description_length: 25 # Setting a stricter requirement for description length
```

--------------------------------

### Configure check_model_has_unit_tests

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/tests

Configuration examples for enforcing unit tests on dbt models.

```yaml
manifest_checks:
    - name: check_model_has_unit_tests
      include: ^models/marts
```

```yaml
manifest_checks:
    - name: check_model_has_unit_tests
      min_number_of_unit_tests: 2
```

--------------------------------

### Registering a plugin via entry points

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Define the entry point in your plugin package's pyproject.toml to allow dbt-bouncer to discover your checks.

```toml
# pyproject.toml of your plugin package
[project.entry-points."dbt_bouncer.checks"]
my_checks = "my_package.checks"
```

--------------------------------

### dbt-bouncer init

Source: https://godatadriven.github.io/dbt-bouncer/stable/cli

Interactively creates a new dbt-bouncer.yml configuration file.

```APIDOC
## dbt-bouncer init

### Description
Creates a dbt-bouncer.yml configuration file interactively by asking a series of questions regarding dbt artifacts and desired checks.
```

--------------------------------

### Configure check_model_file_name

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/directories

Example configuration for enforcing file naming patterns in dbt-bouncer.

```yaml
manifest_checks:
    - name: check_model_file_name
      description: Marts must include the model version in their file name.
      include: ^models/marts
      file_name_pattern: .*(v[0-9])\.sql$
```

--------------------------------

### Run dbt-bouncer with configuration

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Execute the dbt-bouncer script using a specific configuration file.

```bash
uv run dbt-bouncer --config-file dbt-bouncer-example.yml
```

--------------------------------

### Configure check_seed_has_unit_tests in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_seeds

Examples of configuring the check in the manifest_checks YAML configuration.

```yaml
manifest_checks:
    - name: check_seed_has_unit_tests
      include: ^seeds/core
```

```yaml
manifest_checks:
    - name: check_seed_has_unit_tests
      min_number_of_unit_tests: 2
```

--------------------------------

### Configure include patterns at different levels

Source: https://godatadriven.github.io/dbt-bouncer/stable/configuration

Demonstrates how include patterns behave when defined at the check level, global level, or both.

```yaml
# Specify `include` at the check level only
manifest_checks:
  - name: check_model_names
    include: ^models/staging
    model_name_pattern: ^stg_
```

```yaml
# Specify `include` at the check and global levels
include: ^models/marts
manifest_checks:
  - name: check_model_names
    include: ^models/staging
    model_name_pattern: ^stg_
```

```yaml
# Specify `include` at the global level only
include: ^models/staging
manifest_checks:
  - name: check_model_names
    model_name_pattern: ^stg_
```

--------------------------------

### Run dbt-bouncer with uv

Source: https://godatadriven.github.io/dbt-bouncer/stable/getting_started

Execute as a standalone Python executable using uv, useful for environments without a persistent Python installation.

```bash
uvx dbt-bouncer --config-file <PATH_TO_CONFIG_FILE>
```

--------------------------------

### Configure check_lineage_seed_cannot_be_used

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/check_lineage

Example YAML configuration for the seed usage restriction check.

```yaml
manifest_checks:
    - name: check_lineage_seed_cannot_be_used
      include: ^models/intermediate|^models/marts
```

--------------------------------

### Configure check_model_max_fanout

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/lineage

Example configuration for limiting the number of downstream models in a dbt project.

```yaml
manifest_checks:
    - name: check_model_max_fanout
      max_downstream_models: 2
```

--------------------------------

### Run test suites via Makefile

Source: https://godatadriven.github.io/dbt-bouncer/stable/CONTRIBUTING

Execute various test suites using predefined Makefile targets.

```bash
# Runs unit tests
make test-unit

# Runs integration tests
make test-integration

# Runs all tests
make test

# Alternative for dev containers only
make test-dev-container
```

--------------------------------

### Configure check_model_test_coverage in YAML

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/tests

Example configuration for the manifest check in a dbt-bouncer configuration file.

```yaml
manifest_checks:
    - name: check_model_test_coverage
      min_model_test_coverage_pct: 90
```

--------------------------------

### Configure check_model_has_contracts_enforced

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/access

Example configuration for enforcing model contracts within the manifest checks.

```yaml
manifest_checks:
    - name: check_model_has_contracts_enforced
      include: ^models/marts
```

```python
@check
def check_model_has_contracts_enforced(model):
    """Model must have contracts enforced.

    !!! info "Rationale"

        Enforced contracts guarantee that a model's output schema — column names and types — is validated at build time. Without this, schema changes can silently break downstream consumers. Applying this check to a specific set of models (e.g. marts) provides a schema stability guarantee for those critical outputs.

    Receives:
        model (ModelNode): The ModelNode object to check.

    Other Parameters:
        description (str | None): Description of what the check does and why it is implemented.
        exclude (str | list[str] | None): Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked.
        include (str | list[str] | None): Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked.
        materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization.
        severity (Literal["error", "warn"] | None): Severity level of the check. Default: `error`.

    Example(s):
        ```yaml
        manifest_checks:
            - name: check_model_has_contracts_enforced
              include: ^models/marts
        ```

    """
    if not model.contract or model.contract.enforced is not True:
        fail(
            f"`{get_clean_model_name(model.unique_id)}` does not have contracts enforced."
        )
```

--------------------------------

### Run dbt-bouncer via CLI

Source: https://godatadriven.github.io/dbt-bouncer/stable/getting_started

Execute dbt-bouncer by specifying a configuration file. Verbose mode provides additional debugging information.

```bash
dbt-bouncer --config-file <PATH_TO_CONFIG_FILE>
```

```text
Running dbt-bouncer (X.X.X)...
Loaded config from dbt-bouncer-example.yml...
Validating conf...
```

```bash
dbt-bouncer --config-file <PATH_TO_CONFIG_FILE> -v
```

```text
INFO: Running dbt-bouncer (0.0.0)...
DEBUG: config_file=PosixPath('dbt-bouncer-example.yml')
DEBUG: config_file_source='COMMANDLINE'
DEBUG: Config file passed via command line: dbt-bouncer-example.yml
DEBUG: Loading config from /home/user/dbt-bouncer/dbt-bouncer-example.yml...
INFO: Loaded config from dbt-bouncer-example.yml...
```

--------------------------------

### Configure check_model_grant_privilege in manifest_checks

Source: https://godatadriven.github.io/dbt-bouncer/stable/checks/manifest/models/access

Example configuration for the check_model_grant_privilege rule within the manifest_checks block.

```yaml
manifest_checks:
    - name: check_model_grant_privilege
      include: ^models/marts
      privilege_pattern: ^select
```
Tokens:
Raw