PlantUML ER Diagram: Entities, Keys, and Relationships

A PlantUML ER diagram can document database entities and cardinality as text. For a practical schema-oriented view, PlantUML's Information Engineering (IE) notation is usually the most direct option: define entities, list attributes, and connect them with crow's-foot relationships. PlantUML also supports Chen notation, while class diagram syntax offers a third option for domain-oriented models.

This tutorial builds an order database with customers, orders, products, and order lines. Browse the PlantUML examples guide if you first need to compare diagram types.

Key Takeaways

• PlantUML supports both Information Engineering and Chen ER notations; they are distinct modeling styles.
• IE syntax extends class diagram syntax with entity declarations, mandatory-attribute markers, and crow's-foot endpoints.
• PlantUML's * attribute marker means mandatory, not primary key.
• Key and foreign-key labels are conventions you define; the renderer does not validate DDL or referential integrity.
• Use an ERD for storage structure and a class diagram for object-oriented design decisions.

Prerequisites and Notation Choice

You need a PlantUML renderer that supports IE diagrams. The syntax below follows the official Information Engineering diagram documentation, retrieved July 24, 2026.

PlantUML offers two ER-related approaches:

• IE notation uses entity boxes and crow's-foot cardinalities. It works well for implementation-oriented schema discussions.
• Chen notation represents entities, relationships, and attributes as separate shapes. It works well for conceptual data modeling.

The official Chen EER documentation uses a different syntax. Do not copy a relationship line from one notation into the other and assume it has the same meaning.

Step 1: Define an Entity

Use entity followed by a name and a body. In IE syntax, entity is an alias for class, so much of the class diagram formatting model still applies.

@startuml
entity Customer {
  * customer_id : UUID <<PK>>
  --
  * email : VARCHAR(255)
  display_name : VARCHAR(120)
  * created_at : TIMESTAMP
}
@enduml

The leading * marks an attribute as mandatory in IE notation. <<PK>> is a label chosen by the author to communicate primary-key intent; PlantUML does not infer or enforce it. The -- separator creates a visual division in the entity body.

Step 2: Add Primary and Foreign Key Conventions

Use one documented convention across the project. Stereotype-like labels such as <<PK>>, <<FK>>, and <<UK>> are readable, but they remain diagram annotations.

@startuml
entity Customer {
  * customer_id : UUID <<PK>>
  --
  * email : VARCHAR(255) <<UK>>
}

entity Order {
  * order_id : UUID <<PK>>
  --
  * customer_id : UUID <<FK>>
  * status : VARCHAR(30)
  * placed_at : TIMESTAMP
}
@enduml

The diagram can render even if customer_id has the wrong type or points nowhere. Review the actual migration or DDL separately. An ERD is documentation, not a schema validator.

Step 3: Read Crow's-Foot Cardinality

IE relationships combine an endpoint on each side. The official notation includes:

You can reverse endpoints to express the relationship in either direction. Always add a verb label so readers understand the business meaning as well as the count.

@startuml
entity Customer
entity Order

Customer ||--o{ Order : places
@enduml

This says every order belongs to exactly one customer, while a customer may place zero or many orders. Cardinality does not automatically describe deletion behavior, cascading, uniqueness, or whether an association is temporarily invalid during a transaction.

Step 4: Model a Many-to-Many Relationship

Relational schemas normally resolve a many-to-many relationship with an associative entity. In an ordering system, OrderLine connects orders and products while carrying quantity and price-at-purchase.

@startuml
entity Order {
  * order_id : UUID <<PK>>
}

entity Product {
  * product_id : UUID <<PK>>
  --
  * sku : VARCHAR(40) <<UK>>
  * current_price : DECIMAL
}

entity OrderLine {
  * order_id : UUID <<PK, FK>>
  * line_number : INTEGER <<PK>>
  --
  * product_id : UUID <<FK>>
  * quantity : INTEGER
  * unit_price : DECIMAL
}

Order ||--|{ OrderLine : contains
Product ||--o{ OrderLine : referenced by
@enduml

The compound key annotation is a modeling convention. It documents intent but does not create a database constraint.

Step 5: Build the Complete ERD

The following source is copyable and covers entities, required and optional attributes, keys, and four relationship shapes.

@startuml
title Order database ERD
left to right direction

entity Customer {
  * customer_id : UUID <<PK>>
  --
  * email : VARCHAR(255) <<UK>>
  display_name : VARCHAR(120)
  * created_at : TIMESTAMP
}

entity Address {
  * address_id : UUID <<PK>>
  --
  * customer_id : UUID <<FK>>
  * line_1 : VARCHAR(255)
  line_2 : VARCHAR(255)
  * city : VARCHAR(120)
  * country_code : CHAR(2)
}

entity Order {
  * order_id : UUID <<PK>>
  --
  * customer_id : UUID <<FK>>
  shipping_address_id : UUID <<FK>>
  * status : VARCHAR(30)
  placed_at : TIMESTAMP
}

entity OrderLine {
  * order_id : UUID <<PK, FK>>
  * line_number : INTEGER <<PK>>
  --
  * product_id : UUID <<FK>>
  * quantity : INTEGER
  * unit_price : DECIMAL(12,2)
}

entity Product {
  * product_id : UUID <<PK>>
  --
  * sku : VARCHAR(40) <<UK>>
  * name : VARCHAR(255)
  * current_price : DECIMAL(12,2)
}

Customer ||--o{ Address : stores
Customer ||--o{ Order : places
Address |o--o{ Order : selected for
Order ||--|{ OrderLine : contains
Product ||--o{ OrderLine : referenced by
@enduml

The address relationship is optional on the order side because this example permits an order to exist before shipping details are selected. That is a business decision, not a PlantUML recommendation.

IE vs Chen vs Class Diagram

Choose notation based on the question:

The PlantUML class diagram guide explains composition, aggregation, dependencies, and visibility. A class diagram may resemble an ERD, but the two views should not be treated as interchangeable.

A runtime request that creates these records belongs in the PlantUML sequence diagram guide. For higher-level application boundaries around the database, continue with C4-PlantUML context and container views.

Common ER Diagram Mistakes

Frequently Asked Questions

Does PlantUML have a dedicated ERD syntax?

Yes. PlantUML documents Information Engineering notation and Chen EER notation. IE extends class diagram syntax with crow's-foot endpoints and mandatory attributes; Chen uses a separate conceptual notation.

How do I mark a primary key?

Use a clearly documented label such as <<PK>>. Do not rely on the IE *, because the official documentation defines it as a mandatory-attribute marker.

When the model needs methods, interfaces, inheritance, or lifecycle ownership rather than database-oriented entities, use the official PlantUML class diagram syntax and the related class diagram guide instead.

Can PlantUML generate SQL?

The diagram syntax does not validate or generate a production schema by itself. Use database-specific migration or modeling tools for executable DDL and keep the diagram aligned through review or automation.

Where can I compare Mermaid and PlantUML ER diagrams?

See the existing Mermaid vs PlantUML ER diagram comparison for tool-selection intent.

Next Steps

Copy the complete ERD, replace the entities with your own schema, and document the meaning of every key label and optional endpoint. Then compare the rendered diagram with the actual migration files.

Use the PlantUML examples hub to choose the next view, the class diagram tutorial for domain structure, or the PlantUML C4 guide for architecture. Refer to the official IE diagram and Chen ER diagram pages for the full notation.