Text-Based Entity Relationship Diagrams with Mermaid.js

Entity Relationship Diagrams (ERDs) are simple and effective ways of communicating relational database designs.

In this article we'll explore what entity relationship diagrams are and how Mermaid.js makes it easy to create and maintain ERDs for your applications at zero cost.

While there are many tools out there that will help you make a nice and polished entity relationship diagram, like the one I made above using Visual Paradigm Online, these tools usually have a few issues:

• ERD tools often require or encourage payment in either a one-time or subscription basis
• Working with ERD tools can sometimes feel like a struggle to arrange the perfect diagram and understand the tool's conventions.
• ERDs are hard to version control, usually requiring that you commit the resulting image and files separate, requiring other developers to have access to the tools you used to create the diagram originally.

Thankfully, Mermaid.js allows us to create and version entity relationship diagrams in human-readable text files.

What is Mermaid.js?

Before we go any further, let's talk about what Mermaid.js is and how you get access to it.

Mermaid.js is an open-source JavaScript library that allows you to generate a variety of diagram types from specially formatted text.

While you can add JavaScript to support Mermaid diagrams on any website, Mermaid also integrates into a variety of existing tools including:

• GitHub
• GitLab
• Azure Devops
• Polyglot Notebooks
• Obsidian
• Plugins for Jira and Confluence

The easiest way of trying mermaid is likely going to be creating a .md file in GitHub and then adding a mermaid block to your document as shown below:

You can also try out Mermaid at any time by going to Mermaid.live and creating a document without even needing to log in.

This means that Mermaid is highly available in many of the tools you already use in your ecosystem, but also flexible enough to be added to your blog or web site.

Creating an Entity Relationship Diagram with Mermaid.js

Let's create a simple entity relationship diagram that tracks cities in various states or provinces throughout various countries in the world.

We'll do this by working in four phases:

1. Defining our entities
2. Adding relationships between entities
3. Adding attributes / fields to our entities
4. Adding primary and foreign keys to our entities

Creating Entities

First, we can create a simple entity relationship diagram by identifying our entities. In our case we're going to feature city, state, and country entities. These entities will later become tables in our relational database.

We start by adding an entity relationship diagram in markdown:

erDiagram
    CITY
    STATE
    COUNTRY

This generates a fairly simple diagram with the three separate entities as boxes:

Adding Relationships Between Entities

Next, we'll define the relationships between our three tables.

We do this with "crow's foot" notation. With crow's foot, you describe how entities relate to each other in terms of one-to-one and one-to-many relationships.

For example, the following diagram shows the relationship between countries and states or provinces:

Here, a country has at least one state or province and a state has one and only one province.

When reading "crow's feet" notation you start at one entity and then follow its line to the other entity, looking at the pair of lines near the other entity.

For example, when starting from COUNTRY we skip over the two || lines and look instead at the |{ lines near the STATE. These lines say that a country has at least one state inside of it, but possibly many.

If we instead wanted to say that a COUNTRY might exist without any states in it at all, that would be a O{ type of ending and would look like this:

In Mermaid.js, we can describe our relationships with lines like this: COUNTRY ||--|{ STATE to say that a country has one or many states and a state has one and only one country.

The supported endings we have for our lines are as follows:

• O| - Zero or one
• || - One and only one
• O{ - Zero or many
• |{ - One or many

We can also add a : and then a string describing our relationship after each relationship to describe it on the diagram.

Our entity relationship diagram for states and countries is as follows:

erDiagram
    COUNTRY
    STATE
    CITY
    COUNTRY ||--|{ STATE : "Has"
    STATE ||--|{ CITY : "Has"
    CITY ||--o| STATE : "Is capital of"
    CITY ||--o| COUNTRY : "Is capital of"

With that we have a working Entity Relationship Diagram!

Note: technically speaking, now that we describe our entities with relationships, we no longer need to list the entities on their own lines for them to be included in the diagram. I'm including them here for completeness and to make the next step make more sense.

Adding Fields to our Entity Relationship Diagram

If all we wanted to model was the entities in our system, we could declare victory and move on. However, you'll often want to represent the different fields / columns / attributes of your database tables in your entity relationship diagrams.

The code for adding fields to your ERDs is fairly straightforward. Instead of listing the entity name on its own, we add { } after it and then list individual attributes for that entity on separate lines along with their data types.

For example, CITY might be represented as follows:

    CITY {
        int city_id
        string name
        string state_abbreviation
    }

Here we declare the entity we care about, then list the attributes in that entity with the type of that attribute before its name.

The full entity relationship diagram code now becomes:

erDiagram
    CITY {
        int city_id
        string name
        string state_abbreviation
    }
    STATE {
        string state_abbreviation
        string name
        int country_id
    }
    COUNTRY {
        int country_id
        string name
    }
    COUNTRY ||--|{ STATE : "Has"
    STATE ||--|{ CITY : "Has"
    CITY ||--o| STATE : "Is capital of"
    CITY ||--o| COUNTRY : "Is capital of"

And just like that, we've defined the data in our entities!

Adding Primary and Foreign Keys to our ERD

The last step in our journey is to add primary and foreign keys to our entity relationship diagram.

As a review, a primary key uniquely identifies each row in a database table while a foreign key references a primary key in another table and helps a database preserve referential integrity on inserts, updates, and deletions.

We can indicate primary keys and foreign keys by adding a PK or FK after the column name in our Mermaid.js ERD code as follows:

erDiagram
    CITY {
        int city_id PK
        string name
        string state_abbreviation FK
    }
    STATE {
        string state_abbreviation PK
        string name
        int country_id FK
    }
    COUNTRY {
        int country_id PK
        string name
    }
    COUNTRY ||--|{ STATE : "Has"
    STATE ||--|{ CITY : "Has"
    CITY ||--o| STATE : "Is capital of"
    CITY ||--o| COUNTRY : "Is capital of"

And with that minor change we now have PK and FK markers in our entity relationship diagram.

Note: If you ever needed a column to be part of both a primary and secondary key, you can list them both with commas. Your row would look something like the following:

int some_id PK,FK

Next Steps

Check out the full documentation for Mermaid.js Entity Relationship Diagrams for some additional features, information on styling these diagrams, and any updates that happen after this article is published.

Personally, I plan on using Mermaid.js for my entity relationship diagrams on personal projects going forward and may even consider them for some larger projects involving teams.

I find Mermaid.js ERDs to be intuitive and lightweight. The generated diagrams may not be as pretty as something I might make in another tool, but they're also significantly easier to maintain over time and share with others. I also find not needing to worry about having a "perfect" diagram somewhat freeing and that liberates my time towards building the application instead of building beautiful documentation that quickly gets out of date and forgotten.

Stay tuned for more content on other features of Mermaid.js!