dbt-plan v0.18.2 — keep separate warnings visible in summaries

dbt-plan v0.18.2 — keep separate warnings visible in summaries

Text and GitHub reports now put report-wide review status before model rows and
append it to the final summary. A safe model DDL operation no longer leaves the
reader with a final 0 warning count without the separate review status.

Upgrade

pip install --upgrade dbt-plan==0.18.2
# For the optional MCP server:
pip install --upgrade 'dbt-plan[mcp]==0.18.2'

What changes

• A report with safe replacement DDL and an unreadable downstream read starts
  with Review required: WARNING and ends with
  overall review: WARNING (before policy).
• Next actions cover unresolved SQL/columns, incomplete or mismatched artifacts,
  stale sources and missing/corrupt historical baselines. Repeated actions are
  deduplicated. Unknown evidence still requires review.
• Reports show ignored models as not checked and limit no-risk statements to
  supplied artifacts. This is not full project coverage accounting.

Compatibility

JSON fields, model DDL counts, canonical findings, graph evidence, MCP verdicts
and CLI exit policy retain their meaning. summary.warning counts model
predictions, not every finding. Human text gains a status section and a suffix
on its grepable dbt-plan: summary; machine consumers should use JSON.

The new status reuses the existing standard-library-only MCP/CI report consumer.
The base CLI does not require the optional MCP dependency. Acknowledging a risk
or choosing --fail-on never can permit exit 0 without changing raw review status.
Execution errors still exit 3 and do not produce a completed report.

No warehouse behavior, expanded adapter support, pilot adoption or usability
improvement is claimed. The package release does not move the Marketplace v1
tag. See reading review status.

Full changelog

v0.18.1

dbt-plan v0.18.1 — preserve snapshots and model identity

This patch fixes snapshot publication and model readiness counts, and prevents
relation or version-alias collisions from hiding changes or downstream failures.
It remains a static file analyzer with sqlglot as its only runtime dependency.

Upgrade

pip install --upgrade dbt-plan==0.18.1
# For the optional MCP server:
pip install --upgrade 'dbt-plan[mcp]==0.18.1'

Unresolved SELECT * in added or modified SQL now appears in parse_failures,
even when replacement DDL is safe. The default warning policy can therefore
exit 2 on changes that previously passed. Explicit exit policies still apply;
use explicit output columns or sufficient relation metadata to resolve them.

Fixes

• Validate staged snapshot layout and inventory before publication. Unreadable
  input fails with exit 3 while preserving the previous baseline; regenerate
  compiled input before retrying. Legacy reader recovery behavior is retained.
• Count each enabled root model node ID once, including distinct versions.
  Add summary.model_sql and missing/unclassified node lists. Existing JSON
  select_star and columns_readable fields retain SQL-file count semantics;
  their text labels now explicitly identify files.
• Match validated, normalized model paths and physical relations. Qualified
  source, seed or package references cannot borrow another model's columns by
  basename. Quoted identifiers, CTEs, aliases and qualified stars retain dialect
  identity; uncertain SQL remains unreadable and reviewable.
• Give actual compiled filenames precedence over generated version aliases.
  Use node IDs for DAG, contract and selected-input lookups so an alias collision
  cannot substitute another model's SQL or DDL policy. Data tests retain their
  attached model's filename when the manifest supplies it.

Verification and scope

CI covers Linux and Windows Python 3.10–3.14, minimum dependencies, built artifacts,
Core/DuckDB compilation, MCP and the composite Action. Added regression cases
exercise ordinary and selected checks, version/filename collisions, baseline
fallback, downstream contracts and data tests.

Snowflake, Postgres and BigQuery identity cases use parser fixtures. This release
does not certify live warehouse execution or Fusion full-compile compatibility.
The Marketplace v1 tag is not moved by this package release.

Full changelog

v0.18.0

dbt-plan v0.18.0 — explain risks and verify baselines

This release connects trustworthy snapshots, explicit CI policy and causal
explanations. It remains a file-only static analyzer: no warehouse connection,
no execution simulation, and no new runtime dependency beyond sqlglot.

Upgrade

pip install --upgrade dbt-plan==0.18.0
# For an MCP installation:
pip install --upgrade 'dbt-plan[mcp]==0.18.0'

Review these behavior changes before upgrading CI:

1. Unresolved reads require review. An unresolved downstream SQL read not
   already represented by a risk/refusal now creates a separate, unwaivable
   input.refusal warning. A check that previously passed can exit 2 under the
   default policy. Acknowledging the source or reader does not waive this refusal.
   The original DDL finding stays intact; MCP returns review_required even when
   an explicit policy permits exit 0. Candidate dependencies, unknown root
   attribution and external coverage alone do not create blanket warnings.
2. Damaged snapshots stop analysis. New snapshots record a layout version
   and a SHA256 inventory of the manifest and regular compiled SQL files.
   Unsupported/malformed metadata, changed digests, missing or unexpected SQL,
   or inventoried snapshots containing symlinks/junctions cause exit 3, before a
   completed report. Compile the intended baseline revision and run
   dbt-plan snapshot again to recover. Do not delete metadata to bypass a check.
   Older snapshots without inventories remain readable as unrecorded; checking
   does not silently upgrade them. Integrity verifies bytes, not SQL safety or
   authenticity, and does not protect against concurrent edits.
3. Reports contain more detail. Text and GitHub output now include bounded
   causal explanations. Use JSON rather than parsing presentation text. Existing
   report fields remain, with additive findings, causal_graph, ignored-model
   and baseline metadata. Missing additive fields in legacy reports are not proof
   of an empty or safe analysis. Graph indices refer to the accompanying findings
   array, not durable identifiers.

Choose the exit policy explicitly

dbt-plan check --fail-on warning
dbt-plan run --fail-on destructive

Resolution is CLI flag > DBT_PLAN_FAIL_ON > fail_on in .dbt-plan.yml > legacy
behavior. Without the new setting, warning_exit_code still applies, including
its default of 2 and opt-out value 0. Explicit --fail-on warning forces warnings
to fail (using 2 when the configured warning code is 0); destructive permits
completed warnings; never permits completed findings. Execution errors always
remain exit 3. Raw risks and refusals are never erased by policy.

The Action and generated workflow keep their own gate policy and legacy warning
opt-out behavior. Their raw verdict can be destructive or warning even when
exit-code is 0. This deliberately differs from explicit CLI --fail-on warning.
Review package pins, Action references and generated workflow settings together;
upgrading the package does not rewrite existing workflow files. The mutable
Marketplace v1 tag is not moved by this package release.

See the exit policy guide.

Understand the cause, not just the count

• Canonical findings preserve qualified source/affected identities, raw severity,
  stable rule codes and exact, conservative or unknown evidence across CLI,
  JSON, GitHub, MCP and CI consumers.
• Causal graphs distinguish direct compiled reads from candidate dependencies,
  fallback references and unknown attribution. A supported direct read does not
  prove an entire root-to-target path.
• Human output shows a bounded representative route and discloses omitted
  associations, edges, steps and columns. JSON retains the full relevant graph;
  the analyzer does not enumerate every possible path.
• Trusted original file links stay separate from compiled SQL locations; no Jinja
  source lines are invented. Exposures are declared consumers, not a guarantee
  that every external consumer was analyzed.
• Ignored models and unmatched ignore names are visible. An excluded model is
  not presented as checked or safe.

Read the three reproducible examples.

Bounded MCP analysis

MCP plan waits at most 120 seconds for its analysis subprocess by default.
DBT_PLAN_MCP_PLAN_TIMEOUT_SECONDS accepts integers from 1 through 3600. A timeout
returns an error and discards partial output; it is never permission to run dbt.
The limit covers the subprocess wait, not total request latency, and does not
apply to MCP snapshot or the standalone CLI.

Verification and scope

Required CI covers Python 3.10–3.14 on Linux and Windows, minimum dependencies,
built artifacts, real dbt/DuckDB compilation, MCP and the composite Action.
The release workflow tests and builds the tagged source, verifies artifacts,
then publishes to PyPI, GitHub Releases and the MCP registry.

This release includes product PRs #299–#307 and the contributor CI feedback
dependency update in #298. Reproducible examples are not a usability study;
neither static analysis nor an integrity check certifies warehouse runtime safety.

Full changelog

v0.17.0 — resource-scoped approvals and safer reports

dbt-plan v0.17.0 — resource-scoped approvals and safer reports

This release tightens acknowledgement policy and protects snapshot and report
boundaries. It also includes machine-readable project statistics.

Upgrade: review acknowledgements

pip install --upgrade dbt-plan==0.17.0

An acknowledgement now covers only the named resource's known findings.
Acknowledging an upstream model no longer accepts downstream risks automatically.
Review existing acknowledge_models lists and --acknowledge flags: previously
passing CI can now exit 1 (destructive) or 2 (warning).

For example, if the view stg_orders loses a column inherited by the incremental
fct_orders model using sync_all_columns, acknowledging only stg_orders does
not waive the drop on fct_orders. Review and explicitly acknowledge the affected
resource if that change is intended. Unknown findings and ambiguous identities
cannot be acknowledged away. Raw JSON and MCP risks stay visible even when policy
permits the change.

See the migration guide.

Improvements

• Recoverable snapshot publication preserves the previous baseline when staging
  or publication fails. A failed restoration retains a backup and reports where
  to recover it. Concurrent writers and power-loss durability are not guaranteed.
• MCP validates report structure and consistency before classifying safety.
  Malformed or incomplete reports are errors, not all-clear results.
• A versioned JSON Schema and actual CLI contract tests cover check reports.
  Additive fields remain compatible; schema validation is not a safety verdict.
• dbt-plan stats --format json exposes project statistics for automation.

Verification

Required CI covers Linux and Windows on Python 3.10–3.14, minimum dependencies,
built packages, real dbt/DuckDB execution, MCP and the composite Action. The release
workflow tests and builds the tagged source, checks packaged artifacts, then
publishes to PyPI, GitHub Releases and the MCP registry.

Full changelog

v0.16.1

What's Changed

• Add PostgreSQL TABLESAMPLE and REPEATABLE regression fixture (#233) by @proobker in #264
• Add PostgreSQL AT TIME ZONE projections regression fixture (#234) by @proobker in #265
• Add DuckDB SEMI and ANTI JOIN projections regression fixture (#237) by @proobker in #268
• Add PostgreSQL correlated LATERAL aggregate regression fixture (#235) by @proobker in #266
• Add BigQuery SAFE_OFFSET array projections regression fixture (#238) by @proobker in #269
• Add Snowflake COUNT_IF and IFF aggregate projections regression fixture (#240) by @proobker in #271
• Add Trino map subscript and element_at projections regression fixture (#239) by @proobker in #270
• DuckDB GROUP BY ALL projection fixture (#204) by @proobker in #276
• PostgreSQL DISTINCT ON projection fixture (#201) by @proobker in #273
• Add DuckDB ASOF JOIN projections regression fixture (#236) by @proobker in #267
• PostgreSQL named WINDOW projection fixture (#203) by @proobker in #275
• PostgreSQL aggregate FILTER projection fixture (#202) by @proobker in #274
• BigQuery UNNEST WITH OFFSET projection fixture (#205) by @proobker in #277
• Document a warehouse-free minimal reproduction for findings and CLI errors (#241) by @proobker in #272
• Update bug report form for inferred dialects and execution errors (#214) by @proobker in #283
• DuckDB list-comprehension projection fixture (#213) by @proobker in #280
• fix: parse inline unit-test CSV headers by @mgalore in #287
• Add Windows development quickstart (#216) by @proobker in #285
• Document config file syntax (#215) by @proobker in #284
• PostgreSQL ordered-set aggregate projection fixture (#211) by @proobker in #278
• PostgreSQL GROUPING SETS and GROUPING projection fixture (#212) by @proobker in #279
• Document terminal output settings and their precedence (#206) by @proobker in #281
• Document the stats report with a reproducible local example (#207) by @proobker in #282
• Improve first-run onboarding by @PresentJay in #290
• Prepare v0.16.1 release by @PresentJay in #291

Full Changelog: v0.16.0...v0.16.1

v0.16.0 — stronger safety checks and explicit CI errors

dbt-plan v0.16.0 — stronger safety checks and explicit CI errors

This release expands analysis and changes the CLI error contract. Read the upgrade
notes before updating CI consumers from 0.15.x.

Breaking changes

• Execution failures exit 3. Completed destructive findings still exit 1 and
  review findings still use warning_exit_code (default 2). Invalid arguments,
  unreadable configuration, missing required inputs, compile failures and recovery
  failures cannot be accepted as completed warning reports.
• Exit code 3 is reserved. Change any warning_exit_code: 3 configuration
  before upgrading.
• Invalid selections fail. Unknown, empty or unsupported --select terms exit
  3, including a mix of valid and invalid names. Select versioned models with an
  explicit version or compiled file name.

See exit codes and migration
and selection semantics.

Highlights

• Check source and compiled-artifact evidence, including data-test SQL left behind
  by partial compilation. Invalid or incomplete inputs require review.
• Detect snapshot and Python-model changes from manifests, relation/configuration
  changes without SQL edits, and casts added or removed on one side.
• Resolve EXCLUDE/EXCEPT against known columns and preserve readable columns when
  another expression is unknown. Quoted case-sensitive identities remain explicit
  uncertainty rather than being silently folded into a match.
• Follow column losses through ephemeral models; check downstream contracts,
  generic-test predicates and overrides, versioned unit-test inputs, and exposure
  owners. SQL snapshot checks cover complete files, including multiple blocks.
• Show the analysis dialect and baseline revision/time. Use agent-setup --file
  to write guidance to a chosen instruction file.
• Preserve Git worktree/index recovery during run failures, and make generated
  CI install dependencies consistently for uv and requirements.txt projects.

Upgrade notes

1. Handle exit code 3 as an execution failure and review custom warning codes.
2. Check existing selection expressions, especially versioned models.
3. Update package and Action references together. Pin version: '0.16.0' in the
   Action if reproducibility is required; its empty version input installs latest.
4. Regenerate generated workflows to adopt the installation and gating fixes,
   then review project-specific settings. New generated CI defaults to blocking
   destructive findings while allowing completed warnings. Execution errors
   always fail, including when the Action uses fail-on: never.
5. Recompile inputs and review new warnings. Some previously successful checks
   now refuse to claim safety. Existing workflow files are not automatically
   rewritten by a package upgrade.

pip install --upgrade dbt-plan==0.16.0

The Action preserves adapter inference when dialect is empty. JSON reports gain
an analysis object, and text reports show dialect/baseline metadata; consumers
that parse terminal text or reject additional JSON fields should check their parser.

Python DataFrame schemas, live warehouse introspection and full quote-aware column
lineage remain outside this release's analysis. MCP run was deliberately not
added because checkout/stash/compile can conflict with concurrent agent edits.

Verification

Required CI covers Python 3.10–3.14 on Linux and Windows, the minimum sqlglot
version, built packages, real dbt/DuckDB execution, MCP and the composite Action.
The execution tests create incremental targets before testing the second run;
optional integrations and built-package checks must not silently skip in their
required jobs. Snowflake/Postgres behavior was not validated against live warehouses.

Full changelog
· Audit resolutions and review follow-ups

Contributors

Thank you @1cbyc and @insisong for fixing verbose configuration-file loading and adding parsing, precedence and JSON-output regression tests in #229. Your contribution shipped in v0.16.0.

v0.15.0 — safer verdicts and smoother contributions

dbt-plan v0.15.0 — safer verdicts and smoother contributions

Highlights

• Use custom target directories with run, the GitHub Action, and MCP.
• Get an explicit warning when a baseline cannot be read, and avoid false safe
  MCP verdicts when analysis refusals remain.
• Pipe run --format json into other tools without snapshot progress corrupting stdout.
• Catch deleted models even when old compiled files remain, and detect broken
  references through downstream SELECT * chains and aliased relations.
• Read shorter data-test names in human output while retaining full names in JSON.

Contributor experience

PRs to dbt-plan now get an automatically updated CI status comment with failure
links. Authors can use /ci to refresh status and /ci retry for transient
failures. External code still needs maintainer execution approval.
See the contribution guide.

Thanks to our contributors

Thank you for making dbt-plan more reliable and easier to use:

• @Akimbo92i — forward run acknowledgements to check (#125).
• @LuizPiccini — regression tests for cascade risk severity names (#126).
• @MuhammadWaleed12 — prevent false safe MCP verdicts (#137).
• @mikemikimike — custom target-directory support (#172).
• @proobker — parseable JSON stdout and explicit unreadable-baseline warnings (#175, #176).
• @1cbyc — explain missing verdicts in agent setup guidance (#178).
• @be-student — readable data-test names and the JSON output contract (#179, #180).
• @pushnanashi2 — run generated CI for every PR (#181).

Upgrade notes

Some cases that previously exited successfully now warn because analysis could
not establish safety. Review the warning rather than treating it as a regression.
Existing generated workflows must be regenerated to pick up the removal of path
filters. The contributor status bot is specific to this repository; it is not
installed into consumer projects.

pip install --upgrade dbt-plan==0.15.0

Full changelog: v0.14.0...v0.15.0

v0.14.0

What's Changed

• Stop assuming model-paths is "models" by @PresentJay in #105
• Record what dbt-plan says on jaffle_shop by @PresentJay in #107
• Add dbt-plan run --against, and say which baseline you got by @PresentJay in #117
• Say when target/ is older than the code it describes by @PresentJay in #118
• Keep dbt-plan's own snapshot out of the stash by @PresentJay in #120
• Resolve downstream references instead of searching for the name by @PresentJay in #121
• Compare a contract's declared type with the SQL's cast, by family by @PresentJay in #122
• Release 0.14.0 by @PresentJay in #123

Full Changelog: v0.13.0...v0.14.0

v0.13.0

What's Changed

• Report data tests broken by a dropped column by @PresentJay in #88
• Report a change an enforced contract will reject by @PresentJay in #89
• Analyse versioned models instead of skipping them by @PresentJay in #90
• Fire the unknown-materialization guard, and make stats agree with check by @PresentJay in #92
• Read the dialect from the manifest, and three more sharpenings by @PresentJay in #93
• Release 0.13.0 by @PresentJay in #94

Full Changelog: v0.12.0...v0.13.0

v0.12.0

What's Changed

• Report unit tests broken by a dropped column by @PresentJay in #79
• Name the exposures downstream of a change that is not safe by @PresentJay in #82
• Report a model that loses a column without its own file changing by @PresentJay in #83
• Release 0.12.0 by @PresentJay in #84

Full Changelog: v0.11.2...v0.12.0