Mermaid ER Syntax

Last updated: March 2026

Mermaid ER diagrams are a plain-text format for describing entity-relationship schemas. Diagram2Code parses Mermaid erDiagram blocks and converts them to production-ready SQL DDL or ORM model code. This page covers the input syntax accepted by the parser — for output details see SQL DDL Generation and ORM Generation.

Table & Column Syntax

Each entity block defines one database table. The block opens with the table name in UPPER_SNAKE_CASE (converted to lower_snake_case in SQL output), followed by a brace-enclosed list of column definitions.

erDiagram
    TABLE_NAME {
        type column_name MARKERS "optional comment"
    }

Each column line contains up to four parts in order:

Relationships

Relationships are declared outside entity blocks, one per line. They define the foreign key targets that the generator uses to emit REFERENCES clauses and ORM association annotations.

LEFT_TABLE CARDINALITY "--" CARDINALITY RIGHT_TABLE : "label"

The cardinality tokens use Mermaid's crow's-foot notation. Each side of the -- separator is two characters: the first describes optionality, the second describes multiplicity.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER }|--|{ PRODUCT : contains
    USER ||--|| PROFILE : has

CUSTOMER ||--o{ ORDER : places means one Customer places zero-or-more Orders. The generator emits a foreign key from ORDER.customer_id back to CUSTOMER. The relationship label (places) is used for documentation only and does not affect the SQL output.

A many-to-many relationship (}|--|{) causes Diagram2Code to generate a junction table automatically. The junction table is named by joining the two table names in alphabetical order (e.g. order_product) and contains foreign key columns to each parent table.

Common Patterns

One-to-many with explicit FK column

erDiagram
    AUTHOR {
        int id PK
        string name
        string email UK
    }
    POST {
        int id PK
        int author_id FK
        string title
        text body
        timestamp published_at
    }
    AUTHOR ||--o{ POST : writes

Many-to-many via junction table

Declare the relationship directly — Diagram2Code generates the junction table automatically. You do not need to define it as a separate entity.

erDiagram
    STUDENT {
        int id PK
        string name
        string email UK
    }
    COURSE {
        int id PK
        string title
        string code UK
    }
    STUDENT }|--|{ COURSE : enrolls

Self-referencing table

A table can reference itself, which is common for hierarchical data such as categories or org charts.

erDiagram
    CATEGORY {
        int id PK
        string name
        int parent_id FK "NULL for root categories"
    }
    CATEGORY ||--o{ CATEGORY : contains

Full-featured Example

erDiagram
    CATEGORY {
        int id PK
        string name UK "Category name"
        int parent_id FK
    }
    PRODUCT {
        int id PK "Primary key"
        string name "Product name"
        decimal price
        boolean active
        string sku UK "Stock keeping unit"
        int category_id FK
        timestamp created_at
    }
    CUSTOMER {
        int id PK
        string email UK
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int customer_id FK
        decimal total
        timestamp placed_at
    }
    CATEGORY ||--o{ CATEGORY : contains
    CATEGORY ||--o{ PRODUCT : groups
    CUSTOMER ||--o{ ORDER : places
    ORDER }|--|{ PRODUCT : includes

Known Limitations

• Must start with erDiagram — The keyword must appear exactly as written (case-sensitive) at the beginning of the diagram. Leading blank lines are allowed, but other Mermaid diagram types or content before erDiagram cause a parse error.
• No spaces in column names — Column identifiers must be valid snake_case tokens. first_name is valid; first name is not.
• Comments must be on their own line — Mermaid %% comments cannot appear on the same line as a column definition or relationship.
• No native enum columns — Mermaid has no enum syntax. Use a string or varchar(N) column and add a ::CHECK directive in a comment to generate a CHECK constraint in the SQL output.
• FK columns need a matching relationship line — Marking a column as FK does not automatically infer the target table. You must also add the corresponding relationship line; otherwise the generator cannot emit a valid REFERENCES clause.