dbt-plan MCP server

dbt-plan

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

Like terraform plan for dbt, and used the same way: you run it before the thing that changes your warehouse, not only in CI afterwards.

Analyzes compiled SQL files from warehouses including Snowflake, BigQuery, Redshift, Postgres and DuckDB through one code path. SQL dialect support varies; see analysis limits.

What It Looks Like

$ dbt-plan check

dbt-plan -- 4 model(s) changed
  dialect: snowflake (default; adapter: unknown)
  baseline: unknown revision, unknown snapshot time

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

SAFE  dim_customers (table)
  CREATE OR REPLACE TABLE

SAFE  dim_publishers (table)
  CREATE OR REPLACE TABLE

SAFE  fct_daily_sales (incremental, append_new_columns)
  ADD COLUMN  total_sales

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

What It Does

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

name it, resolved against the project's own schema rather than matched as text; the ones that select * and lose it without their own file changing; and the tests whose fixtures pin it down. Names the exposures whose owners need telling

• Column changes: detects ADD/DROP COLUMN from SQL diff
• Risk assessment: judges safety based on materialization x onschemachange rules
• Cascade analysis: finds downstream models broken by a dropped column — the ones that

• Contracts: reports a change an enforced contract will reject, in either direction
• Config changes: detects materialization or onschemachange policy changes
• Type changes: compares explicit CAST types between revisions
• SELECT resolution**: reads the columns from the CTEs of the same statement, and follows a ref() into the referenced model's compiled SQL

The analysis reads files, compares them, and warns; it does not connect to a warehouse or simulate dbt run. The optional dbt-plan run workflow invokes your compile command, which can require credentials and execute macros.

Quick Start

See a result without a warehouse

The repository includes before/after compiled SQL and a manifest, so you can try the analysis without installing dbt or configuring warehouse credentials:

git clone --depth 1 https://github.com/PresentJay/dbt-plan
cd dbt-plan
python -m pip install dbt-plan
bash examples/sample-project/run-example.sh

The sample prints text, GitHub markdown and JSON output. It intentionally contains a dropped column, so the inner check reports exit code 1 (destructive); the example script itself completes successfully. See the sample scenario for the expected finding.

Use it with your dbt project

python -m pip install dbt-plan
dbt-plan run               # compile baseline → compile current → check

dbt-plan run does the whole thing in one command and needs whatever credentials your dbt compile normally needs. If your project already has compiled artifacts, use dbt-plan check directly; it only reads local files and does not connect to a warehouse.

The loop it is built for

Once you have a baseline, the inner loop is a single sub-second command. Edit a model or a macro, recompile, and see what dbt run would do — before running it:

Shortened. The full README is on GitHub.