dbt-plan

Static analysis tool that warns about risky DDL changes before dbt run. Like terraform plan for dbt.

pip install dbt-plan

Get started in 2 minutes

1Install

One package, one dependency (sqlglot). No warehouse connection needed.

pip install dbt-plan

2Run

One command handles everything: compile baseline, compile current, check.

dbt-plan run

3Add to CI

Generate a GitHub Actions workflow that blocks destructive PRs.

dbt-plan ci-setup

What you'll see

$ dbt-plan check dbt-plan -- 3 model(s) changed DESTRUCTIVE int_unified (incremental, sync_all_columns) DROP COLUMN data__device ADD COLUMN data__device__uuid Downstream: fct_events, dim_device (2 model(s)) >> BROKEN_REF fct_events: references dropped column(s): data__device WARNING fct_strict (incremental, fail) BUILD FAILURE SAFE dim_device (table) CREATE OR REPLACE TABLE dbt-plan: 3 checked, 1 safe, 1 warning, 1 destructive, 1 cascade risk(s)

What it checks

Column changes

Detects ADD/DROP from compiled SQL diffs. Flags sync_all_columns drops as DESTRUCTIVE.

Cascade analysis

Finds downstream models that reference dropped columns or will fail from schema changes.

Config changes

Detects materialization or on_schema_change policy changes between snapshots.

CI-ready

Exit codes (0/1/2), JSON output, GitHub markdown. One-line summary for grep.

Multi-dialect

Snowflake, BigQuery, Postgres, Redshift, DuckDB, and more via --dialect.

Zero runtime deps

Only sqlglot. No warehouse connection. Analyzes files on disk, nothing else.

CI integration (GitHub Actions)

Add to your PR workflow. Blocks merge on destructive changes.

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

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

      - run: |
          git checkout ${{ github.event.pull_request.base.sha }}
          dbt compile && dbt-plan snapshot

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

      - run: dbt-plan check  # exit 1 blocks merge

Design philosophy

Principle	Meaning
False safe = never	If we can't determine safety, we warn. Never silently pass.
False warning = OK	Over-warning is fine. Use ignore_models to suppress.
No runtime deps	Only sqlglot. No warehouse connection needed.
CI-first	Exit codes, structured output, one-line summary.