ブログ

MermaidでER図を書く：記法から限界まで

READMEやWikiにER図を載せたいなら、Mermaidがいちばん身軽な答えです。コードブロックをひとつ書けばGitHubが勝手に図として描いてくれるので、画像ファイルを作ってアップロードして更新するという作業がまるごと消えます。

この記事ではerDiagramの記法を掲示板DBの例でゼロから覚え、リレーション記号の読み方、実際に使うとぶつかる壁、そしてMermaidにはできないことまで順番に扱います。

どこに書けば図になるのか

Mermaidは図をテキストで書く記法で、それを絵に変えるのはレンダラーの仕事です。すでに使っているツールの多くにレンダラーが入っています。

  • GitHub / GitLab: Markdownの```mermaidコードブロックを自動で描画します。READMEにER図を載せる一番よくあるルートです。
  • Notion: コードブロックを作って言語をMermaidにするだけです。
  • VS Code: Markdown Preview Mermaid Supportのようなプレビュー拡張を入れれば、エディタの中でそのまま見えます。
  • mermaid.live: 公式のオンラインエディタです。記法を試したり、PNG/SVGで書き出したりするのに便利です。

インストールも登録も要らず、いま使っているドキュメントツールにコードブロックを書くだけ。これがMermaid最大の魅力です。

最初の図: テーブルひとつから

erDiagramと宣言して、テーブル（エンティティ）を波かっこで書きます。各行は「型 カラム名 キー表示」の順です。

erDiagram
  MEMBERS {
    bigint id PK
    varchar email UK
    varchar nickname
    datetime created_at
  }

PK・FK・UKがそれぞれ主キー・外部キー・ユニークの表示で、レンダリングすると表形式のエンティティボックスになります。カラムに説明を付けたければ、行末に引用符で書きます。

    bigint id PK "サロゲートキー"

varchar(255)のように桁数まで書く表記も、mermaid 10では正常にレンダリングされます。ただしGitHubなどのレンダラーは内蔵バージョンがまちまちなので、古い環境でエラーが出たら、まず括弧を外してみるのが早いです。

リレーション記号の読み方

テーブル2つの関係は1行で書けます。

  MEMBERS ||--o{ POSTS : "作成"

「会員1人が投稿を0件以上作成する」という意味です。記号が暗号めいて見えますが、構造が分かれば単純です。線の両端の記号がそれぞれのテーブル側のカーディナリティで、内側が最小・外側が最大です。

記号 意味
|| ちょうど1
|o 0または1
}| 1以上
}o 0以上

よく使う組み合わせはこう読めます。

  • ||--o{ — 1対0..N（いちばんよくある親子）
  • ||--|{ — 1対1..N（子が最低1件は要るとき）
  • }o--o{ — N対M（多対多）

真ん中の線にも意味があります。--（実線）は識別関係、..（点線）は非識別関係です。最初は実線だけで統一しても図を読むのに支障はないので、区別が必要になったら分ければ十分です。このカラスの足の体系自体が初めてなら、ER図の記号まとめで基礎から確認できます。

実践: 掲示板DBを丸ごと書いてみる

会員・カテゴリ・投稿・コメント、4テーブルの掲示板を丸ごと書くとこうなります。

erDiagram
  MEMBERS ||--o{ POSTS : "作成"
  CATEGORIES ||--o{ POSTS : "分類"
  POSTS ||--o{ COMMENTS : "付く"
  MEMBERS ||--o{ COMMENTS : "作成"

  MEMBERS {
    bigint id PK
    varchar email UK
    varchar nickname
  }
  CATEGORIES {
    int id PK
    varchar name UK
  }
  POSTS {
    bigint id PK
    bigint member_id FK
    int category_id FK
    varchar title
  }
  COMMENTS {
    bigint id PK
    bigint post_id FK
    bigint member_id FK
  }

レンダリング結果はこうなります。

Mermaid erDiagramで書いた掲示板のER図 — 4テーブルとリレーション線のレンダリング結果

リレーションを上にまとめて書き、エンティティ定義を下に置くのがコツです。図の骨格（どれとどれがつながるか）がコードの最初の数行で読み取れますし、diffが出たときもリレーションの変更とカラムの変更が分かれて見えます。

この掲示板の設計自体がどう出来上がったのか — エンティティの拾い方やリレーションの決め方から — が気になったら、ER図の書き方で同じ例をゼロから扱っています。

使ってみるとぶつかる壁

Mermaid ERDを実務で使うと、いくつかの壁にすぐ出会います。上のレンダリング画像にもヒントがあります。

配置に手を出せません。 上の図でCATEGORIESが右上に、COMMENTSが下に置かれたのは、すべてMermaidが決めたことです。テーブルをドラッグして動かす機能はなく、コードの順序を変えれば結果は変わりますが、狙いどおりに置けるわけではありません。4テーブルなら気になりませんが、20を超えると線が絡まり始め、そこから配置を直せないことが本当に不便になります。

スキーマ情報を全部は載せられません。 NOT NULL、デフォルト値、インデックス、CASCADEといった情報は書く場所がありません。図としての要約には十分ですが、このコードだけを見て実際のテーブルは作れないということです。

SQLと行き来する道がありません。 MermaidのコードをDDLに変換する機能も、DDLを読んでMermaidを作る機能も本体にはありません。図と実際のスキーマを別々に手で管理する、二重管理が始まる地点です。

テーブル定義書が出せません。 検収や引き継ぎで求められる定義書は、別に作ることになります。

おすすめの役割分担

Mermaidをやめようという話ではありません。方向を決めようという話です。原本はDDLに置いて、Mermaidはドキュメント用の出力として使う。

スキーマの原本がDDLなら実際のDBとずれる心配がなく、ドキュメントに図が必要になったらDDLからMermaidを作ればいい。変換はAIに任せるのが楽です — DDLを貼って「erDiagramに変換して」と頼めば終わりなので、手作業で変換するような仕事ではありません。AIにスキーマ作業を頼むコツはAIでER図を作るに書いてあります。

そして編集・検証・定義書が要る段階 — 配置を整えてレビューに持っていく、チームで同じ図を見ながら作業する — になったら、専用ツールの出番です。WorksCove ERDはDDLを貼り付ければ編集できる図になり、同じデータからテーブル定義書まで出せます。DDLの取り出し方から始めたければ、SQLからER図を自動生成するに手順があります。

よくある質問

Mermaid のER図はどこでレンダリングされますか？

GitHubとGitLabはMarkdown内のmermaidコードブロックを自動で描画します。Notionもコードブロックの言語をMermaidにすれば表示されます。VS Codeはプレビュー拡張機能を入れれば対応でき、手早く試すなら公式オンラインエディタのmermaid.liveに貼り付けるのが一番速いです。

データ型に桁数（VARCHAR(255)）まで書けますか？

書けます。mermaid 10でvarchar(255)のような括弧付きの型が正常にレンダリングされることを確認しました。ただしレンダラーごとに内蔵のmermaidバージョンが違うため、古い環境ではエラーになることがあります。描画されないときは括弧を外すのが一番手軽な対処です。

テーブルの位置を自由に動かせますか？

動かせません。Mermaidは配置をすべて自動で計算し、手動調整の機能がありません。コードの順序を変えると結果は多少変わりますが、狙った場所に置く方法はないので、配置を整えたくなったときが専用ツールに移るタイミングです。

Mermaidのコードから実際のDBテーブルを作れますか？

Mermaid自体にSQLへの書き出し機能はありません。流れを逆にするのがおすすめです。スキーマはDDLで管理し、ドキュメントに図が必要になったらDDLからMermaidを生成する方向なら、どちらの情報も失われません。

まとめると — READMEに載せる軽い構造図ならMermaidより速いものはなく、編集して検証して定義書まで出す段階なら専用ツールの仕事です。重ねて使うのではなく段階で分ければ、それぞれに一番得意なことだけをさせられます。