🗄️ Mermaid

Entity-relationship diagram

Design database schemas that make sense

Open this example in the editor Generate one with AI

What is a Entity-relationship diagram?

An ER diagram shows database entities, their attributes and the cardinality of relationships between them (one-to-many, many-to-many). It is the blueprint of every relational database.

ER diagrams belong in the pull request that adds a migration, and in the first hour of onboarding, where the fastest way to explain a product is often its data model. They make cardinality explicit: one address per customer or several is a business rule, not a detail. What they do not carry is physical design — no indexes, no partitioning, no query patterns. The migration file stays the source of truth.

Live example

Mermaid code

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_LINE : contains
    PRODUCT ||--o{ ORDER_LINE : "ordered in"
    CUSTOMER {
      string id PK
      string email UK
    }
    ORDER {
      string id PK
      date created_at
    }

Live example

When to use it

Design a new database schema before the first migration

Document an existing schema for new team members

Discuss data models with non-technical stakeholders

Common mistakes

Cardinality read from the wrong side

In CUSTOMER ||--o{ ORDER : places, the || next to CUSTOMER means one customer per order, and the o{ next to ORDER means zero or more orders per customer. Each marker counts its own entity, seen from the other end.

A relationship without a label

CUSTOMER ||--o{ ORDER on its own is a parse error: Mermaid expects a colon. Write : places, or : "" when the relationship is self-evident. This is by far the most common erDiagram failure.

Entity names containing spaces

ORDER LINE ||--o{ PRODUCT does not create an entity called ORDER LINE — the name is split at the space. Quote it as "ORDER LINE", or use the underscore convention the rest of the schema already follows.

Basic syntax

.mmd

erDiagram
    USER ||--o{ POST : writes
    USER {
      string id PK
      string email
    }

CUSTOMER ||--o{ ORDER : places
Every relationship needs a label after the colon; write : "" when there is nothing useful to say. Quote labels that contain spaces, as in : "ordered in".
ORDER { string id PK decimal total "in cents" }
Attributes are type then name, then optional key markers (PK, FK, UK, comma-separated) and a quoted comment. Types are free text and nothing is validated.
ORDER ||--|{ LINE : contains CUSTOMER }o..o{ PROMO : uses
A solid line is an identifying relationship — the child cannot exist alone. Dots mark a non-identifying one, where the foreign key is optional.
erDiagram direction LR
Direction defaults to top-down. direction LR spreads a wide schema sideways, which usually fits a documentation page better than a tall column of entities.

Questions about this diagram

How do I read cardinality symbols like ||--o{ ?

|| means exactly one, o| zero or one, }| one or more, }o zero or more. So CUSTOMER ||--o{ ORDER reads “one customer places zero or more orders”.

Can I generate an ER diagram from SQL?

Yes — paste your CREATE TABLE statements or describe your data and the AI produces the corresponding ER diagram with keys and relationships.

Can I keep an ER diagram in version control with my migrations?

Yes, and that is the main reason to write it as text. The diagram sits next to the migration, diffs line by line in review, and a schema change nobody reflected in it shows up as a missing edit.

Can a Mermaid ER diagram show indexes and constraints?

No. It shows entities, attribute types and PK, FK or UK markers, and nothing else: no indexes, defaults, check constraints or triggers. Treat it as a map of the schema, not a specification you could generate a database from.

How do I model a many-to-many relationship?

Either draw it directly with }o--o{, or model the junction entity explicitly: STUDENT ||--o{ ENROLMENT and COURSE ||--o{ ENROLMENT. Use the second form as soon as the join carries columns of its own, such as an enrolment date.

What is the difference between PK, FK and UK?

PK marks the primary key, FK a foreign key pointing at another entity, and UK a unique constraint. Mermaid renders them as labels only — it never checks that an FK matches a primary key elsewhere in the diagram.

Entity-relationship diagram or another diagram type?

ER diagram or class diagram?

Choose by what the reader is about to do. If they are writing SQL or a migration, give them entities, keys and cardinalities. If they are writing application code, a class diagram with methods and inheritance is closer to what they will actually type.

ER diagram or flowchart?

An ER diagram answers “what is stored and how does it relate”; a flowchart answers “what happens and in what order”. Boxes that are nouns with attributes belong in an ER diagram; boxes that are verbs belong in a flowchart.

Explore other diagram types

🔀 Flowchart 💬 Sequence diagram 🧩 Class diagram 🔄 State diagram 📅 Gantt chart 🥧 Pie chart 🧠 Mind map 🌿 Git graph 🕰️ Timeline 🚶 User journey 🎯 Quadrant chart

Create your Entity-relationship diagram now

Describe it in plain language — the AI writes the Mermaid code for you.

Open Mermaid Studio