Mermaid erDiagram Syntax: Complete Guide with Examples

Mermaid's erDiagram type is one of the fastest ways to turn a database schema into a clean, shareable diagram. This reference covers every part of the syntax — entity definitions, attribute types, relationship notation, cardinality, and full working examples you can paste directly into the editor.

Starting a Mermaid ER Diagram

Every Mermaid ER diagram starts with the erDiagram keyword on its own line:

erDiagram
    CUSTOMER {
        int id PK
        string name
    }

Indentation is optional but makes the schema easier to read. Entity names are conventionally written in UPPERCASE, though the parser accepts any case. The diagram renders automatically as you type — no manual layout required.

Entity Definitions and Attribute Syntax

Entities are defined with curly braces. Each attribute line follows the pattern: type attributeName [key]

erDiagram
    PRODUCT {
        int id PK
        string name
        float price
        int categoryId FK
        string sku
        bool isActive
        datetime createdAt
    }

Supported attribute types (any string works — these are display labels, not enforced types):

• int, bigint, smallint
• string, varchar, text, char
• float, decimal, numeric
• bool, boolean
• date, datetime, timestamp, time
• uuid, json, jsonb
• blob, bytea

Key constraints: PK (primary key), FK (foreign key), UK (unique key). These appear as badges on the attribute in the rendered diagram.

Relationship Syntax: Connecting Entities

Relationships are defined outside the entity blocks using this pattern:

ENTITY_A relationship ENTITY_B : "label"

The relationship label (in quotes) describes the verb: "places", "belongs to", "contains", "has", etc. The label is required — the parser rejects relationships without one.

Example relationships:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT }|--|{ CATEGORY : belongs-to

Sell Custom Apparel — We Handle Printing & Free Shipping

Cardinality Notation Reference

Mermaid erDiagram uses crow's foot notation. Each side of the relationship is defined by two characters:

Symbol	Meaning
|	Exactly one
o	Zero or one
{	Zero or many
}	One or many

The two characters at each end combine to form the cardinality. Common combinations:

Pattern	Meaning	Example
||--||	One and only one to one and only one	User has exactly one Profile
||--o{	One to zero or many	Customer places zero or many Orders
||--|{	One to one or many	Order contains one or many Line Items
}|--|{	One or many to one or many	many-to-many junction
o|--o{	Zero or one to zero or many	optional relationship

The double dash -- in the middle is the relationship line. It can also be written as .. for a dashed line (indicating non-identifying relationships).

Identifying vs Non-Identifying Relationships

Mermaid supports two line styles that carry semantic meaning:

• -- (solid line) — identifying relationship: the child entity's existence depends on the parent
• .. (dashed line) — non-identifying relationship: the child can exist independently

erDiagram
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER ||..o{ WISHLIST : "has"

In the first line, LINE_ITEM is an identifying relationship — a line item cannot exist without an order. In the second, WISHLIST is non-identifying — a customer can exist without any wishlists.

Many teams omit this distinction and use only solid lines for simplicity. The diagram renders correctly either way.

Full Schema Examples Ready to Copy

E-commerce schema:

erDiagram
    CUSTOMER {
        int id PK
        string name
        string email UK
        string phone
    }
    ADDRESS {
        int id PK
        int customerId FK
        string street
        string city
        string country
    }
    ORDER {
        int id PK
        int customerId FK
        int addressId FK
        date createdAt
        string status
    }
    LINE_ITEM {
        int id PK
        int orderId FK
        int productId FK
        int quantity
        decimal unitPrice
    }
    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }
    CUSTOMER ||--o{ ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    LINE_ITEM }o--|| PRODUCT : references

Blog / CMS schema:

erDiagram
    USER {
        int id PK
        string username UK
        string email UK
        string role
    }
    POST {
        int id PK
        int authorId FK
        string title
        text body
        string status
        datetime publishedAt
    }
    TAG {
        int id PK
        string name UK
    }
    COMMENT {
        int id PK
        int postId FK
        int userId FK
        text body
        datetime createdAt
    }
    POST_TAG {
        int postId FK
        int tagId FK
    }
    USER ||--o{ POST : writes
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes
    POST }|--|{ TAG : "tagged with"

Common Mermaid erDiagram Syntax Errors

These are the errors that trip people up most often:

• Missing relationship label — the label in quotes after the colon is required. CUSTOMER ||--o{ ORDER will fail; CUSTOMER ||--o{ ORDER : places works.
• Spaces in entity names — entity names cannot contain spaces. Use underscores or camelCase: LINE_ITEM not LINE ITEM.
• Wrong bracket direction — { means zero or many on the right side, } means one or many on the left. The bracket always opens toward the "many" side.
• Attribute block after relationship — define all entity blocks first, then define relationships. Mixing them can cause parse errors in some Mermaid versions.
• Missing erDiagram declaration — the first line must be exactly erDiagram with no leading spaces.

Frequently Asked Questions

What is Mermaid erDiagram syntax?

Mermaid erDiagram is a text-based syntax for creating entity-relationship diagrams. You describe entities, their attributes, and relationships between them as plain text, and Mermaid renders the result as a visual diagram with crow's foot notation. It is widely used in GitHub READMEs, documentation tools, and browser-based ERD makers.

Does Mermaid support crow's foot notation?

Yes. Mermaid erDiagram uses crow's foot notation for cardinality. The symbols ||, o|, |{, and o{ represent exactly-one, zero-or-one, one-or-many, and zero-or-many respectively. You combine them on each side of the relationship line to define cardinality precisely.

Can I use Mermaid ER diagrams in GitHub?

Yes. GitHub natively renders Mermaid diagrams in Markdown files. Wrap your erDiagram in a fenced code block with the language set to mermaid (three backticks followed by "mermaid") and GitHub will render the diagram automatically in READMEs, issues, and pull requests.