dbterd-vscode
A VS Code extension that turns your dbt project into an interactive ERD — zoom,
pan, click a table to open its SQL, follow FK edges like breadcrumbs. Powered
by dbterd under the hood.
Install
From the VS Code Marketplace: search for dbt ERD and click Install.
Or grab a .vsix from the Releases page
and install with:
code --install-extension dbterd-vscode-<version>.vsix
You'll need Python 3.10+ on PATH — the extension spawns a small FastAPI
server that wraps the dbterd library.
Usage
- Open the Command Palette (
Cmd/Ctrl+Shift+P).
- Run dbterd: Open ERD.
- The ERD opens in a new panel. Click a table header to jump to its SQL.
- Run dbterd: Refresh ERD after
dbt compile / dbt docs generate to
pick up manifest changes.
Settings
| Setting |
Default |
Description |
dbterd.dbtProjectPath |
"" |
Absolute path to the dbt project root. |
dbterd.serverPort |
0 |
Port for the local server. 0 = auto-pick. |
dbterd.pythonPath |
"" |
Optional override for the base Python interpreter. Leave empty to auto-detect (dbt project .venv → $VIRTUAL_ENV → python3 on PATH). |
How it works
Three layers dressed up as one extension:
- A FastAPI server wraps
dbterd and serves /erd as JSON.
- A React +
@xyflow/react webview renders that JSON as draggable table
cards with FK edges between columns.
- A TypeScript extension host spawns the server on activate, hosts the
webview, and pipes click-to-open-SQL messages back to VS Code.
┌──────────────────────────────┐
│ VS Code Extension Host │ activate() → spawn server, open webview
└──────────────┬───────────────┘
│ child_process
▼
┌──────────────────────────────┐
│ dbterd-server (FastAPI) │ GET /erd → { nodes, edges, … }
└──────────────▲───────────────┘
│ fetch
┌──────────────┴───────────────┐
│ Webview (React + reactflow)│ renders custom table-card nodes
└──────────────────────────────┘
Contributing
PRs welcome. This repo is built for agentic development (Claude Code is a
first-class contributor), but regular human PRs work just as well. See
CONTRIBUTING.md for setup, conventions, the /erd
contract rules, and release process.
A standing ovation to the humans who steer the agents (and occasionally remind
them which file the contributor list belongs in). Agents may write the code,
but merges still need a human to click the button — well done, human drivers ❤️
Support
⭐ If this extension is useful, please star the repo on GitHub — it helps others discover it and keeps the maintainer motivated to keep shipping.
🍰 And if this extension saves you from squinting at manifest.json at 2 AM,
consider sponsoring a coffee — or, in 2026 currency, roughly 1M Claude tokens.
Either way, the late-night bug hunts stay fueled and the agents stay fed.
