How to Understand an Inherited SQL Project in Minutes (Free)
You start a new job and get a repository with 200 SQL files and a README that says "see Confluence". Reading them in order takes days. Drawing them takes minutes. Here is a way to get oriented quickly, whether you write SQL every day or not.
Open the SQL Data Flow Diagram Generator
Start with the big picture
Drop the project folder onto the SQL Data Flow Diagram Generator. You get raw source tables on the left, final tables on the right, and the layers in between, coloured by schema or folder. In a few seconds you know how many layers there are and which tables are the final outputs.
Find the tables that matter
Look at the Tables tab and sort your eyes to the tables that feed the most others. Those are the core of the project. Then look for tables that feed nothing: they are either the final reports or dead code.
Follow one number
Pick a column you care about, such as revenue, and trace it in the Columns tab. In three or four clicks you go from the report table back to the raw column it started from, and you read the expression at each step. That is a day of reading, done in a minute.
Check the order and the problems
The Run order tab shows which files must run first. The Issues tab lists circular dependencies and statements that could not be read. Both are good first questions for the team.
Put it in your documentation
Save the graph as a PNG and drop it in the wiki, or share a link so teammates can open the same graph and click around. A picture that was drawn from the code stays honest, which a hand-drawn diagram does not.
Keep expectations realistic
The graph is drawn from SQL text. Anything done outside the files, in orchestration code, a spreadsheet or a dashboard, will not appear. Treat it as the map, then ask the team about the roads it does not show.
Open the SQL Data Flow Diagram Generator
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 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.
Also try
How to use the SQL Data Flow Diagram Generator: step by step
- Drop the project folder onto the page.
- Click the tables with the most connections, then trace one important column.
- Save the picture as PNG or share a link for your documentation.
When to use the SQL Data Flow Diagram Generator
- Get oriented in a new SQL codebase
- Create documentation from the code itself
- Prepare questions for the team
- Explain a warehouse to a non-technical manager
Example
Input: a warehouse folder: raw, staging and marts SQL files
Output: A left-to-right data flow diagram you can save as PNG
Frequently asked questions
How do I document a SQL project quickly?
Drop the folder into a lineage tool, save the graph as a PNG and add it to your wiki. Because it is drawn from the code, it matches what the project really does.
Can a non-technical person use this?
Yes. You do not need to write SQL. Drop the files, click the boxes and read what feeds what.
Is anything uploaded?
No. All analysis happens in your browser.
Tip: Start with a sample project on the page to learn the controls in two minutes, then drop your own.