Mermaid Database Schema Diagram: Visualize Your DB with Code

# Mermaid Database Schema Diagram: Visualize Your DB with Code

Documenting a database schema used to mean exporting a screenshot from a GUI tool or drawing boxes in Lucidchart. With Mermaid.js, you can write your schema diagram as plain text right alongside your code — version-controlled, diff-able, and always up to date.

This guide shows you how to build real database schema diagrams using Mermaid's erDiagram syntax, from simple two-table relationships to multi-table e-commerce schemas.

Why Use Mermaid for Database Diagrams?

• Lives in your repo — commit it with migration files so the diagram and schema stay in sync
• Renders natively on GitHub, GitLab, Notion, Obsidian, and Confluence
• No GUI required — write it in any text editor or the [MermaidEditor.lol online editor](https://mermaideditor.lol)
• Reviewable in PRs — teammates can comment on schema changes like any other code

Basic erDiagram Syntax

Mermaid uses the erDiagram keyword to define entity-relationship diagrams. Here's the minimal structure:

erDiagram
    USER {
        int id PK
        string email
        string name
        datetime created_at
    }

Each entity block lists columns with their type and optional key markers (PK, FK, UK).

Adding Relationships

Relationships use a crow's foot notation between entity names:

erDiagram
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"
    PRODUCT ||--o{ ORDER_ITEM : "included in"

    USER {
        int id PK
        string email
        string name
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
        datetime created_at
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }
    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

Relationship Cardinality Symbols

Read USER ||--o{ ORDER as: "one user places zero or more orders."

Real-World Example: Blog Platform Schema

Here's a schema diagram for a typical blog application:

erDiagram
    AUTHOR ||--o{ POST : "writes"
    POST ||--o{ COMMENT : "receives"
    POST }o--o{ TAG : "tagged with"
    POST ||--o| POST_META : "has"

    AUTHOR {
        int id PK
        string username UK
        string email UK
        string bio
        datetime created_at
    }
    POST {
        int id PK
        int author_id FK
        string title
        string slug UK
        text content
        string status
        datetime published_at
    }
    COMMENT {
        int id PK
        int post_id FK
        string author_name
        text body
        datetime created_at
    }
    TAG {
        int id PK
        string name UK
    }
    POST_META {
        int id PK
        int post_id FK
        string meta_title
        string meta_description
    }

This diagram captures the full shape of the database at a glance — tables, column types, primary/foreign keys, and how entities relate.

Many-to-Many Relationships

Mermaid handles many-to-many via a junction table, just like your actual database:

erDiagram
    STUDENT }o--o{ COURSE : "enrolls in"
    ENROLLMENT {
        int student_id FK
        int course_id FK
        date enrolled_on
        string grade
    }
    STUDENT ||--|{ ENROLLMENT : "has"
    COURSE ||--|{ ENROLLMENT : "has"

    STUDENT {
        int id PK
        string name
        string email UK
    }
    COURSE {
        int id PK
        string title
        int credits
    }

Tips for Clean Schema Diagrams

1. Use PK/FK/UK annotations — they make the diagram readable without needing to explain the schema in prose.

2. Keep it focused — large schemas (50+ tables) become unreadable. Split into bounded contexts: users-schema.md, orders-schema.md, etc.

3. Add relationship labels — the quoted string after the entities ("places", "contains") acts as documentation for the foreign-key intent.

4. Pair with migration files — keep the .md file in the same directory as your Alembic/Flyway/Prisma migration so reviewers see both together.

Editing Mermaid Diagrams Online

The fastest way to prototype a schema diagram is MermaidEditor.lol — paste your erDiagram block and get a live preview instantly. You can also export the finished diagram as PNG or SVG for architecture docs, Confluence pages, or README files.

Embedding in README

On GitHub and GitLab, paste the diagram in a fenced code block:

erDiagram

USER ||--o{ ORDER : "places"

...

It renders automatically — no plugin, no image upload required.

Conclusion

Mermaid's erDiagram syntax gives you a practical, code-first way to document database schemas. Start with your most critical tables, add relationships and key annotations, and commit the file next to your migration scripts. Your future self (and your teammates) will thank you every time they need to understand the data model without digging through raw SQL.

Try building your first schema diagram at MermaidEditor.lol — no sign-up needed.