Skip to content

v0.18.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 06 Oct 02:42
· 2 commits to main since this release
v0.18.0
533fb1d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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

Assets 4
Loading