dddbml — DBML diagrams for VS Code, Git-friendly, DDD-aware

Interactive diagram for .dbml files, rendered beside the editor. The source of truth stays in your .dbml: you write it in the editor, and the diagram only applies small, minimal text edits when you ask for them (new table, new FK, delete). Table positions, group colors and edge shapes live in a sibling JSON file with deterministic formatting, so your team reviews the diagram in the same PR as the schema.

Built for:

• DDD projects — every TableGroup is a bounded context you can hide, collapse or color.
• Large schemas — viewport culling + level of detail keep pan/zoom smooth on thousands of tables.
• Git-based teams — sorted keys, integer coordinates, no view-state noise; conflicts on the layout file are resolved inside the diagram.

Install

code --install-extension dddbml-<version>.vsix

Open a .dbml file and run dddbml: Open Diagram (command palette or the editor-title icon).

Features

Canvas

• Tables, refs and groups parsed with the official @dbml/core in a background worker; tables with no saved position are arranged by bounded context.
• Pan with middle-click, Space + drag, or the hand tool. Zoom with the wheel, Ctrl+= / Ctrl+-, fit with Ctrl+1, reset with Ctrl+0.
• Drag tables, marquee-select on empty space, Shift to add to the selection, Esc to clear. Undo/redo with Ctrl+Z / Ctrl+Shift+Z.
• Two detail levels by zoom: full tables, or colored rectangles for a bird's-eye view (threshold configurable).
• Double-click a table header (or a column) to jump to its declaration in the .dbml; Ctrl+click anywhere in a Table block in the editor to focus it in the diagram.

Relationships

• Orthogonal edges that leave and enter at the FK/PK column rows, with crow's-foot / bar cardinality markers. Like dbdiagram, edges always leave from the left/right sides: a Z across a wide gap, an S when the tables are close, and a C around the right side once they overlap. Self-references draw as nested loops.
• Edit an edge by sliding a segment or dragging a ghost handle to add a notch; flip the port side by dragging an endpoint; recolor; "Reset line" to tidy.
• Auto-arrange (whole diagram or the selection) with an obstacle-avoiding edge router, cancelable with real progress.

Assisted editing (writes your .dbml with minimal edits; Ctrl+Z in the diagram undoes them)

• Right-click empty canvas → New table here: name it and it appears where you clicked (inside a group box it joins that TableGroup).
• Right-click a table → Add field opens the editor on a new line in that table.
• Drag the dot on a column's right edge onto another column to create a reference, then pick the cardinality.
• Delete a table, a field or a relation from its context menu, with a confirmation listing what else goes with it.
• Tip: enable VS Code Auto Save so the diagram and the file stay in sync.

DBML records and Dep

• Tables with sample records show a row-count badge; click it for a read-only grid of the values.
• Dep blocks (Dep: a -> b, Dep: a.col -> b.col) draw as dashed curved arrows, separate from FK refs. Select one to add, move (drag) or delete (double-click) bend points; toggle them in Diagram Views → Dependencies.

Bounded contexts (TableGroup)

• Dashed container per group; collapse to a single node with aggregated edges; hide a group or a single table.
• Per-group, per-table and per-edge colors from a palette, or any color via the eyedropper chip.
• Diagram Views panel: search, hide/show all, collapse/expand all, per-table visibility.

Git, from the canvas

• Commit, discard or stash the diagram files only (.dbml + layout); browse history read-only; overlay a diff vs HEAD with inline column changes.
• Layout-file merge conflicts are resolved in-diagram with ghost positions, never by hand-editing markers.

Export

• Schema → TypeORM entities (PostgreSQL dialect; more dialects pluggable). Export the whole schema or the selection.
• Diagram → PNG / SVG / clipboard, whole diagram, current view or selection. Prefer SVG for very large diagrams.

Settings — zoom step and limits, LOD threshold, UI density, snap-to-grid, layout spacing and export defaults, editable from the in-app Settings panel or VS Code settings (dddbml.*).

Layout file

For schema.dbml the extension writes schema.dbml.layout.json next to it:

{
  "version": 1,
  "tables": {
    "public.orders": { "x": 480, "y": 80 },
    "public.users": { "x": 120, "y": 80, "color": "#8b5cf6" }
  },
  "groups": {
    "billing": { "color": "#D0E8FF" }
  },
  "edges": {
    "public.orders::user_id|public.users::id": {
      "waypoints": [{ "x": 360, "y": 120 }]
    }
  }
}

Only shared design goes into this file. Your camera position and which groups you hid or collapsed are per-user view state, stored in VS Code's global storage, so pan/zoom never dirties the repo. The writer sorts keys, rounds coordinates to integers, omits defaults, uses LF + trailing newline and writes atomically. Moving three tables changes three lines.

Design vs data

Keep the .dbml about data (tables, columns, refs, records, Dep) and let the layout file carry design (positions, colors, bend points). A DBML headercolor is honored as a fallback, but it is never copied into the layout file: the moment you pick a table color in the diagram, the layout color wins and dddbml shows a one-time notice. Choosing colors in the UI keeps diagram tweaks out of your schema diffs and lets several people restyle the diagram without touching the source of truth.

Commands

Limitations

• The diagram reflects the last saved file; editing happens in the text editor.
• One .dbml per diagram — !include is not followed yet.
• Self-referencing refs render degenerately.

See specs/08-roadmap.md for what is planned.

Development

pnpm install
pnpm build            # extension (esbuild) + webview (vite)
pnpm test             # vitest
pnpm typecheck

Press F5 to launch an Extension Development Host, open a .dbml there (e.g. test/fixtures/huge.dbml, 5000 tables) and run the command. pnpm watch:extension / pnpm watch:webview rebuild on change.

• src/extension/ — VS Code host: parsing, layout file I/O, git, exporters, panel lifecycle.
• src/webview/ — Preact + Zustand renderer: culling, LOD, edges, drag, panels.
• src/shared/ — types crossing the postMessage boundary.
• specs/ — design documents (Spanish). If you change a pipeline, update its spec in the same PR.

Performance budgets and how to measure them: specs/07-performance-budgets.md.

License

MIT. See LICENSE.