erd-renderer

Generate beautiful, interactive Entity-Relationship (ER) diagrams from DBML, SQL DDL, and Live Databases — in VS Code and the CLI.

erd-renderer transforms DBML schemas, raw SQL DDL files (.sql), SQLite databases (.sqlite), and live database connections into clean, interactive, standalone SVG and PNG diagrams using deterministic layered layout, crow's foot notation, and domain clustering.

⚡ VS Code Extension

Install the extension directly from the VS Code Marketplace or search for erd-renderer in the Extensions tab (Cmd+Shift+X / Ctrl+Shift+X).

Key Features

• Live Side-by-Side Preview (Cmd+Shift+V / Ctrl+Shift+V): Open any .dbml or .sql file and press Cmd+Shift+V (or click the preview icon in the editor tab) to open an instant live ERD preview that auto-refreshes as you type.
• Interactive Pan, Zoom & Fit: Smooth drag-to-pan, mouse-wheel cursor-centered zooming, and 1:1 / viewport fit controls that preserve your zoom level across document edits.
• Table Search & Focus: Real-time search bar that filters tables and auto-centers the viewport on matching schemas.
• Relationship Highlighting: Click any table node to highlight its direct parent/child relationships and foreign key lines while dimming the rest of the diagram.
• "Connect to Database & Visualize": Connect directly to PostgreSQL, MySQL, MSSQL, SQLite, or Oracle databases via Cmd+Shift+P → ERD: Connect to Database & Visualize.
• One-Click Export: Export crystal-clear SVGs, 2x high-resolution PNGs, or copy images directly to your clipboard.

🚀 Core Features

• Multi-Source Schema Ingestion: Render diagrams directly from DBML (.dbml), SQL DDL (.sql), SQLite database files (.sqlite, .db), or live database connections.
• Granular Table Filtering & Focus: Visualize only the tables you care about with --tables, glob wildcards (sales.*), --exclude-tables, or a --tables-file list.
• Smart Relationship Graph Depth (--depth <N>): Automatically expand from seed tables to include 1-hop or N-hop connected foreign key parents and children.
• Reverse-Engineer to DBML (pull / introspect): Extract clean, portable .dbml schemas from SQL DDL scripts, SQLite files, or live database connections.
• Sugiyama Hierarchical Layout: Deterministic layered layout engine optimized for relational schemas with multi-parent relationships and cycles.
• Crow's Foot Notation: Supports one-to-one, one-to-many, many-to-one, and many-to-many cardinality with unoccluded markers.
• TableGroup Domain Clustering: Groups related tables into domain containers (e.g. Identity, Catalog, Orders).
• Visible Foreign Key Badges: Displays foreign key column names clearly on connection arrows without clipping or occlusion.
• Self-Contained SVG: 100% offline, zero external font or stylesheet dependencies.
• High-Res PNG Export: Built-in retina/high-DPI PNG generation via sharp.
• Zero Config CLI & TypeScript API: Use directly via npx or import into your Node.js application.

Quick Start

Render any schema file directly without installing:

# From DBML schema
npx erd-renderer schema.dbml

# From SQL DDL dump file
npx erd-renderer schema.sql

# From local SQLite database
npx erd-renderer ./database.sqlite

Installation

Global CLI

npm install -g erd-renderer

In a Project

npm install -D erd-renderer

Database Drivers (Optional Peer Dependencies)

Install the respective driver when connecting to live database instances:

npm install -D pg          # For PostgreSQL (Neon, Supabase, RDS, local)
npm install -D mysql2      # For MySQL & MariaDB (PlanetScale, Aurora, local)
npm install -D mssql       # For Microsoft SQL Server (Azure SQL, RDS, local)
npm install -D oracledb    # For Oracle Database (Oracle Cloud, local)

CLI Usage & Subcommands

1. render Subcommand — Generate Visual Diagrams

The render command parses DBML, SQL DDL, SQLite files, or live database connection strings and generates visual SVG or PNG diagrams:

# Render from DBML
erd-renderer render schema.dbml
erd-renderer schema.dbml # (implicit render)

# Render directly from Live PostgreSQL Database (with schema TableGroups)
erd-renderer render "postgresql://postgres:postgres@localhost:5432/testdb" -o postgres-erd.svg

# Render directly from Live MySQL Database
erd-renderer render "mysql://root:root@localhost:3306/testdb" -o mysql-erd.svg

# Render directly from Live Microsoft SQL Server (MSSQL)
erd-renderer render "mssql://sa:Password123!@localhost:1433/testdb?encrypt=false" -o mssql-erd.svg

# Render directly from Live Oracle Database
erd-renderer render "oracle://testdb:Password123!@localhost:1521/FREEPDB1" -o oracle-erd.svg

# Render directly from SQL DDL (Postgres default)
erd-renderer render schema.sql -o schema-erd.svg

# Render SQL DDL with explicit database dialect
erd-renderer render mysql_schema.sql --db mysql -o mysql-erd.svg
erd-renderer render mssql_schema.sql --db mssql -o mssql-erd.svg

# Render directly from SQLite database
erd-renderer render ./chinook.sqlite -o chinook.png --format png

# Specify custom output path
erd-renderer render schema.dbml -o docs/diagram.svg

# Render both SVG and high-res PNG (2x retina)
erd-renderer render schema.dbml -f both --scale 2

2. pull Subcommand — Reverse-Engineer to DBML

Extract clean, formatted DBML from live database connections, SQL DDL scripts, or SQLite files:

# Extract full live PostgreSQL database to DBML
erd-renderer pull "postgresql://postgres:postgres@localhost:5432/testdb" -o postgres.dbml

# Extract full live MySQL database to DBML
erd-renderer pull "mysql://root:root@localhost:3306/testdb" -o mysql.dbml

# Extract full live Microsoft SQL Server database to DBML
erd-renderer pull "mssql://sa:Password123!@localhost:1433/testdb?encrypt=false" -o mssql.dbml

# Extract full live Oracle database to DBML
erd-renderer pull "oracle://testdb:Password123!@localhost:1521/FREEPDB1" -o oracle.dbml

# Extract full SQLite schema to a DBML file
erd-renderer pull ./chinook.sqlite -o chinook.dbml

# Extract SQL DDL script to clean DBML with explicit dialect
erd-renderer pull ./mysql_schema.sql --db mysql -o schema.dbml
erd-renderer pull ./schema.sql --db postgres -o schema.dbml

# Extract only a focused subset of tables from a live DB
erd-renderer pull "postgresql://postgres:postgres@localhost:5432/testdb" --tables "orders" --depth 1 -o orders.dbml

# Print DBML output directly to stdout
erd-renderer pull ./chinook.sqlite

3. Granular Table Filtering & Large Schema Subsets

When working with large databases (100–1000+ tables), you can extract and render focused sub-diagrams:

A. Inline Table List (-t, --tables) & Wildcard Globs

# Explicit table list
erd-renderer render schema.dbml -t "users, orders, order_items, payments" -o checkout.svg

# Wildcard glob matching (e.g. all sales tables and CRM tables)
erd-renderer render schema.dbml -t "sales.*, crm_*" -o sales-domain.svg

# Exclude temporary, backup, or audit tables
erd-renderer render schema.dbml --exclude-tables "tmp_*, backup_*, *_audit, *_log"

B. Table List File (--tables-file / -t @file.txt)

For medium-to-large selections (20–100 tables), store table names in a plaintext file (one table per line, # comments supported):

erd-renderer render schema.dbml --tables-file ./domains/billing.txt -o billing.svg
# Or using the @file shorthand
erd-renderer render schema.dbml -t @billing.txt -o billing.svg

Example billing.txt:

# Core customer & payment tables
users
payment_methods
invoices
invoice_items

# Subscriptions
subscriptions
plans

C. Smart Relationship Depth (--depth <N>)

Automatically expand the diagram to include foreign key parents and children:

# Include 'orders' plus all directly connected tables (1 hop away)
erd-renderer render schema.dbml --tables "orders" --depth 1 -o orders-subgraph.svg

# Include 'orders' plus tables within 2 relationship hops
erd-renderer render schema.dbml --tables "orders" --depth 2 -o orders-extended.svg

4. Layout Directions & Simultaneous DBML Export

# Layout directions: LR (default), TB (Top-to-Bottom), RL, BT
erd-renderer render schema.dbml --direction TB

# Render visual diagram AND emit intermediate DBML simultaneously
erd-renderer render ./chinook.sqlite --emit-dbml chinook.dbml -o chinook.svg

CLI Options Reference

Programmatic API

You can import erd-renderer as a TypeScript / JavaScript module:

import {
  parseDbml,
  parseSqlDdl,
  introspectSqlite,
  filterSchema,
  emitDbml,
  renderErDiagram,
} from 'erd-renderer';
import { readFileSync, writeFileSync } from 'node:fs';

// 1. Ingest from DBML, SQL DDL, or SQLite
const rawSql = readFileSync('schema.sql', 'utf-8');
const fullSchema = parseSqlDdl(rawSql);

// 2. Filter to a focused domain (e.g. 'orders' + 1 hop depth)
const focusedSchema = filterSchema(fullSchema, {
  tables: ['orders'],
  depth: 1,
});

// 3. Render SVG and PNG
const result = await renderErDiagram(focusedSchema, {
  format: ['svg', 'png'],
  layout: { direction: 'LR', seed: 1 },
  style: { theme: 'default', scale: 2 },
});

// 4. Save visual diagram
writeFileSync('orders-domain.svg', result.svg);
if (result.png) {
  writeFileSync('orders-domain.png', result.png);
}

// 5. Or export back to clean DBML
const dbml = emitDbml(focusedSchema);
writeFileSync('orders-domain.dbml', dbml);

CI / GitHub Actions Integration

Automatically generate and update ER diagrams on every schema push:

name: Generate ER Diagram

on:
  push:
    paths:
      - 'schema.dbml'
      - 'schema.sql'

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Generate Diagrams
        run: npx erd-renderer render schema.sql --format both -o docs/schema

      - name: Commit Diagram Updates
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add docs/schema.svg docs/schema.png
          git diff --quiet && git diff --staged --quiet || git commit -m "docs(erd): update schema diagram"
          git push

🔒 Security & Privacy First

Connecting to live databases requires absolute trust. erd-renderer is designed from the ground up for safe use with production and enterprise databases:

• 🛡️ 100% Local & Offline: Zero telemetry, zero external tracking, and zero cloud dependencies. Schema introspection and diagram rendering run entirely on your local machine.
• 🔑 Encrypted OS Keyring Storage: Passwords and connection strings in the VS Code extension are encrypted using the official SecretStorage API (backed by Apple Keychain, Windows Credential Manager, or Linux Secret Service). Passwords are never saved in plain text.
• 👓 Strictly Read-Only Introspection: The tool only inspects catalog metadata (tables, columns, indexes, foreign keys). It enforces read-only session transactions and never queries, modifies, or accesses table row data.
• 🧱 Sandboxed Webview with Strict CSP: Previews run in a sandboxed Webview enforcing a strict Content Security Policy (CSP) with cryptographic nonces and complete XML entity escaping.
• 🚫 Redacted Error Logs: Connection errors and diagnostic logs automatically sanitize and mask passwords before displaying notifications.

Author & Connect

Created and maintained by Shubham Shakya.

• GitHub: @shubham23471
• LinkedIn: Shubham Shakya
• X (Twitter): @shubham__shakya

Feel free to open an issue or pull request on GitHub if you have any questions or feature suggestions!

License

MIT © 2026 Shubham Shakya