dbt Flow Lineage

Animated column-level lineage visualization for dbt projects.

See exactly how each column flows through your dbt models from source to final table with color-coded animated paths that show passthrough, renames, transforms, and aggregations.

Screenshots

Model-Focused View with Direction Filters

Click any model in the sidebar to see its lineage. Use the Both / Upstream / Downstream toggle to control what's visible.

Draggable Layout

Drag model nodes to rearrange the graph. Edges and particles follow automatically.

Column Path Tracing

Click any column to highlight its full upstream/downstream path. Unlinked columns grey out. Particles speed up on the selected path.

Full Lineage for Complex Models

View the complete lineage of OBT (One Big Table) models spanning sources through staging, dimensions, and facts.

Features

Column-Level Lineage

Every column gets its own traced path showing where it comes from and where it goes. Click any column to highlight its full upstream and downstream journey.

Animated Data Flow

Glowing particles flow along column edges, visualizing data propagation through your models in real time.

Transformation Classification

Each column edge is color-coded by how the data changes:

Model-Focused View

Right-click any .sql file or click a model in the sidebar to see only that model's lineage. Filter by Upstream, Downstream, or Both.

Draggable Nodes

Drag model boxes to rearrange the graph layout. Edges and animations follow automatically.

Native IDE Integration

• Activity Bar icon with model/column tree sidebar
• CodeLens annotations above SELECT statements
• Right-click context menu on .sql files
• Status bar showing model count
• Keyboard shortcuts: +/- zoom, Esc clear, 0 fit-to-view
• Colored startup banner in the Terminal panel

Installation

Option 1: From VS Code Marketplace (recommended)

Search for "dbt Flow Lineage" in the Extensions tab and click Install.

Option 2: Download from GitHub Releases (latest updates)

1. Download the latest .vsix from GitHub Releases
2. In VS Code / Cursor / Windsurf, go to the Extensions tab
3. Click the ... menu (top-right of Extensions panel) → "Install from VSIX..."
4. Select the downloaded .vsix file
5. Reload the window when prompted

Option 3: Install from terminal

# Download the latest release
curl -L -o dbt-flow-lineage.vsix https://github.com/tripleaceme/dbt-flow-lineage/releases/latest/download/dbt-flow-lineage-0.1.0.vsix

# Install in VS Code
code --install-extension dbt-flow-lineage.vsix

# Install in Cursor
cursor --install-extension dbt-flow-lineage.vsix

Option 4: Build from source

git clone https://github.com/tripleaceme/dbt-flow-lineage.git
cd dbt-flow-lineage
npm install
npm run build
npx vsce package
code --install-extension dbt-flow-lineage-0.1.0.vsix

Requirements

What you need

1. A dbt project with models
2. Columns defined in schema.yml — this is the only requirement. Every column you want to track must be listed:

models:
  - name: dim_artists
    columns:
      - name: artist_id
      - name: artist_name
      - name: total_streams
      # ... all columns you want to trace

3. Run dbt compile (or dbt docs generate) to create manifest.json

What works automatically

• SELECT * in CTEs and final selects
• Complex CTEs with multiple joins
• Jinja templates ({{ ref() }}, {{ source() }})
• Nested functions like round(sum(x) / 3600.0, 2)
• SELECT syntax accepted by the PostgreSQL grammar in node-sql-parser; other warehouse dialects are not guaranteed. Unsupported or ambiguous SQL produces a visible unresolved status instead of guessed column edges.

Extension Settings

Commands

Keyboard Shortcuts

Compatibility

Works on:

• VS Code 1.85+
• Cursor
• Windsurf
• VSCodium
• Any VS Code fork

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions, project structure, and PR guidelines.

License

MIT

Lineage semantics and limitations

Column edges describe inputs to selected values, not row-level provenance. Table aliases, renames, expressions, CASE, aggregates, non-recursive CTEs and derived tables are resolved structurally. Constants and COUNT(*) have no selected-value column dependencies. Join/WHERE predicates alone do not create output-column edges. Quoted column names are normalized to lowercase, consistent with the existing artifact model; case-sensitive identifiers that differ only in case are not supported.

Generate compiled SQL with dbt compile for macros and control flow. Raw SQL supports only explicit ref and source calls with literal arguments. Arbitrary Jinja, recursive queries, set operations, scalar/correlated subqueries, NATURAL/USING/lateral joins and unknown or ambiguous references are conservatively left unresolved. Model-level dependencies remain visible. Detailed reasons appear in model tooltips.

Documented manifest columns take priority. A catalog supplies types and fills an absent column list; it does not augment a partially documented list. Wildcards expand against the available metadata, so completeness depends on that metadata. “Models resolved” reports the percentage of dependent models whose listed outputs were resolved, including constants; it is not an accuracy percentage.

Run npm test, npm run typecheck, npm run lint and npm run build before releasing. Tests invoke the production parser and builder, including the 30 research diagnostic cases and additional ambiguity/unsupported-SQL checks.