How to Analyze a dbt Project Without a Database Connection
Sometimes you have a dbt repository but no way to run it. You got a ZIP from a client, you are reviewing a pull request on a laptop with no credentials, or the warehouse is locked down. dbt docs generate will not help you there. Here is how to analyze the project anyway, using only the SQL files.
Why dbt docs is not always possible
The standard workflow is dbt docs generate followed by dbt docs serve. That needs dbt installed, a configured profile and a working connection to your warehouse, because it collects metadata about your tables. In an audit, a code review or an air-gapped environment, none of that may be available.
The models themselves, though, already contain what a lineage graph needs. Every dependency is written in the SQL as ref() and source().
What you can learn from the SQL alone
Reading the model files as text gets you a lot:
- The full model dependency graph from sources to marts.
- Upstream and downstream paths for any model.
- Column-level lineage, including how each output column is calculated.
- A build order for the files, and any circular dependencies.
- Which source tables the project reads.
What you cannot get without a warehouse or a dbt run: row counts, test results, freshness, actual column types from the database, and compiled SQL after macros expand.
How to do it in four steps
1. Gather only the models folder
Take the models folder from the repository, or ZIP the repository. You do not need profiles, credentials or artifacts.
2. Open a SQL-reading dbt visualizer
Open the dbt lineage viewer and drop the folder or ZIP onto the page. It reads each file in your browser, so nothing is uploaded. A file that is only a SELECT is treated as a model named after the file, which is how dbt names models.
3. Explore the graph
Click models to follow upstream and downstream paths. Use the search box for a specific model or column. Dashed cards are sources: tables the SQL reads that are not created in the project.
4. Check the Issues tab
This tab is where you learn what the analysis could not see: statements it could not read, and circular dependencies. Treat it as an honest gap list.
What this approach cannot see
Be explicit about the blind spots, especially in an audit:
- Jinja that generates names: loops that build table or column names at run time cannot be followed from the source text.
- Macros: models using macros that expand into joins or columns appear incomplete.
- YAML: descriptions, tests and exposures are not read.
- Packages not in the folder: models from packages you did not include show up as sources.
If these matter for your question, compile the project somewhere that can run dbt and analyze the compiled SQL instead.
A worked example: reviewing a pull request
A pull request renames a column in a staging model. Without running anything, drop the branch's models folder into the visualizer, open the Columns tab for that staging model and click the column. The right-hand list shows every column in other models that is built from it. If the list includes a mart the author did not touch, you have found the missing change.
When to still use dbt docs
This approach complements dbt docs rather than replacing it. Use dbt docs when you want descriptions, tests and compiled SQL next to the graph. Use a SQL-reading tool when you cannot run dbt, want a fast private look, or need column lineage without extra setup. More options are compared in the best free dbt lineage tools.
Keeping it private
Because the analysis runs in the page, you can verify the privacy claim yourself: open the browser developer tools, watch the Network tab while you drop a folder, and you will see the files are not sent anywhere. This is covered step by step in how to analyze SQL lineage without uploading files to a server.
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.
- 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 dbt Lineage Viewer: step by step
- Take the models folder or a ZIP of the repository.
- Drop it into a SQL-reading dbt visualizer.
- Explore the graph and read the Issues tab for gaps.
When to use the dbt Lineage Viewer
- Audit a dbt repository you cannot run
- Review a pull request without credentials
- See lineage on a locked-down laptop
- Map a client project from a ZIP
Example
Input: models/stg_orders.sql with {{ source() }} and models/orders.sql with {{ ref() }}
Output: shop.orders → stg_orders → orders, with each column traced
Frequently asked questions
Can I see dbt lineage without a database connection?
Yes. A tool that reads your .sql model files can follow ref() and source() and draw the lineage without any warehouse connection.
Do I need to run dbt docs generate?
Not for a lineage graph. dbt docs adds descriptions, tests and catalog details, but the dependency graph can be built from the SQL text.
What is missing compared with dbt docs?
Descriptions and tests from YAML, compiled SQL after macros expand, row counts and warehouse metadata.
Is it safe for private repositories?
The files are analysed in your browser and are not uploaded, and you can confirm this in the browser Network tab.
Tip: If macros generate important columns, analyze the compiled SQL from target instead of the raw models for a more complete graph.