🎨 mmerd - Mermaid ERD Generator

Automatically generate beautiful Entity Relationship Diagrams from your SQL files!

✨ Features

• 🚀 Instant ERD Generation - Run mmerd in any directory with SQL files
• 🔍 Smart Relationship Detection - Automatically finds foreign key relationships across multiple SQL files
• 📊 High-Resolution Output - Generates crisp, scalable diagrams (PNG and SVG)
• 🎯 Zero Configuration - Works out of the box with sensible defaults
• 📁 Multi-File Support - Perfect for projects that organize tables in separate SQL files
• 🎨 Mermaid Powered - Leverages Mermaid.js for beautiful, customizable diagrams

📸 Example Output

Running mmerd on a blog database with separate SQL files for users, posts, comments, and tags:

erDiagram
    users ||--o{ posts : "writes"
    users ||--o{ comments : "authors"
    posts ||--o{ comments : "has"
    posts ||--o{ post_tags : "tagged"
    tags ||--o{ post_tags : "applied"

Loading

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/mmerd.git
cd mmerd

# Run the installer
./install.sh

The installer will:

• ✅ Check for Node.js and npm (required prerequisites)
• ✅ Install mermaid-cli if not present
• ✅ Install mmerd and companion tools to ~/.local/bin
• ✅ Add ~/.local/bin to your PATH if needed

Basic Usage

# Navigate to a directory with SQL files
cd /path/to/your/database/schemas

# Generate ERD
mmerd

# Output:
# ✓ Created: database_erd.mermaid
# ✓ Created: database_erd.png
# 🖼️ Opens the diagram automatically!

🛠️ Available Commands

Command	Description	Usage
mmerd	Generate ERD from SQL files in current directory	mmerd
mmviz	Convert .mermaid file to high-res PNG	mmviz diagram.mermaid
mmsvg	Convert .mermaid file to scalable SVG	mmsvg diagram.mermaid
mmview	Quick view any image file	mmview output.png

📚 How It Works

1. Scans all .sql files in the current directory
2. Parses CREATE TABLE statements to extract table structure
3. Detects relationships through:
   • Inline REFERENCES clauses
   • FOREIGN KEY constraints
   • ALTER TABLE ADD FOREIGN KEY statements
4. Generates a Mermaid ERD with proper relationships
5. Renders to high-resolution PNG (4x scale for clarity)
6. Opens the diagram in your default image viewer

🎯 Use Cases

Perfect for:

• 📖 Documentation - Auto-generate database diagrams for your docs
• 👀 Code Reviews - Visualize schema changes in PRs
• 🎓 Learning - Understand database structures quickly
• 🏗️ Design - Validate relationships before implementation
• 🔍 Debugging - Spot missing or incorrect foreign keys

📁 Project Structure

mmerd/
├── bin/
│   ├── mmerd         # Main ERD generator
│   ├── mmviz         # Mermaid to PNG converter
│   └── mmsvg         # Mermaid to SVG converter
├── examples/
│   ├── users.sql     # Sample schema files
│   ├── posts.sql
│   ├── comments.sql
│   └── tags.sql
├── install.sh        # Installation script
├── uninstall.sh      # Uninstallation script
└── README.md         # You are here!

🔧 Prerequisites

• Node.js (v14 or higher)
• npm (comes with Node.js)

Don't have Node.js? Install it from:

• Ubuntu/Debian: sudo apt-get install nodejs npm
• macOS: brew install node
• Windows/Others: nodejs.org

📝 SQL File Requirements

mmerd works with standard SQL CREATE TABLE syntax:

-- Basic table
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL
);

-- Table with foreign key
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(200) NOT NULL,
    content TEXT
);

Supported:

• ✅ CREATE TABLE statements
• ✅ Inline REFERENCES clauses
• ✅ FOREIGN KEY constraints
• ✅ ALTER TABLE ADD FOREIGN KEY
• ✅ Multiple files with cross-file relationships

🎨 Customization

Output Location

By default, mmerd creates:

• database_erd.mermaid - Mermaid source file
• database_erd.png - Rendered diagram

Manual Rendering

You can edit the .mermaid file and re-render:

# Edit the mermaid file
nano database_erd.mermaid

# Re-render to PNG
mmviz database_erd.mermaid

# Or render to SVG for infinite scaling
mmsvg database_erd.mermaid

🗑️ Uninstallation

cd mmerd
./uninstall.sh

This will:

• Remove mmerd scripts from ~/.local/bin
• Optionally uninstall mermaid-cli
• Keep your Node.js installation intact

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit PRs

📄 License

MIT License - feel free to use in your projects!

🙏 Acknowledgments

• Mermaid.js - The amazing diagramming library
• mermaid-cli - Command-line interface for Mermaid

💡 Tips & Tricks

Generate ERD for Specific Tables

# Create a temporary directory
mkdir temp_erd
# Copy only the SQL files you want
cp users.sql posts.sql temp_erd/
cd temp_erd
mmerd

Version Control Your ERDs

# Add to your project
mmerd
git add database_erd.mermaid
git commit -m "Update database ERD"

CI/CD Integration

# GitHub Actions example
- name: Generate ERD
  run: |
    npm install -g @mermaid-js/mermaid-cli
    mmerd
    mkdir -p docs/diagrams
    mv database_erd.png docs/diagrams/

🐛 Troubleshooting

mmerd: command not found

• Run source ~/.bashrc (or source ~/.zshrc for zsh)
• Ensure ~/.local/bin is in your PATH

No SQL files found

• Ensure you're in a directory with .sql files
• Check file extensions are .sql (not .SQL or .sql.txt)

Diagram not opening automatically

• Linux: Install xdg-utils
• macOS: Should work automatically
• Windows: WSL may need additional configuration

---

Made with ❤️ for developers who love clean database documentation