How to Identify Downstream Dependencies Before Changing SQL
Renaming one column sounds harmless until the dashboard stops loading on Monday morning. The fix is to look before you change. This guide shows how to identify everything downstream of a SQL table, using only your SQL files, so a change never surprises you.
The two questions to ask first
Before changing a table, ask what it is built from (upstream) and what is built from it (downstream). Downstream is the dangerous direction: those are the views, tables and reports that will break, or quietly show wrong numbers.
Why searching is not enough
A text search for the table name finds comments, strings and unrelated tables with similar names. It also misses dependants that read through a view, which is where most surprises come from. A change to a base table affects views, which affect tables built from those views.
Direct readers are only the first hop. Impact analysis needs the full transitive set.
How to find everything downstream
1. Load your SQL
Open the SQL impact analysis page and drop your SQL files, a ZIP or a dbt models folder. Nothing is uploaded; the analysis runs in your browser.
2. Select the table
Click the table in the graph, or search for it. Its details bar lists the tables it is built from and shows how many tables are affected if it changes.
3. Choose Downstream
Everything that reads the table, directly or through other tables, stays visible, and the rest fades. The count next to the button tells you the size of the blast radius at a glance.
4. Check columns, not just tables
A widely used table may have a column nobody reads, or a rarely used table may hold the one column your report depends on. Open the Columns tab, choose the table and click the column. The right-hand list shows exactly which columns are built from it.
An example
You plan to drop raw.customers.legacy_id.
- Table-level downstream of raw.customers shows 9 tables. That sounds alarming.
- Column-level downstream of legacy_id shows nothing is built from it. The drop is safe from the SQL side.
Without the column view, you might have postponed a safe cleanup, or approved a risky change because "only one table reads it".
Upstream is useful too
When a number looks wrong, go the other way. Choose Upstream to see every table it is built from, then follow the column back to the raw table. A join or filter on the way often explains the difference.
Turning the result into a plan
- Update: modify the affected objects in dependency order, upstream first.
- Test: run checks on every affected table, especially those whose links are calculations.
- Tell owners: warn teams who own affected tables before the change.
- Stage it: add new alongside old, migrate, then remove.
What this does not cover
Only your SQL files are read. A dashboard, a Python script or a spreadsheet that reads the table directly is not in the files, so check those separately. Dynamic SQL built from strings cannot be followed, and column lineage is best effort. The Issues tab lists statements that could not be read.
A pre-change checklist
Use this short list before you rename, retype or drop anything:
- List the downstream tables and views of the table, and the downstream columns of the specific column.
- Note which links are calculations, because they need numeric tests, not just a successful run.
- Search outside your SQL repository for dashboards, notebooks and application code that read the object directly.
- Ask the owners of affected tables whether they have deadlines or reports that run soon.
- Decide the rollback: how will you restore the old name or type if something fails?
Common surprises
A few things catch people out even with a good dependency list. A view that selects everything from a table picks up new columns automatically, so adding a column can break a downstream table with a fixed column list. A column rename breaks anything that referenced it by name, including saved queries nobody remembers. And a type change on a source column can quietly alter results in calculated dependants, such as integer division or rounding, without raising an error.
These are the reasons to treat downstream lists as a starting point for testing rather than as a sign-off.
Related reading
For the column-level method, read how to perform SQL column impact analysis. For a wider dependency inventory, see SQL dependency mapping for large data projects.
Related tool pages
- SQL Lineage Analyzer for a Folder of SQL Files: Upload a folder of SQL files or a dbt project and get table and column lineage across every file, a run order and impact analysis. Free, runs in your browser.
- 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 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 Impact Analysis: step by step
- Drop your SQL files or dbt models onto the page.
- Click the table, then choose Downstream.
- Open Columns and click a column to see which columns are built from it.
When to use the SQL Impact Analysis
- Check what breaks before renaming a column
- Find who depends on a table
- List unused tables before cleanup
- Plan a migration
Example
Input: Click raw.order_items in the graph
Output: 9 downstream tables and views would be affected
Frequently asked questions
How do I find what depends on a SQL table?
Open a lineage tool, drop your SQL files, click the table and choose Downstream. Every table and view that reads it, directly or indirectly, stays visible.
Can I check one column instead of the whole table?
Yes. In the Columns tab pick the table and click the column to see the columns built from it.
Does it check dashboards and code outside SQL?
No. It reads SQL files only. Check BI tools and application code separately.
Is this safe for private SQL?
Yes. The files are analysed in your browser and not uploaded.
Tip: Put a screenshot or share link of the downstream view in your change request so reviewers see the same impact you saw.