Check What a dbt Change Breaks Before You Merge

A pull request diff shows you which lines changed. It does not show you which models are affected. In a dbt project those are different questions, and the second is the one that matters. In the SQL lineage analyzer you can make the change on a copy and get the answer from the SQL, without running dbt.

Open the SQL Lineage Analyzer

What the problem really is

Reviewing a dbt pull request, I want three answers. What changed in the model itself? What reads that model and might break? And is anything reading something that no longer exists? A line-by-line diff gives you the first, partly. The other two need the dependency graph with and without the change.

How to use it

Load the project as it is on your main branch in the SQL lineage analyzer: drop the folder, or paste a public GitHub link to the main branch. Under the graph, open Project files, click the model the pull request changes and press Edit. Paste in the version from the pull request, or make the same change by hand. The graph and the analysis update as you type, and a card called What your edits would affect compares your version with the one you loaded. Your own files are never changed, and Undo all edits puts everything back.

There is no separate step for uploading an old version. The version you loaded is the baseline, and your edit is the change.

What it reports

  • Columns that were removed or renamed while something still reads them, with the models that read them.
  • Tables that were removed while something still reads them.
  • Columns whose data type changed in a cast, and columns whose calculation changed, with how many downstream columns read them.
  • Tests removed from your dbt YAML.
  • Downstream impact: how many tables and columns the change reaches, directly or through other models.
  • Personal data that now reaches a column it did not reach before.

How "logic changed" is decided

A column counts as changed when its expression differs after cleaning up formatting. Whitespace, letter case and table aliases are ignored, so renaming an alias from o to orders does not create noise, and reformatting a query does not either. Changing a SUM to an AVG, or a CASE branch, does.

Copy the summary into the pull request

Copy summary (Markdown) gives the findings and the downstream models as text, ready to paste into the pull request description. A reviewer then sees the blast radius without opening anything. It is the closest thing to a cheap, repeatable impact check I know of that needs no warehouse. For a worked example with real output, see edit your SQL and see what breaks.

Limits you should know

These matter for deciding how much to trust the result:

  • Matching is by table name. A renamed model appears as one removed and one added table, not as a rename.
  • Only column logic is compared. A change to a WHERE clause or a JOIN condition that leaves the selected columns alone is not detected.
  • It reads text. It cannot see what a macro expands to, so a change inside a macro is not followed into the models that use it. The Macros tab shows which models use a macro, so look there before you change one.
  • It only knows the files you loaded. A dashboard or another project that reads your models is invisible to it.

So treat it as a fast first pass that catches the most common mistake, a dropped or renamed column, and not as a replacement for running tests in CI. The background on this kind of check is in what breaks if I change a SQL table.

Open the SQL Lineage Analyzer

Related tool pages

  • dbt Lineage Viewer for Your SQL Models: Drop your dbt models folder and see the lineage graph from sources through staging to marts, with column links. No dbt run, no warehouse. Free, private.
  • SQL Column Lineage Tool: See which source columns build every column of a view or table across many SQL files. Trace to the raw table or forward to dependants. Free, in your browser.
  • SQL File Dependency Analyzer: Find out which SQL file must run before which, from the tables each file creates and reads. Get a run order, circular dependencies and tables nothing uses.
  • SQL Impact Analysis: What Breaks If a Table Changes: Pick a table and see everything downstream that depends on it, and every upstream source it is built from. Works across a whole folder of SQL files, free.
  • SQL File Lineage Tool: Free SQL file lineage tool: drop a folder of .sql files and see which file feeds which table, column by column. Nothing is uploaded.
  • SQL Query Visualizer: Free SQL query visualizer: paste a query or drop SQL files and see tables, joins and columns as a clear diagram. Runs in your browser, no upload.

Also try

How to use the SQL Lineage Analyzer: step by step

  1. Load the project as it is on your main branch.
  2. Open Project files, pick the changed model, press Edit and paste in the new version.
  3. Read What your edits would affect, then copy the Markdown summary into the pull request.

When to use the SQL Lineage Analyzer

  • Review dbt pull requests
  • Catch removed columns still used downstream
  • Estimate the impact of a refactor
  • Document a release with a change summary

Example

Input: models/ folder: raw schema, staging views, marts, reports (7 .sql files)

Output: A graph of 10 tables and views, 40 column links and the order to run the files

Frequently asked questions

How can I check what a dbt change breaks before merging?

Load the project as it is today, open the changed model in Project files, press Edit and paste in the new version. A card lists the downstream models and columns that would break.

Will it tell me what a removed column breaks?

Yes. Any model that still reads a column that was removed is listed as will likely break, because that is what will fail the next time the project runs.

Does it detect changes in WHERE or JOIN conditions?

No. Only the logic of selected columns is compared. A change to a filter or a join that leaves the columns alone is not detected.

Is a renamed model detected as a rename?

No. Tables are matched by name, so a rename appears as one table removed and one added. A renamed column is recognised, though.

Does editing change my files?

No. Edits stay in your browser and Undo all edits restores the originals.

Tip: Read the Will likely break list first. It is the shortest list and the one most likely to fail the next run.