ER diagram

erDiagram
  CUSTOMER["Customer"] {
    string id PK "Account"
    string email UK
  }
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  PRODUCT ||..o{ LINE-ITEM : "appears in"

timeline:
  enter ORDER slide-top, enter CUSTOMER:ORDER fade
  enter LINE-ITEM slide-right, enter ORDER:LINE-ITEM fade
  enter PRODUCT slide-bottom, enter PRODUCT:LINE-ITEM fade, highlight LINE-ITEM glow

Only erDiagram; there is no erDiagram-v2.

Entities

  • Writing a name declares an entity. Names may contain letters, digits, _, -, ., * and non-ASCII characters, as in LINE-ITEM or CAFÉ.
  • Quote a name that contains spaces: "Customer Account". A % inside a quoted name or alias (A["50% off"]) is an error, as Mermaid refuses it; spell it out instead.
  • Alias: CUSTOMER["Customer"] or CUSTOMER[Client] changes only the name drawn; the id is still CUSTOMER. When one entity has several aliases, the first one wins.
  • An entity mentioned many times is merged into one, and so are its attributes.
  • One line can hold several statements: A B C declares three entities.
  • The reserved words end, subgraph, class, style and classDef cannot be used as entity names.

Attributes

erDiagram
  ORDER {
    int id PK
    string customer_id FK "The customer who placed it"
    list~string~ tags
    string `shipping address`
  }
  • Each attribute is written as type name [keys] ["comment"].
  • Keys can be PK, FK and UK; several are separated by commas with no spaces (PK,FK) and must come before the comment.
  • Generics are written as list~string~.
  • Wrap a name with special characters in backticks.
  • A block can be written on one line: E { string a }.

Relationships

The syntax is left <cardinality><line><cardinality> right : label, and the label is required.

Cardinality Symbol Word form
Exactly one || one, only one, 1
Zero or one |o, o| zero or one, one or zero
Zero or more }o, o{ zero or more, zero or many, many, many(0), 0+
One or more }|, |{ one or more, one or many, many(1), 1+
Line Syntax
Solid (identifying) -- or to
Dashed (non-identifying) .., .-, -. or optionally to
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER |o..|{ ITEM : contains
  PRODUCT one to zero or many ITEM : "appears in"
  • Either side can take any cardinality; what is written on the left is drawn on the left.
  • The label is one word, or a quoted string. : two words becomes the label two plus an entity called words, as in Mermaid.
  • The label is drawn on the line, on a background the theme’s --siren-edge-label-fill paints, and wraps by itself once it is wider than about 171px (a row holds as much as Mermaid’s, which draws it larger); <br> breaks a row. An entity name, an alias and an attribute’s comment never wrap.

Subgraph

erDiagram
  subgraph sales ["Sales"]
    CUSTOMER ||--o{ ORDER : places
  end
  ORDER ||--|{ ITEM : contains
  • subgraph name, subgraph name["title"] or subgraph name [title], closed by end.
  • Subgraphs can be nested, and each level can have its own direction. It is given up as soon as a relationship whose two ends have different parents passes through the subgraph: one entity inside it (at any depth) and one outside, or two of its own entities at different nesting depths. Such a relationship voids every subgraph from each end up to and including the two ends’ nearest common one, and each is then laid out in the direction of the nearest enclosing subgraph that keeps its own, or else the diagram’s, as in Mermaid 12. A subgraph that names no direction is laid out the same way, in its enclosing subgraph’s direction.
  • Sibling subgraphs are placed last-written first, and every subgraph before the entities outside them, as in Mermaid: subgraph SA, subgraph SB, then X reads SB, SA, X from left to right.
  • For a relationship written inside a subgraph, the entities at both ends are placed in that subgraph.
  • A subgraph name cannot be the same as an entity name.

Direction

direction TB, BT, LR, RL; if written more than once, the last one wins. TD is not accepted: Mermaid reads direction TD as two entities, and so does Siren.

Styles

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER:::urgent
  style CUSTOMER fill:#dbeafe,stroke:#2563eb
  classDef urgent fill:#fee2e2,stroke:#dc2626
  • style A,B property:value,...
  • classDef a,b property:value,...: several names can be defined at once.
  • class A,B name1,name2
  • A:::name, which can also follow an alias: A["x"]:::name.
  • A style beats a class applied to the same entity whichever line comes first, as in Mermaid. Applying a class no classDef defines is a warning: the entity is drawn unstyled.
  • Relationships cannot be styled.
  • A subgraph’s frame is filled with the theme’s --siren-subgraph-fill, none by default; see Themes.
  • A timeline highlight always wins over an author’s stroke: while an entity is highlighted, outline and glow draw its border in the highlight color, and give the author’s back afterwards.

A value in an ER style or classDef is read in the characters Mermaid reads it in, so it is stricter than a flowchart’s:

  • Only letters, digits, non-ASCII characters, spaces, -, _, *, #, : and ,. Write a color as a hex code or a name (fill:#f96, fill:red) and a size as a whole number (stroke-width:2). A function (rgb(…)), a decimal (1.5px), !important, a quote, $, % or / is an error.
  • No space inside a value: Mermaid glues the words together, so stroke-dasharray:5 5 would paint 55, and Siren refuses it. A space beside a : or a , is fine.
  • A ; only at the very end of the line (fill:red;); anything after it is an error. An empty declaration (fill:red,, style A ;), a second : in one declaration (fill:red:blue) and a , right before the declarations (style A ,fill:red) are errors too, each saying what to write instead.

Accessibility

accTitle: title, accDescr: description and the braced accDescr { ... } block, in any case and with whitespace before the colon allowed; the last one wins. accTitle { has no block form, so it reads as an entity called accTitle, as in Mermaid.

Comments

Only a whole line is a comment. Inside a relationship’s quoted label, an attribute’s quoted comment, a backticked name or a generic, a %% is text; anywhere else on a line it is an error that tells you to move the comment to a line of its own, and a line of only %% is refused too.

Timeline targets

Element id Example
Entity The entity name (not the alias) CUSTOMER (CUSTOMER["Customer"])
Relationship left:right, separated by a colon, with #2 for a repeat CUSTOMER:ORDER
subgraph subgraph:N, numbered in the order opened; the name cannot be used subgraph:1
  • Relationships use a colon rather than - because entity names can themselves contain - (ORDER:LINE-ITEM).
  • An entity whose name has spaces ("Customer Account") cannot be named in a timeline, because a target cannot contain spaces. Give an entity you want to animate a name without spaces, and show it through an alias.
  • Attributes cannot be targeted on their own.

Not yet supported

Syntax Current behavior
The u cardinality (A u--o{ B : x) Error. Mermaid cannot draw its symbol either
classDef default Error
style / class on a subgraph after its end Error
style on a relationship (style A:B ...) Error
Cardinality words such as one, to or many as entity names (CUSTOMER one ORDER) No error, but drawn as three entities; Mermaid reports an error
Names starting with a digit (123abc) No error, but drawn as one entity; Mermaid draws two