dbt-lineage

A fast Rust CLI tool for visualizing dbt model lineage. Parses SQL files directly to extract ref() and source() dependencies, builds a DAG, and renders it as ASCII art, Graphviz DOT, SVG, interactive HTML, or a terminal UI.

Supports both direct SQL parsing (no dbt compilation or Python runtime needed) and manifest.json for full-fidelity graphs.

Features

• Direct SQL parsing — extracts ref() and source() calls via regex, no dbt compile needed
• Manifest support — optionally read manifest.json for column metadata, materializations, and full graph fidelity
• Interactive TUI — navigate, search, and explore lineage in a terminal UI (ratatui) with Unicode box-drawing nodes, orthogonal edge routing, and full mouse support
• Impact analysis — dbt-lineage impact <model> computes downstream impact with severity scoring (Critical/High/Medium/Low)
• Lineage diff — dbt-lineage diff --base <ref> compares lineage between git refs, showing added/removed/modified nodes and edges
• Column-level lineage — trace column provenance through the DAG with confidence levels (Direct, Aliased, Derived, Star)
• 6 output formats — ASCII, Graphviz DOT, JSON, Mermaid, self-contained SVG, and interactive HTML (pan/zoom/search)
• Run dbt from TUI — execute dbt run / dbt test on selected models with scope control (+upstream, downstream+, +all+) via keyboard menu or right-click context menu
• Run status tracking — color-coded nodes show success (green), error (red), outdated (yellow), or never-run (default)
• Path highlighting — trace upstream/downstream paths with impact analysis in the TUI
• Selector expressions — filter by tag, path, or model name (-s tag:finance,path:marts)
• Node type support — models, sources, seeds, snapshots, tests, exposures

Installation

From crates.io

cargo install dbt-lineage

From source

git clone https://github.com/sipemu/dbt-lineage-viewer.git
cd dbt-lineage-viewer
cargo install --path .

The binary is installed to ~/.cargo/bin/dbt-lineage.

Usage

Static output

# Full lineage of current directory's dbt project
dbt-lineage

# Focus on a specific model
dbt-lineage stg_orders

# Point at a different project directory
dbt-lineage -p path/to/dbt/project

# Show 2 levels upstream, 1 downstream
dbt-lineage stg_orders -u 2 -d 1

# Include seeds, tests, snapshots, exposures
dbt-lineage --include-seeds --include-tests --include-snapshots --include-exposures

# Selector expressions
dbt-lineage -s tag:finance,path:marts

# Use manifest.json instead of parsing SQL
dbt-lineage --manifest target/manifest.json

# Output formats
dbt-lineage -o dot > lineage.dot        # Graphviz DOT
dbt-lineage -o json                      # JSON graph
dbt-lineage -o mermaid                   # Mermaid diagram
dbt-lineage -o svg > lineage.svg         # Self-contained SVG
dbt-lineage -o html > lineage.html       # Interactive HTML (pan/zoom/search)

Interactive TUI

dbt-lineage -i
dbt-lineage -i -p path/to/dbt/project
dbt-lineage -i stg_orders -u 3 -d 3

Impact analysis

Compute downstream impact for a model with severity scoring:

dbt-lineage impact orders -p path/to/project          # text report
dbt-lineage impact orders -o json                      # JSON for CI
dbt-lineage impact orders --manifest target/manifest.json

Severity levels:

• Critical — impacts exposures (dashboards, reports)
• High — impacts table/incremental materializations or mart models
• Medium — impacts staging or intermediate models
• Low — impacts tests only

Lineage diff

Compare lineage between git refs to see what changed:

dbt-lineage diff --base main                           # compare main to working tree
dbt-lineage diff --base main --head feature-branch     # compare two branches
dbt-lineage diff --base HEAD~1 -o json                 # JSON for CI integration

Shows added, removed, and modified nodes and edges with a summary of changes.

CLI Reference

Usage: dbt-lineage [OPTIONS] [MODEL] [COMMAND]

Commands:
  impact  Compute downstream impact analysis for a model
  diff    Compare lineage between git refs

Arguments:
  [MODEL]  Model name to focus on (shows full lineage if omitted)

Options:
  -p, --project-dir <PATH>    Path to dbt project directory [default: .]
  -u, --upstream <N>           Upstream levels to show (default: all)
  -d, --downstream <N>         Downstream levels to show (default: all)
  -i, --interactive            Launch interactive TUI mode
  -o, --output <FORMAT>        Output format [default: ascii]
                               [values: ascii, dot, json, mermaid, svg, html]
  -s, --select <SELECTOR>      Selector expression: tag:X, path:Y, or model name (comma-separated)
      --manifest <PATH>        Use manifest.json instead of parsing SQL
      --include-tests          Include test nodes
      --include-seeds          Include seed nodes
      --include-snapshots      Include snapshot nodes
      --include-exposures      Include exposure nodes
  -h, --help                   Print help

TUI Keybindings

Navigation

Mouse

Search

Analysis

Node list panel

Running dbt

Run menu / context menu options:

General

Node colors in TUI

By run status (when target/run_results.json exists):

By node type (when never run):

How it works

1. Parse dbt_project.yml to find model/seed/snapshot paths (or read manifest.json)
2. Walk those directories, collecting .sql and .yml files
3. Extract ref('model') and source('schema', 'table') from SQL via regex
4. Parse YAML schema files for sources, model descriptions, and exposures
5. Build a directed acyclic graph (petgraph) where edges flow from dependency to dependent
6. Resolve column-level lineage by tracing SELECT/FROM/JOIN through the graph
7. Filter by focus model, depth, selectors, and node type
8. Layout using a Sugiyama-style layered algorithm (longest-path layering + barycenter ordering)
9. Render as ASCII, DOT, JSON, Mermaid, SVG, HTML, or interactive TUI

uv / virtualenv support

When running dbt from the TUI, the tool auto-detects whether to use uv run dbt or plain dbt:

• If uv.lock or pyproject.toml exists in the dbt project directory, uses uv run dbt
• Otherwise, if dbt is on PATH, uses it directly
• If dbt is not on PATH but uv is, falls back to uv run dbt

Building without TUI

The TUI is enabled by default. To build a minimal binary with only static output:

cargo build --release --no-default-features

License

MIT