# Entity relationship diagram

An ER diagram is the fastest way to explain a database to somebody who has not read it. Capable gives you three text routes to one, and the right choice depends on whether the diagram is documentation or a source of truth.

Mermaid is the easy default. DBML is better if the diagram will eventually generate a schema.

---

## When to reach for one

* Documenting a schema for people who will query it.
* Design reviews, where the relationships are the debate.
* Onboarding, where a picture beats reading migrations.

---

## How to draw it in Capable

| **Route** | **Use when**                                                   |
| --------- | -------------------------------------------------------------- |
| Mermaid   | Quick documentation of an existing schema.                     |
| DBML      | The diagram is the schema definition, with types and defaults. |
| ERD       | Classic ER notation from a compact text format.                |

---

## A worked example

An order schema with cardinality on every relationship:

![Entity relationship diagram](https://help.gocapable.com/images/att1418264592.svg)

The source, which you can paste into a new diagram and edit:

```
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : "appears in"
  CUSTOMER {
    uuid id PK
    string email UK
    string name
    timestamp created_at
  }
  ORDER {
    uuid id PK
    uuid customer_id FK
    string status
    numeric total
  }
  ORDER_ITEM {
    uuid id PK
    uuid order_id FK
    uuid product_id FK
    int quantity
  }
```

---

## A few things that catch people out

* Get cardinality right; it is the only part of the diagram that carries real information.
* Include the columns that matter, not every column. A 40-column table drawn in full is unreadable.
* Join tables deserve to be drawn. Hiding them behind a many-to-many line loses their extra columns.

---

## Related

[Crow's foot notationReading the little marks at the end of the line.](https://help.gocapable.com/diagrams/crow-s-foot-notation.html)

[Database schema diagramTypes, defaults and foreign keys, from text.](https://help.gocapable.com/diagrams/database-schema-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Get the cardinality right and the rest follows._