SQL to Mermaid ER Diagram

Paste CREATE TABLE SQL and get a Mermaid erDiagram you can paste into any GitHub README, GitLab wiki, Notion page, or Markdown renderer that supports Mermaid. Entities show column names, SQL types, and PK/FK markers; foreign key relationships are rendered as labeled connector lines with the correct cardinality notation.

How to use the SQL to Mermaid ER Diagram

Paste your CREATE TABLE DDL, click Generate Mermaid, and copy the output. The output is already wrapped in a Markdown fenced code block with the mermaid language tag so you can paste it directly into a GitHub README or any Markdown editor that renders Mermaid.

  1. Entities — each table becomes an entity block listing column name, type, and a label (PK for primary keys, FK for columns that are referenced by or are foreign keys, blank otherwise).
  2. Relationships — every FOREIGN KEY ... REFERENCES or inline REFERENCES clause becomes a relationship line. The cardinality is }o--|| (zero-or-more to exactly-one), the standard many-to-one notation for a FK column.
  3. Paste the output into a GitHub README, GitLab wiki, Notion embed block, Obsidian note, or any Markdown environment with Mermaid support. The diagram renders automatically.

What is a Mermaid erDiagram and how is it used in documentation?

Mermaid is a JavaScript-based diagramming library that renders diagrams from plain text definitions embedded in Markdown fenced code blocks. The erDiagram diagram type produces entity-relationship diagrams from a concise syntax: entity blocks list attributes with type and key labels; relationship lines connect entities with cardinality markers. GitHub, GitLab, Notion, Obsidian, and dozens of other tools render Mermaid natively, making it the most portable way to include data model diagrams in code documentation without external diagram files.

The Mermaid ER syntax uses a specific cardinality notation: ||--|| (exactly one to exactly one), ||--o{ (one to zero-or-more), }o--|| (zero-or-more to one). The last pattern — many-to-one — is what a foreign key relationship represents: many rows in the child table reference exactly one row in the parent table. Attribute lines in an entity block have the form type name label where label can be PK, FK, or UK.

Embedding the schema diagram in a repository README means that developers cloning the project immediately see the data model without running the database. Combined with the SQL to DBML Converter for dbdiagram.io, you have two complementary documentation outputs from the same DDL source.

Common use cases

  • README documentation — paste the Mermaid block into your project README so the ER diagram renders on GitHub with zero additional tooling.
  • Architecture Decision Records — include the schema diagram in an ADR Markdown file to capture the data model at a point in time.
  • API documentation — include the entity diagram in an OpenAPI or Markdown API reference to show the underlying data model.
  • Pull request reviews — add the diagram to a migration PR description so reviewers see the schema change visually, not just as raw SQL.
  • Wiki pages — paste into Notion, Confluence (via Mermaid plugin), or GitLab wiki for living schema documentation that stays in the repo.

Frequently asked questions

Which Markdown platforms render Mermaid automatically?
GitHub (all public and private repos), GitLab, Notion, Obsidian, Gitea, and Docusaurus support Mermaid code blocks natively. For Confluence, install the Mermaid for Confluence plugin. VS Code requires the Markdown Preview Mermaid Support extension.

What cardinality notation does the converter use?
All foreign key relationships are emitted as }o--|| (zero-or-more on the FK side to exactly-one on the referenced side), representing the standard many-to-one FK relationship. Mermaid does not infer one-to-one from DDL alone; adjust manually if needed.

Can I customize the diagram layout?
Mermaid ER diagrams are auto-laid-out — there is no manual positioning. For more control over layout, use the SQL to DBML Converter and render in dbdiagram.io, which allows dragging entities.

How are column types shown in the diagram?
The raw SQL type is used, simplified by removing parenthetical size arguments (VARCHAR(255) → varchar, DECIMAL(10,2) → decimal). This keeps the diagram readable while preserving type information.

Does the output wrap in a code fence automatically?
Yes — the output includes the opening ```mermaid and closing ``` fences so you can paste directly into a Markdown file. If your environment does not use fenced code blocks (e.g. a raw HTML page), remove the first and last lines.