Faultline

See what your dbt change breaks — before you merge it.

Faultline is a static, warehouse-free impact analysis tool for dbt pull requests. It reads two manifest.json snapshots (the base branch and your PR branch) and tells you exactly which downstream models and columns your change will break — posted right on the pull request.

It never connects to your warehouse. Your data never leaves CI.

Why

A one-line change to a dbt model — renaming or removing a column — can silently break downstream models and the dashboards built on them. You usually find out after it ships. Faultline catches it at review time, inside the pull request, before it merges.

Install

pip install b9x-faultline

Use it locally

# 1. Build the manifest from your main branch
git checkout main && dbt compile && cp target/manifest.json base.json

# 2. Build the manifest from your PR branch
git checkout my-branch && dbt compile && cp target/manifest.json head.json

# 3. See the impact
faultline --base base.json --head head.json

Add --fail-on-break to make it exit with an error when a breaking change is found (useful in CI). Use --dialect snowflake (or bigquery, postgres, …) to match your warehouse's SQL.

Use it in GitHub Actions

Copy .github/workflows/faultline.yml into your dbt repo. On every pull request it compiles both branches, runs Faultline, and posts the impact report as a comment — failing the check if a breaking change is found.

What it reports

How it works

Faultline parses your dbt SQL with sqlglot — it reads the code, it never runs it. That's why it needs no warehouse, no credentials, and no access to your data. It builds the downstream dependency graph from your manifest, then checks each affected model's columns against what changed.

Honest limits

This is static analysis. On very complex, multi-hop SQL it will sometimes mark a downstream model as info — review this rather than a definitive breaking. It degrades safely — it surfaces the affected model for review and never goes silent — but deep column-level tracing across many layers is an area we're actively improving.

License

MIT — see LICENSE.

Contact

Built by B9X · admin@b9x.ai · https://github.com/b9x-ai/faultline