dbt-chequer

A unified CLI for dbt quality checks. Instead of configuring SQLFluff, dbt-bouncer, dbt-coverage, and pre-commit hooks separately, install one package and run an interactive wizard.

dbt-chequer wraps:

• SQLFluff - SQL linting and formatting
• dbt-bouncer - Governance and convention rules
• dbt-coverage - Test and documentation coverage
• dbt-checkpoint - Pre-commit hooks for dbt
• prek - Modern pre-commit hook runner

Plus automated GitHub Actions workflows and a CLI wizard for quick setup.

Installation

pip install dbt-chequer

# Or with uv
uv add dbt-chequer

Quick Start

# Interactive setup wizard
dbt-chequer init

# Run all checks
dbt-chequer check

# Check your setup
dbt-chequer doctor

Features

Interactive Setup Wizard

dbt-chequer init

The wizard will:

1. Detect your dbt project and warehouse adapter
2. Ask which quality categories to enable (Formatting, Documentation, Coverage, Governance, Data Quality)
3. Configure each tool with sensible defaults
4. Generate tool-specific config files:
   • .sqlfluff - SQL linting rules
   • dbt-bouncer.yml - Governance rules
   • .pre-commit-config.yaml - Git hooks
   • .github/workflows/dbt-quality.yml - GitHub Actions

Tool-Specific Configuration

dbt-chequer generates standard config files that each tool recognizes. No unified config file to learn - just the configs you already know:

.sqlfluff                          # SQLFluff configuration
dbt-bouncer.yml                    # dbt-bouncer rules
.pre-commit-config.yaml            # Pre-commit hooks
.github/workflows/dbt-quality.yml  # GitHub Actions

This means you can:

• Use each tool's native CLI directly
• Reference official documentation
• Migrate to/from dbt-chequer easily

Unified Check Command

# Run all configured checks
dbt-chequer check

# Run specific checks only
dbt-chequer check -k sqlfluff -k dbt_coverage

# Auto-fix issues (where supported)
dbt-chequer check --fix

# Only check changed files
dbt-chequer check --changed-only

Category-Based Reporting

Results are organized by quality category:

dbt-chequer Results

Category         Status  Summary                  Issues
Formatting       Fail    4 formatting issue(s)    4
Documentation    Fail    6 missing documentation  6
Coverage         Pass    All checks passed        -
Governance       Pass    All checks passed        -
Data Quality     Pass    All checks passed        -

Configuration Presets

Choose from three presets during setup:

• Relaxed - Basic formatting only (good for existing projects)
• Standard - Formatting + documentation (recommended)
• Strict - All checks enabled (for new projects)

Or select Custom to pick individual categories.

GitHub Actions Integration

dbt-chequer generates a ready-to-use GitHub Actions workflow that:

• Runs SQLFluff linting with auto-fix
• Validates governance rules with dbt-bouncer
• Checks test/doc coverage with dbt-coverage
• Posts results as PR comments (sticky updates)
• Runs on every pull request

Pre-commit Hooks

The wizard generates .pre-commit-config.yaml with hooks for:

• Trailing whitespace removal
• End-of-file fixing
• YAML validation
• SQLFluff linting and fixing
• dbt-checkpoint validations (tests, descriptions, naming)

Install hooks with:

prek install

Status Overview

See which checks are enabled:

dbt-chequer status

Shows:

• Enabled checks by category
• Tool configurations detected
• Check counts (e.g., "5/6 enabled" for Governance)

Diagnostics

Troubleshoot your setup:

dbt-chequer doctor

Checks for:

• dbt project structure
• Required tools installed
• Config file presence
• manifest.json availability

CLI Reference

dbt-chequer init              # Interactive setup wizard
dbt-chequer check             # Run all configured checks
dbt-chequer status            # Show enabled quality gates
dbt-chequer doctor            # Diagnose setup issues
dbt-chequer checks            # List all available checks
dbt-chequer --help            # Show all commands

Check Command Options

dbt-chequer check [OPTIONS]

Options:
  -k, --check TEXT       Run specific checks only (can be repeated)
  --fix                  Auto-fix issues where possible
  --changed-only         Only check changed files
  --help                 Show help

Configuration Examples

SQLFluff Configuration

Generated .sqlfluff includes:

• Dialect detection (bigquery, snowflake, postgres, etc.)
• dbt templater for Jinja
• 4-space indentation
• 100 character line length
• UPPER case keywords
• Trailing commas in SELECT
• Explicit table aliasing

dbt-bouncer Configuration

Generated dbt-bouncer.yml includes:

• Model naming conventions (stg_, int_, fct_, dim_)
• Directory structure validation
• Documentation requirements
• Test coverage requirements
• Staging model isolation
• Source freshness checks

Pre-commit Hooks

Generated .pre-commit-config.yaml includes:

• Basic file cleanup (whitespace, EOF)
• YAML formatting with Prettier
• SQLFluff linting and fixing
• dbt-checkpoint validations:
  • Model descriptions required
  • Column descriptions required
  • Model tests required
  • Macro documentation
  • Model naming contracts per directory

How It Works

1. Auto-Detection: Each check auto-detects its config file

   • SQLFluff looks for .sqlfluff
   • dbt-bouncer looks for dbt-bouncer.yml
   • prek looks for .pre-commit-config.yaml

2. Independent Execution: Checks run via subprocess

   • Wraps each tool's native CLI
   • Parses output into structured violations
   • No reimplementation of check logic

3. Category Mapping: Violations map to quality categories

   • SQLFluff rules → Formatting
   • dbt-bouncer rules → Documentation/Governance/Data Quality
   • dbt-checkpoint hooks → Multiple categories

4. Consolidated Reporting: Results combine across tools

   • Groups violations by category
   • Shows actionable fix suggestions
   • Indicates when auto-fix was attempted

Development

# Clone the repo
git clone https://github.com/kiliantscherny/dbt-chequer
cd dbt-chequer

# Install with uv
uv sync

# Run the CLI
uv run dbt-chequer --help

# Type checking
uv run ty check src/dbt_chequer

# Linting and formatting
uv run ruff check --fix src/dbt_chequer
uv run ruff format src/dbt_chequer

Requirements

• Python 3.12+
• dbt-core 1.0+
• Git (for pre-commit hooks)

License

MIT