🔨 dbt Forge
Getting started · Features · Column autocomplete · Commands · Shortcuts · Settings · Privacy · Non-goals · What's next What is dbt Forge?dbt Forge is a VS Code extension for data engineers working on dbt projects (built and tested against Nothing is sent anywhere. No account, no API key, no third-party backend. dbt Forge only reads the files your own Getting startedPrerequisites
InstallOpen the Extensions view (
The extension is also on the Marketplace page, and activates on its own as soon as the folder you open contains a From a .vsix (a release download, or your own build)
From source (to hack on the extension)
Then press First run
FeaturesWrite SQL
Navigate
Catch mistakes
See the project
Preview
Run dbt
Column autocomplete: what it needsColumn suggestions come from two independent paths, which explains why they sometimes appear and sometimes don't:
Two things trip people up:
The alias must sit right after the If nothing is suggested, dbt Forge stays silent rather than guessing. Check those conditions in order. The exact rules — single-table statements, CTEs that select
|
| Command | Runs |
|---|---|
dbtForge.buildModel |
dbt build --select model for the open model, without upstream or downstream |
dbtForge.buildUpstream |
dbt build --select +model |
dbtForge.buildDownstream |
dbt build --select model+ |
dbtForge.testModel |
dbt test --select model |
dbtForge.buildProject |
dbt build for the whole project |
dbtForge.buildFolder |
dbt build --select path:<folder> for all models in a right-clicked folder |
dbtForge.buildFolderUpstream |
dbt build --select +path:<folder> — the folder's models + upstream parents |
dbtForge.buildFolderDownstream |
dbt build --select path:<folder>+ — the folder's models + downstream children |
dbtForge.buildTag |
dbt build --select tag:<tag> — every resource carrying the tag |
dbtForge.buildTagUpstream |
dbt build --select +tag:<tag> — the tag's resources + upstream parents |
dbtForge.buildTagDownstream |
dbt build --select tag:<tag>+ — the tag's resources + downstream children |
dbtForge.testTag |
dbt test --select tag:<tag> |
Compile and refresh
| Command | Does |
|---|---|
dbtForge.compileFile |
dbt compile --select path:<file> for the open file — works even if it isn't in the manifest yet |
dbtForge.parseProject |
dbt parse — regenerates manifest.json without compiling SQL or hitting the warehouse |
dbtForge.compileProject |
dbt compile for the whole project |
dbtForge.generateDocs |
dbt docs generate — writes catalog.json, which column autocomplete reads |
dbtForge.searchModels |
Quick Pick over the project's models, seeds and snapshots, opening the one you choose (also a magnifier in the dbt Forge panel's title bar) |
dbtForge.refreshIndex |
Re-reads manifest.json / catalog.json from disk (does not run dbt) |
dbtForge.refreshTags |
Re-reads the tag list from the loaded manifest |
Preview and lineage
| Command | Does |
|---|---|
dbtForge.previewCompiledSql |
Opens the compiled SQL for the open model, read-only |
dbtForge.previewData |
dbt show for the open model, or for the CTE the cursor is in — rows land in the Data Preview panel (Ctrl+Enter / Cmd+Enter) |
dbtForge.previewCte |
dbt show for one named CTE — invoked from the CodeLens on the CTE itself |
dbtForge.rerunPreview |
Re-runs the last data preview |
dbtForge.showLineage |
Opens the interactive lineage graph for the open model, seed or snapshot |
dbtForge.toggleLineageLocation |
Switches the lineage between an editor tab and the bottom panel (also a button in the Lineage view's title bar) |
State-aware builds and environment
| Command | Does |
|---|---|
dbtForge.setReferenceState |
Chooses the folder holding the reference manifest.json, and says what differs from it |
dbtForge.useCurrentAsReference |
Keeps a copy of the project's own manifest.json as the reference — for when there is no CI artefact: compile on main, run this, switch branch |
dbtForge.clearReferenceState |
Forgets the chosen reference folder |
dbtForge.buildModified |
dbt build --select state:modified+ --defer --state <reference> |
dbtForge.buildDeferred |
dbt build --select <model> --defer --state <reference> for the open model |
dbtForge.selectProfile |
Switches the profile/target dbt Forge runs dbt with (also on the status bar) |
Keyboard shortcuts
These apply while a dbt model is focused in the editor, and are inert everywhere else.
| Shortcut | Action |
|---|---|
Ctrl+Enter / Cmd+Enter |
Preview Data — the CTE the cursor is in, or the whole model when it is anywhere else |
Ctrl+K B |
Build Model |
Ctrl+K U |
Build Upstream (+model) |
Ctrl+K D |
Build Downstream (model+) |
Ctrl+K T |
Test Model |
Ctrl+K L |
Show Lineage — also on a seed's .csv |
Only the shortcut (and the Command Palette) follow the cursor into a CTE. The buttons say which scope they mean: Preview Data in a menu or in the CodeLens row is always the whole model, and Preview CTE is always that CTE. Whichever ran, the panel's header names it.
The same actions are also under the dbt Forge icon in the editor's title bar, which — unlike the CodeLens row at the top of the file — stays put when you scroll. They sit in one menu rather than as separate icons because VS Code sorts every extension's title-bar buttons into a single shared group, so loose icons end up interleaved with whatever else you have installed. On a seed's .csv the menu holds only Show Lineage, the one action that applies.
Configuration
| Setting | Default | Description |
|---|---|---|
dbtForge.pythonPath |
"" |
Path to the Python executable inside your dbt project's venv. Empty falls back to dbt on PATH |
dbtForge.projectDir |
"" |
Path to the dbt project root. Auto-detected (including nested inside a larger workspace) if left empty |
dbtForge.profilesDir |
"" |
Directory holding profiles.yml, for the environment picker. Empty looks where dbt does: DBT_PROFILES_DIR, the project root, then ~/.dbt. When set, it is also passed as --profiles-dir |
dbtForge.manifestPath |
target/manifest.json |
Path to manifest.json, relative to the project root |
dbtForge.catalogPath |
target/catalog.json |
Path to catalog.json, relative to the project root |
dbtForge.runResultsPath |
target/run_results.json |
Path to run_results.json, relative to the project root. Read after each dbt build, run or test to show each node's last status and duration |
dbtForge.compiledDir |
target/compiled |
Path to the compiled models directory, relative to the project root |
dbtForge.stateDir |
"" |
Folder holding the reference manifest.json that state-aware builds compare against (dbt --state). Relative to the project root, or absolute. Empty turns the feature off. A folder chosen with Set Reference Manifest Folder… is remembered for this machine and wins over it |
dbtForge.previewRowLimit |
100 |
Rows a data preview asks dbt for (dbt show --limit). -1 fetches every row |
dbtForge.flagUndocumentedColumns |
false |
Also warn when the table has columns the .yml doesn't document. Off by default — documenting only the columns that need explaining is a legitimate house style |
dbtForge.lineageLocation |
editor |
Where the lineage graph opens: editor (a tab beside the model) or panel (its own dbt Forge Lineage tab in the bottom panel, beside dbt Forge Preview and Terminal). From the panel, Full lineage in the graph's toolbar opens the same graph in an editor tab, where the minimap is |
dbtForge.lineageFollowsEditor |
true |
When a lineage graph is open, redraw it for whichever model, seed or snapshot you switch to in the editor. Never opens a lineage by itself, and keeps your depth and exclusion choices |
Local data & privacy
dbt Forge does not collect any data and has no network calls of its own:
- Reads
manifest.json,catalog.json,run_results.jsonand compiled SQL directly from your project'starget/folder - State-aware builds read a second, reference
manifest.jsonfrom a folder you choose. Use Current Manifest as Reference copies your project's own manifest into the extension's own storage — never into your project, so nothing appears ingit statusand dbt Forge still adds no file to your project - Reads
profiles.ymlto list the profiles and targets you can switch between. It is only ever read, never modified, and nothing from it — credentials included — leaves your machine or is written to your settings; switching environments only changes the--profile/--targetflags on the command line - Your environment choice, and the reference folder you pick, are stored in VS Code's workspace state, not in a committed
.vscode/settings.json - Runs
dbtthrough your own configured Python environment, in your own integrated terminal - Data preview queries your warehouse — it runs
dbt showthrough your own venv and your own profile, so rows travel between your warehouse and your machine exactly as they would if you randbt showyourself. The extension stores no credentials and opens no connection of its own, but a preview is not an offline operation: it costs a query against whichever target you are pointed at - No telemetry, no backend, no external service — everything happens on your machine
Non-goals
dbt Forge stays small on purpose. One question decides what goes in:
Does the feature need to know your dbt project?
If it has to read manifest.json, catalog.json or your dependency graph to be useful, it belongs here — nobody else can do it as well. If it works the same on any SQL file, it is somebody else's extension, and pulling it in would only make this one heavier at doing what it is actually for.
So these are deliberately out of scope, not "not yet":
| Not in scope | Use instead |
|---|---|
| Jinja / SQL syntax highlighting | Better Jinja — mature, and it covers .sql, .yml and .md. Note that resolving Jinja against your project — ref(), source(), doc(), macros — is very much in scope; it is the colouring that isn't |
| SQL formatting and linting | sqlfmt, SQLFluff, or your editor's own formatter |
| A warehouse browser or general SQL client | A warehouse-specific extension. Data preview here goes through dbt show and nothing else — dbt Forge opens no connection of its own |
| dbt Cloud, remote execution, AI assistance | Not planned in any form. Everything runs locally through your own venv, and nothing leaves your machine (see Local data & privacy) |
A request that falls on the wrong side of that line is not a bad idea — it is usually a good idea for a different extension. Where the underlying need does touch the project (say, resolving a doc() to the block that defines it, rather than colouring the {% docs %} tag), that is the version worth opening an issue for.
What's next
What has shipped, version by version, is in the CHANGELOG. What follows is planned in this order — an order, not a promise of dates. Every item passes the same test as the rest: it needs to know your dbt project.
- dbt resources it doesn't know yet. Done: model versions;
ref('package', 'model')andref('m', v=2)in alias detection; unit tests, semantic models, metrics and saved queries in the lineage; a warning on aref()to a private model from outside its group. - State-aware builds. Done: a reference manifest — a folder, or a copy of the project's own taken on
main—modified/new/impactedmarks in the lineage, and the two deferred builds, plus adbt lsselection from the larger lineage view (#4). - Column-level lineage. The largest item, and the one where being wrong costs the most, so it starts as a measured spike: how much of a real project's compiled SQL resolves with certainty. Same rule as completion — an edge is drawn when it is certain and left out when it is not, never approximated. Whether it ships follows from that number.
Not yet placed: renaming a model across its ref() call sites and .yml; a project-hygiene panel (models with no test, no description, no tested key); multi-project workspaces and cross-project refs.
Under the hood
| Layer | Stack |
|---|---|
| Extension Host | TypeScript + VS Code Extension API |
| Lineage Webview | React + React Flow + dagre (auto-layout), bundled locally — no CDN |
| Data Source | Reads manifest.json / catalog.json / run_results.json / target/compiled/*.sql directly, plus a reference manifest.json for state-aware builds, with a file watcher to stay in sync. profiles.yml is read (never written) to list the environments you can switch between |
| dbt Execution | Runs the dbt executable from your configured venv (Scripts//bin/) in the integrated terminal — except data preview, which spawns dbt show directly so it can read the rows back |
Contributing
The project is under active development.
- Fork → branch → PR
- Open an issue to discuss a feature before coding
- Follow the existing naming conventions
License
MIT © 2026 Evolve — Yohann
Built with ♥ by Evolve