🕵️ dbtective

dbtective is a Rust-powered 'detective' for dbt metadata best practices. As your dbt project grows, keeping metadata consistent and high-quality can become a real challenge.

Explore the full documentation or the possible rules.

dbtective makes it easy to spot and fix common issues, examples:

• Missing descriptions: Does every model and seed have a description?
• Column types: Are all columns explicitly typed?
• Ownership: Do all sources have an owner?
• Naming conventions: Are all marts following your team's naming standards?

We detect and enforce these rules in your cli, prek/pre-commit and CI/CD pipeline, so fast you will barely notice🕵️.

Supports dbt Core v1 and v2, including v2's new Parquet artifacts.

Installation

pip install dbtective

uv add dbtective --dev

brew install feliblo/tap/dbtective

- uses: feliblo/dbtective@v0.3.5
  with:
    config-file: "dbtective.yml"
    entry-point: "."
    only-manifest: "true"
    verbose: "false"

repos:
  - repo: https://github.com/feliblo/dbtective
    rev: v0.3.5
    hooks:
      - id: dbtective-run
        entry: dbtective run
        args: [--only-manifest, --hide-warnings, --auto-parse]

prek install
prek run --all-files
# or with pre-commit
pre-commit install
pre-commit run --all-files

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/feliblo/dbtective/releases/latest/download/dbtective-installer.sh | sh

irm https://github.com/feliblo/dbtective/releases/latest/download/dbtective-installer.ps1 | iex

Quickstart

All possible rules can be found in the rules documentation. Information about customizing dbtective is shown at the config documentation

1. Generate your config file by answering a few simple questions:

   dbtective init
   

   This walks you through picking a config format, and which rules to enable. It then generates a config you can start with. See the CLI reference for details.

2. (Optional) Generate the dbt manifest and catalog files if you haven't done so already. Most dbt commands automatically generate the manifest.json, but if you want to ensure both files are up to date, run:

   # dbt v1
   dbt compile
   dbt docs generate
   
   # dbt v2 — one command produces everything dbtective needs
   dbt build --write-index --static-analysis strict
   

   Tip: For local development and pre-commit, use --only-manifest to skip catalog.json. Eligible catalog rules will fall back to manifest data automatically.

   On dbt v2 the Parquet index carries column types itself, so --only-manifest is not needed. Note dbt docs generate was removed in v2; use dbt compile --write-catalog if you still want a catalog.json.

3. Run dbtective in the root of your current directory or specify an entry point if your dbt_project is not located in the root/current drectory.

   dbtective run
   dbtective run --entry-point "my_dbt_project"
   

4. Review the output and fix any issues found.

5. (Optional) Integrate dbtective into your CI/CD pipeline or pre-commit hooks to automate rules on every commit and/or pull request.

Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes dbtective better for everyone.

For detailed contributing guidelines, development setup, and coding standards, please see the contributing documentation.

Acknowledgements

This project is heavily inspired by dbt-bouncer. It tries to improve certain aspects of the amazing work by pgoslatara, while giving me an opportunity to improve my Rust. More about the aspects we try to improve is available in our FAQ.