An entity-relationship diagram communicates data structure and cardinality. It can support schema design and onboarding, but it is not a replacement for executable migrations. Treat the diagram as an explanation of important constraints and keep the database definition as the source of truth.
Model entities and attributes
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
CUSTOMER {
uuid id PK
string email UK
datetime created_at
}
ORDER {
uuid id PK
uuid customer_id FK
string status
}
ORDER_ITEM {
uuid order_id FK
uuid product_id FK
int quantity
}
PRODUCT {
uuid id PK
string name
decimal price
}Attribute types in an ER diagram are descriptive. Match the vocabulary used by your team, but do not assume the diagram enforces database-specific precision, indexes, defaults, or check constraints.
Read cardinality from both ends
The relationship CUSTOMER ||--o{ ORDER says each order belongs to exactly one customer, while a customer can have zero or many orders. Reading both ends prevents an ambiguous statement such as “customers have orders” from hiding optionality.
Use a relationship label such as places or contains that reads naturally with the entity names. Labels are documentation, not foreign-key names.
Show the right amount of schema
A complete production database may contain audit columns, technical indexes, integration fields, and join tables that overwhelm an overview. Create a domain-level ER diagram with the keys and attributes needed to understand the relationship, then link to migrations or generated schema documentation for full detail.
For a schema-change pull request, update the diagram only when the conceptual model changes. A new nullable telemetry column may not belong in the overview; a new ownership relationship probably does.
Verify assumptions against the database
Check that optionality, uniqueness, and relationship direction match actual constraints. A line that says “exactly one” while the foreign key is nullable creates misleading documentation. When reverse-engineering an old schema, mark uncertain relationships in prose rather than presenting guesses as enforced rules.
Use the ER template in the Mermaid editor to validate syntax and export a scalable SVG for your architecture documentation.