Mermaid ER Diagram Tutorial (Database Modeling)

An entity-relationship diagram, or ER diagram, models the structure of a database: the entities (tables), the attributes (columns) they hold, and the relationships between them, including how many of one relate to how many of another. It is the standard way to design and document a relational database before and after it exists. Mermaid's ER syntax lets you write these diagrams in text, so a schema diagram can live in the repo next to the migrations that create it and stay in sync through code review.

This tutorial walks through defining entities with typed attributes, marking primary and foreign keys, and - the heart of ER diagrams - expressing relationships with the correct cardinality using crow's foot notation. Every concept comes with a short snippet you can render live in the editor at /diagram-tools/mermaid-editor. ER diagrams reward getting the cardinality syntax right, so we will spend real time on it.

Defining entities and attributes

An ER diagram begins with `erDiagram`. You define an entity and its attributes with a block: the entity name followed by braces containing attribute lines. Each attribute line is a type and a name, like `string name` or `int age`. A minimal entity might be `CUSTOMER` with a block containing `string name`, `string email`, and `int id`. Mermaid renders this as a table-like box listing the entity's attributes with their types.

Entity names are conventionally uppercase in ER diagrams, matching database table-naming habits. You can define an entity with no attributes at all - just its name - if you only want to show relationships at first and add detail later. This makes it easy to sketch the overall structure of a database as a set of related entities, then flesh out each one's columns as the design firms up.

Keys and attribute detail

Attributes can be marked as keys, which is essential for a meaningful database diagram. After the type and name on an attribute line, you add a key marker: `PK` for primary key and `FK` for foreign key. So `int id PK` marks id as the primary key, and `int customer_id FK` marks a foreign key that references another entity. Mermaid displays these markers next to the attributes, making the key structure of each table immediately visible.

You can also add a comment to an attribute by placing quoted text after it, and combine markers - an attribute can be both a primary and foreign key in a junction table, written `int id PK, FK`. These details let a Mermaid ER diagram capture the real key structure that drives relationships and joins. Getting keys right matters because the foreign keys are what the relationships between entities represent, so the keys and the relationship lines should tell a consistent story.

Relationships and cardinality

Relationships are the defining feature of ER diagrams, and Mermaid uses crow's foot notation to express cardinality - the number of instances on each side. The syntax puts cardinality symbols on each end of a relationship line. A relationship reads like `CUSTOMER ||--o{ ORDER : places`, which means a customer places zero or more orders, and every order belongs to exactly one customer. Here are the symbols.

• `||` - exactly one (a single vertical bar means one, the double bar reinforces "exactly").
• `o|` - zero or one (the circle means zero is allowed).
• `}|` - one or more (the crow's foot means many, with the bar requiring at least one).
• `}o` - zero or more (crow's foot plus circle: many, and zero is allowed).
• A solid line means an identifying relationship; a dashed line means a non-identifying one.
• The label after the colon names the relationship, like "places" or "contains".
• Read each end toward the other entity: `CUSTOMER ||--o{ ORDER` is "one customer to zero-or-more orders".

Putting it together

A complete small ER diagram combines these pieces. You might declare `CUSTOMER`, `ORDER`, and `LINE_ITEM` entities each with their attributes and keys, then draw relationships: `CUSTOMER ||--o{ ORDER : places` and `ORDER ||--|{ LINE_ITEM : contains`. Read together, these say a customer places many orders, and each order contains one or more line items - a recognizable e-commerce schema captured in a handful of readable lines. The relationships mirror the foreign keys, so the diagram documents both the tables and how they join.

Because it is text, this diagram versions cleanly and can sit right beside your schema definition, updated in the same pull request when the schema changes. That co-location is the whole point of diagram-as-code for database design - the diagram cannot drift out of sync if updating it is part of the same change that alters the schema. When you want to arrange a large ER diagram precisely for documentation, or present it polished, you can import the Mermaid into Atlas Diagram Studio and lay it out visually on the canvas at /diagrams while keeping the source in the Mermaid editor at /diagram-tools/mermaid-editor.