dbt-chequer 0.1.0
Setup wizard for dbt quality checks - configure SQLFluff, dbt-bouncer, and pre-commit hooks
Requires Python: >=3.12
Keywords: ci-cd, data, dbt, linting, quality, testing

# 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

```bash
pip install dbt-chequer

# Or with uv
uv add dbt-chequer
```

## Quick Start

```bash
# Interactive setup wizard
dbt-chequer init

# Run all checks
dbt-chequer check

# Check your setup
dbt-chequer doctor
```

## Features

### Interactive Setup Wizard

```bash
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

```bash
# 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:

```bash
prek install
```

### Status Overview

See which checks are enabled:

```bash
dbt-chequer status
```

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

### Diagnostics

Troubleshoot your setup:

```bash
dbt-chequer doctor
```

Checks for:
- dbt project structure
- Required tools installed
- Config file presence
- manifest.json availability

## CLI Reference

```bash
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

```bash
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

```bash
# 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