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

#A worked example

An order schema with cardinality on every relationship:

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

Get the cardinality right and the rest follows.