Mermaid ER Diagram: Syntax, Keys and Examples (2026)

November 11, 2026 · 12 min read

Mermaid ER Diagram Syntax: Entities, Keys and Relationships

A Mermaid ER diagram is a fenced mermaid code block that starts with erDiagram and lists entities joined by lines such as CUSTOMER ||--o{ ORDER : places. GitHub, GitLab and many Markdown editors turn that text into a crow's foot diagram. Below, you'll build one bookshop schema step by step, then see which newer syntax your renderer may reject.

What a Mermaid ER Diagram Looks Like in Markdown

You write the diagram inside a code fence tagged mermaid. The first line inside the fence is the keyword erDiagram, and every line after it is an entity or a relationship. If fences are new to you, our guide to Markdown code blocks covers the backtick and tilde forms.

Here's the smallest useful version of a bookshop schema, followed by the diagram it produces:

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_LINE : contains
    BOOK ||--o{ ORDER_LINE : "appears in"
```

You get four boxes joined by three labelled lines. The symbols at each line end show how many rows can sit on that side. Mermaid uses crow's foot notation, so a three-pronged fork means "many".

Each relationship line has the same shape: first entity, marker, second entity, a colon, then a label. The label is required and reads from the first entity's point of view. A line holding only a name, such as PUBLISHER, draws a standalone box.

For flowcharts, sequence diagrams and the other types, see Mermaid diagrams in Markdown. This post stays on erDiagram.

Mermaid Relationship Markers and Their Word Aliases

Every marker is two characters. The outer character, the one touching the entity box, sets the maximum. The inner character sets the minimum. A pipe means one, o means zero, and a brace means many. The markers on the right side of -- are mirror images of the left-side ones.

Left sideRight sideMeaning
|oo|Zero or one
||||Exactly one
}oo{Zero or more
}||{One or more

So ORDER ||--|{ ORDER_LINE says an order has one or more lines, and each line belongs to exactly one order.

If symbols are hard to read in a pull request, Mermaid also accepts words. only one and 1 mean exactly one. zero or one and one or zero mean zero or one. zero or more, zero or many, many(0) and 0+ mean zero or more. one or more, one or many, many(1) and 1+ mean one or more. In place of -- and .., you write to and optionally to:

```mermaid
erDiagram
    CUSTOMER only one optionally to zero or more ORDER : places
```

That line produces the same diagram as CUSTOMER ||..o{ ORDER : places. We prefer the symbols, because they keep each line short enough to scan in a code review.

How Do You Write a One-to-Many Relationship in Mermaid?

Put exactly one (||) on the parent side and zero or more (o{) on the child side. The line CUSTOMER ||--o{ ORDER : places reads as "a customer places zero or more orders, and each order belongs to exactly one customer". Swap o{ for |{ when the child side can't be empty.

Read BOOK ||--o{ ORDER_LINE : "appears in" the same way. A book appears in zero or more order lines, and each line points at exactly one book. The zero matters here: a new title that nobody has bought yet is still a valid BOOK row, so |{ would be wrong.

The other common shapes use the same pieces:

```mermaid
erDiagram
    CUSTOMER ||--|| LOYALTY_CARD : holds
    CUSTOMER ||--o| GIFT_PREFERENCE : sets
    BOOK }o..o{ ORDER : "is bought in"
```

The first line is one-to-one: every customer holds exactly one card. The second is optional one-to-one, since a customer may set one gift preference or none. The third is many-to-many, which Mermaid draws without complaint.

A many-to-many line can't hold data such as the quantity of each book in an order, though. In a real database you resolve it through a join entity, which is exactly what ORDER_LINE does in the bookshop schema. Our ER diagram guide walks through that design step.

Solid and Dashed Lines: Identifying vs Non-Identifying

The two characters in the middle of a relationship control the line style. Two hyphens (--) draw a solid line for an identifying relationship. Two dots (..) draw a dashed line for a non-identifying one.

Use the solid line when the child can't exist, or can't be identified, without the parent. ORDER_LINE fits: its primary key is the pair of order ID and book ID, so it depends on both. An ORDER has its own ID, so its link to CUSTOMER is non-identifying:

```mermaid
erDiagram
    CUSTOMER ||..o{ ORDER : places
    ORDER ||--|{ ORDER_LINE : contains
    BOOK ||--o{ ORDER_LINE : "appears in"
    PUBLISHER ||..o{ BOOK : publishes
```

The result shows dashed lines from CUSTOMER and PUBLISHER and solid lines into ORDER_LINE. Many diagrams use -- everywhere, and that's fine for a quick sketch. The dashed form only earns its place when readers care how keys are built.

Attributes, Primary Keys and Foreign Keys in erDiagram

Add columns by following an entity name with a block in braces. Each line inside holds a type, a name, an optional key and an optional comment. Keys are PK, FK or UK (unique), and you combine them with a comma, as in PK, FK. Starting a name with an asterisk, as in int *id, also marks a primary key. A comment goes last, in double quotes.

```mermaid
---
title: Bookshop
---
erDiagram
    CUSTOMER ||..o{ ORDER : places
    ORDER ||--|{ ORDER_LINE : contains
    BOOK ||--o{ ORDER_LINE : "appears in"
    PUBLISHER ||..o{ BOOK : publishes
    CUSTOMER {
        int id PK
        string email UK
        string name
    }
    ORDER {
        int id PK
        int customer_id FK
        date placed_on
    }
    ORDER_LINE {
        int order_id PK, FK
        int book_id PK, FK
        int quantity "at least 1"
    }
    BOOK {
        int id PK
        int publisher_id FK
        string(13) isbn UK "no hyphens"
        decimal price
    }
```

Each box now lists its columns in rows, with a key column and a comment column. The front matter between the --- lines adds a title above the diagram.

Mermaid has no fixed list of data types. A type must start with a letter and may contain digits, hyphens, underscores, parentheses and square brackets, so string(13) and string[] both work.

A comma isn't on that list. In our test, decimal(6,2) broke the whole diagram in Mermaid 11, though Mermaid 12.3 accepted it. For a diagram that renders on any host, write decimal and put the precision in a comment.

Should foreign keys appear at all? Include them in a model of real tables, because readers look for customer_id when they write a join. In a logical model, the relationship line already says it.

We prefer listing only the keys and the few columns that explain a relationship. An ER diagram in a README isn't your DDL, and a 20-row box pushes everything else off the screen. When you do need the DDL, our ER diagram SQL guide maps each table and key both ways.

Try the schema below. Change a marker such as o{ to |{ and the preview redraws the line ends:

Bookshop schema

erDiagram
CUSTOMER ||..o{ ORDER : places
ORDER ||--|{ ORDER_LINE : contains
BOOK ||--o{ ORDER_LINE : listed
PUBLISHER ||..o{ BOOK : publishes
CUSTOMER {
int id PK
string email UK
}
ORDER {
int id PK
int customer_id FK
date placed_on
}
ORDER_LINE {
int order_id PK, FK
int book_id PK, FK
int quantity
}
BOOK {
int id PK
int publisher_id FK
string isbn UK
}

Each box lists its columns and keys.

78 words427 characters30 lines
Markdown

When Do Entity Names and Labels Need Double Quotes?

Quote anything with a space in it. Entity names can use Unicode characters, and a name with a space, such as "Gift Card", needs double quotes. Labels follow the same rule, so "appears in" works and appears in doesn't.

The unquoted label is the nasty one, because it often fails silently. In our tests with Mermaid 11 and 12, BOOK ||--o{ ORDER_LINE : appears in produced no error. The label read "appears", and a stray box named "in" appeared on the canvas.

An alias lets you keep a short ID in the code and show a friendlier name in the box. Declare it with square brackets, then use the short ID everywhere else:

```mermaid
erDiagram
    c[Customer]
    oh["Order History"]
    c ||--o{ oh : keeps
    %% Lines starting with two percent signs are comments
```

The boxes read Customer and Order History, and the %% comment line is ignored. In the Mermaid 11 and 12 builds we tested, an alias written inside a relationship line caused a parse error, so declare aliases first.

A few more mistakes show up as "Parse error on line N":

  • A relationship with no colon or no label. If you really want no text, use an empty label: "".
  • A double quote inside a comment. Comments can't contain double quotes, even escaped ones.
  • Markdown in a key, such as **PK**. Keys accept only PK, FK and UK.

Styling and Laying Out an ER Diagram: direction, style and classDef

Set the flow with a direction line: TB (top to bottom), BT, LR or RL. Colour one entity with style, or define a reusable class with classDef and attach it with class or the ::: shorthand. A class named default applies to every entity that has no class of its own.

```mermaid
erDiagram
    direction LR
    CUSTOMER:::core ||..o{ ORDER:::core : places
    ORDER ||--|{ ORDER_LINE : contains
    style ORDER_LINE fill:#fde68a,stroke:#b45309
    classDef core fill:#dbeafe,stroke:#1d4ed8
```

The diagram now runs left to right. CUSTOMER and ORDER get blue fills, and ORDER_LINE turns amber.

Check your renderer's version before relying on this. The style, classDef and direction statements reached erDiagram in Mermaid 11.5.0. Older renderers stop with a syntax error, which is why older forum answers say ER diagrams can't be styled.

For screen readers, add an accTitle: line and an accDescr: line after erDiagram:

```mermaid
erDiagram
    accTitle: Bookshop schema
    accDescr: Customers place orders, and each order holds one or more order lines
    CUSTOMER ||..o{ ORDER : places
    ORDER ||--|{ ORDER_LINE : contains
```

Nothing visible changes, but Mermaid writes both into the SVG for assistive technology.

For a diagram-only workspace with templates, themes and PNG or SVG export, open the Mermaid editor. Our guide to exporting Mermaid to PNG compares it with the command-line and VS Code routes.

Which Mermaid Version Do Nullable Types and Subgraphs Need?

Three recent releases changed erDiagram, according to the Mermaid ER documentation and the release notes:

FeatureSyntaxAdded in
Nullable or optional typestring? middle_name11.16.0 (June 2026)
Subgraphs to group entitiessubgraph Sales ... end11.17.0 (August 2026)
ELK layout, new default theme and lookautomatic12.0.0 (September 2026)

Here's the limitation: an older renderer doesn't understand these. In our test with a Mermaid 11 build from before 11.16.0, string? stopped the diagram with a parse error. A subgraph was worse, because it rendered without an error and drew boxes named "subgraph", "Sales" and "end". Our editor's preview loads a Mermaid release from before these additions, so it behaves the same way.

The fallbacks work everywhere: write string middle_name "nullable" instead of string?, and split a large schema into one diagram per group instead of using subgraphs. If you're on 12.x and want the old look back, add layout: dagre, theme: default and look: classic under config: in the diagram's front matter. If you load Mermaid on your own site, our Mermaid JS guide sets the same three options in initialize().

Hosts bundle their own Mermaid build. GitHub's diagram docs suggest this block to see which version it runs:

```mermaid
info
```

Paste it into an issue preview and GitHub prints its Mermaid version instead of a diagram. GitLab's Markdown docs say it supports Mermaid version 12 as of November 2026. For the rest of GitHub's syntax, see our GitHub Markdown cheat sheet.

Mermaid ER Diagram Questions

A Mermaid ER diagram stays useful because it lives next to the code it describes and changes in the same commit. Stick to markers, keys, quoted labels and aliases, and it renders on almost any host. Treat nullable types and subgraphs as extras until your renderer catches up. Paste the bookshop example into the editor to see it drawn live, then adapt it to your own tables.