dbt-plan

Static analysis tool that warns about risky DDL changes before dbt run.

Like terraform plan for dbt. No warehouse connection needed. Works with any warehouse (Snowflake, BigQuery, Redshift, Postgres, etc.).

What It Does

dbt-plan analyzes compiled SQL diffs to catch dangerous schema changes at PR time:

• Column changes: detects ADD/DROP COLUMN from SQL diff
• Risk assessment: judges safety based on materialization x on_schema_change rules
• Cascade analysis: finds downstream models that reference dropped columns
• Config changes: detects materialization or on_schema_change policy changes

It does NOT execute anything, connect to any warehouse, or simulate dbt run. It reads files, compares them, and warns you.

Quick Start

pip install dbt-plan

# In your dbt project directory:
dbt-plan run               # One command: compile baseline → compile current → check

That's it. dbt-plan run handles dbt compile, snapshotting, and checking automatically.

More commands

dbt-plan init              # Generate .dbt-plan.yml config + update .gitignore
dbt-plan stats             # Analyze project readiness
dbt-plan ci-setup          # Generate GitHub Actions workflow
dbt-plan check --format github   # GitHub markdown output
dbt-plan check --format json     # JSON for CI pipelines
dbt-plan check --select model1   # Check specific model only

Output Example

$ dbt-plan check

dbt-plan -- 2 model(s) changed

DESTRUCTIVE  int_order_enriched (incremental, sync_all_columns)
  DROP COLUMN  shipping_info
  DROP COLUMN  billing_info
  ADD COLUMN   shipping_city
  Downstream: dim_customers, fct_orders (2 model(s))
  >> BROKEN_REF  fct_orders: references dropped column(s): shipping_info

SAFE  dim_customers (table)
  CREATE OR REPLACE TABLE

dbt-plan: 2 checked, 1 safe, 0 warning, 1 destructive, 1 cascade risk(s)

What Works (v0.4.1)

Scope

dbt-plan is a static analysis warning tool, not a runtime simulator.

Design principle: false warnings are OK, false safe is never OK.

Future Improvements

DDL Prediction Rules

CI Integration (GitHub Actions)

name: dbt-plan
on:
  pull_request:
    paths: ['models/**', 'macros/**']

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - run: pip install uv && uv sync
      - run: pip install dbt-plan

      # Compile and snapshot base branch
      - run: |
          git checkout ${{ github.event.pull_request.base.sha }}
          dbt compile
          dbt-plan snapshot

      # Compile current and check
      - run: |
          git checkout ${{ github.event.pull_request.head.sha }}
          dbt compile
          dbt-plan check --format github >> $GITHUB_STEP_SUMMARY

      # Block destructive changes (exit 1)
      - run: dbt-plan check

How It Works

flowchart TD
    A[dbt-plan snapshot] --> B[Save compiled SQL + manifest.json]

    C[dbt-plan check] --> D[diff_compiled_dirs]
    D --> E[base compiled SQL]
    D --> F[current compiled SQL]
    E --> G[extract_columns]
    F --> H[extract_columns]
    G --> I[base columns]
    H --> J[current columns]
    I --> K[column diff]
    J --> K
    K --> L[predict_ddl + manifest config]
    L --> M{Safety?}
    M -->|SAFE| N[exit 0]
    M -->|WARNING| O[exit 2]
    M -->|DESTRUCTIVE| P[exit 1 — block merge]
    L --> Q[find_downstream]
    Q --> R[format_text / format_github]

Contributing

See CONTRIBUTING.md for development setup, TDD workflow, and coding rules.

Architecture

src/dbt_plan/
├── columns.py      # SQLGlot column extraction (multi-dialect)
├── config.py       # .dbt-plan.yml + env var configuration
├── predictor.py    # DDL risk assessment rules + cascade analysis
├── manifest.py     # manifest.json parsing + downstream BFS
├── diff.py         # compiled SQL directory comparison
├── formatter.py    # text / GitHub markdown / JSON output
└── cli.py          # CLI: snapshot, check, init, stats, run, ci-setup

How to Contribute

Good first issues:

• Add compiled SQL fixtures in tests/fixtures/ for edge cases (UNION, subqueries, etc.)
• Improve error messages for common mistakes

Medium issues:

• ddl-reviewed label override — escape hatch for intentional destructive changes
• INFORMATION_SCHEMA integration — query warehouse for SELECT * resolution

Design decisions: See docs/architecture-decisions.md.

Supported

• dbt-core 1.7+
• Any warehouse: Snowflake, BigQuery, Redshift, Postgres, DuckDB, etc. (--dialect)
• Python 3.10+
• CTE, UNION ALL, QUALIFY, window functions, VARIANT access

License

Apache-2.0