schemagraph

v1.4.4

Published

2 months ago

Zero-dependency pure Node.js CLI & library to parse schemas across any framework (Laravel, Django, Rails, Go, Spring JPA, Prisma, Mongoose, Sequelize, TypeORM, GraphQL, SQL) and generate responsive SVG ERDs, interactive HTML viewers, Mermaid markdown, DBM

⚡ schemagraph

⚡ Quick Start (Instant Run)

Run schemagraph directly in any project folder with npx — zero installation or setup needed:

npx schemagraph

[!TIP] 🚀 Zero Setup & Auto-Open: Automatically scans and parses your project's schemas, generates database-design.html + database-design.svg, and launches the interactive visual explorer in your default browser. (Pass --no-open to suppress in CI/CD).

📦 Installation Options

Choose how you prefer to run schemagraph:

# ⚡ Option 1: Instant Run with npx (Recommended — Zero install)
npx schemagraph

# 🌐 Option 2: Global CLI Install (Run `schemagraph` anywhere)
npm install -g schemagraph
schemagraph

# 🛠️ Option 3: Project Dev Dependency (For npm scripts & team workflows)
npm install --save-dev schemagraph

🎯 Individual Format Commands (Export On-Demand)

By default, schemagraph generates HTML + SVG. You can easily export to any specific format using --format:

# 🌐 1. Interactive HTML Explorer & SVG Diagram (Default)
npx schemagraph

# 📊 2. DBML Schema (Ready for dbdiagram.io & dbdocs.io)
npx schemagraph --format=dbml

# 🐬 3. Standard SQL DDL (Normalized CREATE TABLE & FOREIGN KEYs)
npx schemagraph --format=sql

# 🧜‍♂️ 4. Mermaid Markdown (For GitHub/GitLab READMEs)
npx schemagraph --format=md

# 🤖 5. Token-Optimized AI Prompt Context (For ChatGPT, Gemini, Claude, Cursor)
npx schemagraph --format=ai

# 📋 6. Machine-Readable JSON AST (For custom tooling & pipelines)
npx schemagraph --format=json

# 🕸 7. Graphviz DOT Digraph (For Graphviz / D3)
npx schemagraph --format=dot

# 📦 8. Export Multiple Formats to a Custom Directory
npx schemagraph ./backend --format=dbml,sql,ai,md --output=./docs

# 🚀 9. Export ALL Formats Simultaneously (Headless / CI Mode)
npx schemagraph ./ --format=all --output=./docs --no-open

🌟 Why schemagraph?

🚫 Zero External Dependencies: Built strictly using pure Node.js standard library (fs, path, crypto, events, os). Under 40 KB install footprint. Zero supply-chain security risks.
⚡ Instant Performance: Scans and parses 50+ models and generates all diagrams in under 50 milliseconds.
🎯 Universal Multi-Framework Auto-Discovery: Automatically detects and parses:
- 🐘 PHP / Laravel: Migration files (database/migrations/*.php with Schema::create, Blueprint, foreignId(), constrained()) and Eloquent models (belongsTo, hasMany).
- 🐍 Python / Django & SQLAlchemy: Django models (models.Model, ForeignKey) and SQLAlchemy (Base, Column, ForeignKey).
- 💎 Ruby on Rails: Schema (db/schema.rb, db/migrate/*.rb), create_table, add_foreign_key, and ActiveRecord models (belongs_to, has_many).
- 🐹 Go / GORM: Structs with gorm:"primaryKey", gorm:"foreignKey", and relationship fields.
- ☕ Java & Kotlin (Spring Boot): JPA / Hibernate @Entity, @Table, @Id, @Column, @ManyToOne, @JoinColumn.
- ⚡ Node.js & TypeScript: Prisma (.prisma), Mongoose, Sequelize, TypeORM, GraphQL SDL (.graphql), TypeScript interfaces (interface User), Zod (z.object).
- 🗄️ Relational SQL DDL: .sql files with CREATE TABLE, PRIMARY KEY, FOREIGN KEY ... REFERENCES for PostgreSQL, MySQL, SQLite, MariaDB.
🎨 7 Output Formats:
1. Responsive XML SVG: Modern dark & light developer themes (Catppuccin Mocha, Tokyo Dark, Slate Light), table cards, [PK] and [FK] badges, cubic bezier curves.
2. Interactive Single-Page HTML Explorer: Standalone web app with draggable cards, smooth camera transitions, multi-color wire distinction, connection inspector, minimap, and in-browser exports.
3. DBML (.dbml): Standard Database Markup Language compatible with dbdiagram.io and dbdocs.io.
4. Normalized SQL DDL (.sql): Clean, standard SQL CREATE TABLE and constraint statements.
5. Mermaid Markdown (.md): GitHub/GitLab native erDiagram block + formatted data dictionary tables ready for README.md.
6. JSON Schema Map (.json): Machine-readable AST for CI/CD pipelines, documentation generators, or scripts.
7. Graphviz DOT (.dot): Compatible with Graphviz graph engines (dot, neato, d3-graphviz).

📊 Live GitHub Mermaid ERD Demo

This diagram is rendered natively on GitHub using the Mermaid export produced by schemagraph:

erDiagram
    products ||--o{ categories : "category_id -> id"
    orders ||--o{ users : "user_id -> id"
    order_items ||--o{ orders : "order_id -> id"
    order_items ||--o{ products : "product_id -> id"
    reviews ||--o{ users : "user_id -> id"
    reviews ||--o{ products : "product_id -> id"

    users {
        SERIAL id PK
        VARCHAR_100_ name
        VARCHAR_255_ email
        VARCHAR_255_ password_hash
        VARCHAR_500_ avatar_url
        VARCHAR_20_ role
        TIMESTAMP created_at
    }
    categories {
        SERIAL id PK
        VARCHAR_100_ name
        VARCHAR_120_ slug
        TEXT description
    }
    products {
        SERIAL id PK
        INT category_id FK
        VARCHAR_200_ name
        VARCHAR_220_ slug
        DECIMAL_10__2_ price
        INT stock
        BOOLEAN is_active
        TIMESTAMP created_at
    }
    orders {
        SERIAL id PK
        INT user_id FK
        VARCHAR_50_ order_number
        DECIMAL_10__2_ total_amount
        VARCHAR_50_ status
        VARCHAR_50_ payment_status
        TEXT shipping_address
        TIMESTAMP created_at
    }
    order_items {
        SERIAL id PK
        INT order_id FK
        INT product_id FK
        INT quantity
        DECIMAL_10__2_ unit_price
    }
    reviews {
        SERIAL id PK
        INT user_id FK
        INT product_id FK
        INT rating
        TEXT comment
        TIMESTAMP created_at
    }

🌐 Interactive HTML Viewer Features

When you export with --format=html (or all), schemagraph produces a standalone, self-contained single-page web app with zero CDN dependencies (100% offline).

Key Features:

🚀 Zero-Blur Pure Vector Engine: Crisp, sharp text and cards at any zoom level from 2% eagle-eye to 1000% ultra-close inspection.
🎯 Smooth Animated Camera Navigation (easeOutCubic): Clicking 🎯 Focus Link or Center Table smoothly glides and zooms the camera to frame connected tables at the exact center of your screen.
🌈 Multi-Color Wire Distinction: Relationship connectors use an 11-color deterministic palette so overlapping foreign keys are instantly distinguishable.
💡 Single-Wire Persistent Spotlight: Clicking a relation locks in a 5.5px neon glow spotlight while dimming unrelated tables and edges.
🖱️ Real-Time Draggable Table Cards: Reposition any table node freely; cubic Bézier connectors dynamically recalculate at 60fps.
🔍 Docked Connection Inspector: Click any table or press [ to see all outgoing foreign keys and incoming referenced-by tables with cardinality badges.
🗂️ Compact Mode for Large Schemas: Shrinks table cards to PK/FK keys only for high-density 50+ table architectures.
🗺️ Interactive Minimap Radar: Eagle-eye minimap with click-to-jump radar view.
⬇ 1-Click Multi-Format Export Dropdown: Download SVG, PNG, DBML, SQL, Mermaid Markdown, JSON, and DOT directly from the browser header.

💻 CLI Options Reference

schemagraph [targetDir] [options]

🤖 AI & LLM Integration (ChatGPT, Gemini, Claude, Cursor)

schemagraph is designed from the ground up for modern AI coding agents and LLMs:

llms.txt & llms-full.txt Native Support: Follows the llms.txt standard for automated package discovery and tool ingestion by LLMs.
Instant AI Database Prompt: Run npx schemagraph --format=ai to produce a token-efficient architecture context file (database-schema-ai-prompt.md) ready to paste directly into ChatGPT, Gemini, Claude, or Cursor to ask complex questions about your database design, generate backend APIs, or plan SQL optimizations!
1-Click Copy in Browser: Click 🤖 Copy AI Schema Prompt inside the interactive HTML viewer to copy your complete database prompt directly to your clipboard.

📦 Programmatic Node.js API

Use schemagraph directly in your Node.js scripts, migration hooks, or build pipelines:

const {
    parseProject,
    generateSVG,
    generateHTML,
    generateMarkdown,
    generateJSON,
    generateDBML,
    generateDOT,
    generateSQL,
    generateAIContext
} = require('schemagraph');

// 1. Scan and parse workspace schema models
const schemaMap = parseProject('./backend');

// 2. Generate Interactive HTML Viewer
const html = generateHTML(schemaMap, {
    title: 'Database Explorer'
});

// 3. Generate SVG string
const svg = generateSVG(schemaMap, {
    theme: 'catppuccin', // 'catppuccin' | 'dark' | 'light'
    title: 'Application Architecture'
});

// 4. Generate DBML (for dbdiagram.io)
const dbml = generateDBML(schemaMap);

// 5. Generate Standard SQL DDL
const sql = generateSQL(schemaMap);

// 6. Generate Token-Optimized AI Context Prompt
const aiPrompt = generateAIContext(schemaMap);

// 7. Generate Mermaid Markdown
const markdown = generateMarkdown(schemaMap);

// 8. Generate JSON AST
const jsonAst = generateJSON(schemaMap);

🎨 Built-in Themes

🤖 Continuous Integration & Automation Recipes

Auto-generate ERD on Git Commit (Husky)

Add to your package.json scripts to keep docs in sync with your migrations automatically:

{
  "scripts": {
    "docs:db": "schemagraph ./backend --format=all --output=./docs --no-open"
  }
}

GitHub Actions Workflow

Automatically regenerate and commit updated diagrams when schema files change:

name: Generate Database ERD
on:
  push:
    paths:
      - 'database/migrations/**'
      - 'prisma/**'
      - 'models/**'
      - 'migrations/**'

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx schemagraph ./ --format=all --output=./docs --no-open
      - name: Commit updated ERD
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/
          git commit -m "docs(db): update database architecture diagrams [skip ci]" || exit 0
          git push

🥊 Comparison with Other Tools

❓ Frequently Asked Questions (FAQ)

Simply navigate to your Prisma project root and run:

npx schemagraph

schemagraph has zero external dependencies and directly parses .prisma files without needing Graphviz C++ libraries or Python runtimes.

Yes! Run npx schemagraph ./database/migrations. schemagraph natively parses Schema::create, Blueprint, foreignId(), and constrained() methods to map the entire relational architecture automatically.

Run:

npx schemagraph --format=dbml

This generates database-design.dbml which you can paste directly into dbdiagram.io.