DB Diagram

A self-hosted database diagram editor. Write DBML on the left, see the ER diagram on the right.

DB Diagram is an Electron desktop app for designing and documenting database schemas with a text DSL. You write DBML in a syntax-highlighted editor, and the diagram updates in real time — table nodes, column lists, constraint badges, and relationship edges drawn with crow's foot notation. No account, no subscription, no network connection required.

Why this exists

I wanted a schema diagramming tool that runs on my machine and doesn't require logging in anywhere. Everything I found was either a SaaS product that needed a subscription or an open-source project that hadn't been touched in years. So I built one.

Features

Editor. The left pane uses CodeMirror 6 with a custom Lezer grammar for DBML syntax highlighting. Parse errors appear as inline markers with underlines and a message tooltip — you see what's wrong without leaving the editor. The editor also handles SQL in the import pane: paste CREATE TABLE statements and they convert to DBML, with warnings if the SQL uses features DBML doesn't represent. Export to PostgreSQL or MySQL DDL works from the same panel, using ALTER TABLE for foreign key constraints so referential integrity is preserved.

Diagram. Each table renders as a node with its column names, data types, and constraint badges (PK, FK, NOT NULL, UNIQUE). Relationships draw as orthogonal edges using crow's foot notation with optionality markers. Dagre handles the initial auto-layout; after that, nodes are draggable and their positions persist. You can group tables together — groups move as a unit and resize when their contents change. Table headers support a color palette for visual organization. Columns and tables can carry notes, shown as hover tooltips. Edge segments are draggable so you can route lines around crowded areas. The canvas supports pan, zoom, multi-select with shift-click, and drag-to-select.

Desktop app. Native file dialogs replace the browser File System Access API for opening and saving .dbml files. The title bar shows the current filename and marks unsaved changes. The app menu (File / Edit / Help) has the keyboard shortcuts you'd expect: Cmd/Ctrl+S, Cmd/Ctrl+O, and so on. Recent files appear in the File menu and in the OS dock or Jump List. Drag a .dbml file onto the window and it opens. Close with unsaved changes and you get a confirmation dialog. Window size and position restore on next launch. Everything works offline.

MCP server. Run the app with --mcp and it starts a headless MCP server over stdio. This lets AI assistants in editors like Cursor or Windsurf create and edit schemas directly. There are 10 tools: get and set the full schema, plus granular operations for creating tables, adding and removing columns, defining relationships, and renaming things. The practical upshot is that you can describe a schema to your AI assistant and have it build the diagram for you, then open the file in DB Diagram to review and adjust it.

Getting Started

Prerequisites: Node.js 18+ and npm.

1. Clone the repo:

   git clone https://github.com/lorranmcm/dbml-diagram.git && cd dbml-diagram

2. Install dependencies:

   npm install

3. Run in development mode:

   npm run dev

This opens the Electron app with hot reload. Edit DBML in the left pane and the diagram updates on the right.

To build a distributable installer:

npm run build
npm run dist

The packaged app appears in the release/ directory.

For browser-only mode without Electron: npm run dev:web

MCP Server

Running the app with --mcp starts a headless MCP server over stdio, letting AI assistants read and modify schemas programmatically. It works with any MCP-compatible client — Claude Desktop, Cursor, Windsurf, or anything that implements the MCP protocol.

Dev mode

node out/main/index.js --mcp

Run npm run build first so out/ exists.

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "db-diagram": {
      "command": "node",
      "args": ["/absolute/path/to/dbml-diagram/out/main/index.js", "--mcp"]
    }
  }
}

Replace /absolute/path/to/ with the actual path to your clone. On Windows, use forward slashes or escaped backslashes.

Other MCP clients (Cursor, Windsurf) use similar config files — check their documentation for the config file location.

Tools

Tool	Description
get_schema	Returns the current DBML schema text
set_schema	Replaces the full schema (validates DBML syntax)
create_table	Adds a new table to the schema
add_column	Adds a column to an existing table
list_tables	Returns a JSON summary of all tables and columns
delete_table	Removes a table and its references
delete_column	Removes a column and its references
add_relationship	Adds a foreign key relationship between tables
rename_table	Renames a table and updates references
rename_column	Renames a column and updates references

Tech Stack

Library	Version	Purpose
React	19	UI framework
Electron	41	Desktop shell
CodeMirror 6	via @uiw/react-codemirror 4	Code editor with custom DBML grammar
@dbml/core	6.5	DBML parser and SQL exporter
React Flow	12	Diagram canvas with pan/zoom/nodes/edges
Dagre	3	Directed graph auto-layout
Dexie	4	IndexedDB wrapper for persistent storage
TanStack Store	0.9	Client state management
MCP SDK	1.29	Model Context Protocol server
TypeScript	5.9	Type safety
Vite	8	Build tool and dev server

Docker Deployment

The VPS deployment target is the web build, not the Electron runtime.

Build and run locally with Docker Compose:

docker compose up --build

The app publishes port 80 by default. Override it if needed:

APP_PORT=8080 docker compose up --build

VPS Deployment

Server prerequisites:

• Docker Engine
• Docker Compose plugin
• An SSH user that can run Docker commands

The deployment workflow assumes the app lives at /opt/db-diagram on the VPS unless you override it through GitHub secrets.

GitHub Actions Deployment

The workflow in .github/workflows/deploy.yml runs on pushes to master and on manual dispatch. It:

1. Installs dependencies with npm ci --legacy-peer-deps
2. Runs npx vitest run src/lib/file-io/group-metadata.test.ts
3. Builds the production web bundle with npm run build:web
4. Builds the Docker image
5. Syncs the repository to the VPS over SSH
6. Runs docker compose up -d --build --remove-orphans remotely

Repository secrets required for deployment:

• VPS_USER
• VPS_SSH_KEY
• VPS_PORT optional, defaults to 22
• VPS_APP_DIR optional, defaults to /opt/db-diagram
• VPS_APP_PORT optional, defaults to 80

The current deploy target host is 31.97.19.229.