DBML Outline
A Visual Studio Code extension that adds a DBML Elements explorer and native Outline support for .dbml files.
The DBML semantic model is parsed with the official @dbml/core package using the dbmlv2 parser. A small source locator is used only to map parsed elements back to file/line positions for navigation.
Features
DBML Elements
The Explorer view follows the same general information architecture as the DBML Playground Elements view:
DBML Elements
├─ Tables (2)
│ ├─ users 4 cols
│ │ ├─ id int PK
│ │ ├─ username varchar NN
│ │ ├─ email varchar U
│ │ ├─ created_at timestamp
│ │ └─ Indexes (2)
│ │ ├─ idx_users_email email UNIQUE
│ │ └─ (created_at, id) BTREE
│ └─ posts 5 cols
├─ Refs (1)
├─ Deps (0)
├─ Enums (1)
├─ TableGroups (0)
├─ TablePartials (0)
├─ Records (0)
├─ DiagramViews (0)
└─ Externals (0)
Clicking a navigable item opens the source declaration.
Native VS Code Outline
The normal VS Code Outline and Ctrl+Shift+O document-symbol navigation mirror the Elements-style top-level groups:
Tables 2
├─ users
│ ├─ id
│ ├─ username
│ ├─ email
│ ├─ created_at
│ └─ Indexes 2
│ ├─ idx_users_email
│ └─ (created_at, id)
└─ posts
Refs 1
Deps 0
Enums 1
TableGroups 0
TablePartials 0
Records 0
DiagramViews 0
Externals 0
The first level is always ordered as Tables, Refs, Deps, Enums, TableGroups, TablePartials, Records, DiagramViews, and Externals. Child symbols come from the parsed/declaration content of the current DBML file. dbmlOutline.showEmptyGroups controls whether empty root groups are shown.
DBML v2 / multi-file projects
By default the extension uses Parser.setDbmlSource() and Parser.parseDbmlProject() for workspace files. This is the official @dbml/core editor-oriented multi-file API.
The extension registers workspace .dbml files with the parser and keeps open/edited documents synchronized, so DBML module-system imports can be resolved.
Diagnostics
Parser errors from @dbml/core are surfaced as VS Code diagnostics where a line/column can be determined. The Elements tree falls back to the lightweight source index while the document is temporarily invalid during editing.
Requirements
- VS Code
1.95.0 or newer
- Node.js
22+ for packaging/publishing with the current @vscode/vsce
The extension runtime itself is hosted by VS Code.
Install for development
npm install
Open this folder in VS Code and press F5 to launch an Extension Development Host.
Open any .dbml file and check:
- Explorer → DBML Elements
- Explorer → Outline
Ctrl+Shift+O
Build a VSIX
Before packaging, change this in package.json:
"publisher": "your-publisher-id"
to your actual Visual Studio Marketplace publisher ID.
Then:
npm install
npm run lint
npm run package
This creates a file similar to:
dbml-outline-0.1.3.vsix
Install it locally with:
code --install-extension dbml-outline-0.1.3.vsix
Publish to Visual Studio Marketplace
- Create a Visual Studio Marketplace publisher.
- Put that publisher ID in
package.json.
- Authenticate
vsce with the publisher.
- Publish:
npx vsce login <publisher-id>
npm run publish
You can also provide VSCE_PAT in the environment instead of storing credentials locally.
Configuration
dbmlOutline.multifile
Default: true
Use the @dbml/core stateful multi-file parser for workspace DBML projects.
dbmlOutline.maxProjectFiles
Default: 1000
Maximum number of DBML files registered during a workspace scan.
dbmlOutline.showEmptyGroups
Default: true
Show groups such as Refs (0) and Enums (0).
dbmlOutline.debounceMs
Default: 180
Delay before refreshing the Elements tree after edits.
Architecture
@dbml/core
│
dbmlv2
│
▼
Database model
│
normalize semantic model
│
┌────────────┴─────────────┐
▼ ▼
DBML Elements VS Code Outline
TreeDataProvider DocumentSymbolProvider
▲ ▲
└──── source locator ──────┘
(navigation only)
The source locator does not decide DBML semantics. It only records declaration positions so Tree items and Outline symbols can jump to source lines. @dbml/core remains the semantic parser.
Supported Elements
- Tables
- Fields
- Indexes
- Refs
- Enums / enum values
- TableGroups
- TablePartials
- Records
- DiagramViews (when exposed by the installed
@dbml/core model; source fallback also detects declarations)
- Externals (same behavior as above)
- Direct module dependencies (
use ... from ...) in the active file
Notes on compatibility
@dbml/core is the source of truth for semantic parsing. Its public parser API is stable, but internal Database model shapes can evolve. The normalizer deliberately accepts both common camelCase/snake_case model properties and falls back to source-declared elements if a collection is not exposed by a particular version.
License
MIT. @dbml/core is distributed under Apache-2.0; see THIRD_PARTY_NOTICES.md.
