Intro

この記事はAIを活用して作成しました。

Crowfootは、データベースのスキーマファイルからERDを作り、静的Webアプリとして共有するCLIツールです。Liam ERDを基にしたフォークで、元の図に配置保存・メモ・色・テーブルグループなどの機能を追加しました。

ERDは、テーブル同士が線でつながっているだけでは読みにくいことがあります。関連テーブルを近くに置き、ドメインごとにまとめ、関係の横に説明を添えることで構造が見えてきます。そうして整理した配置が再読み込みや再生成後も残ると、文書として使いやすくなります。

実際のプロジェクトのDB構造を文書として共有するためLiam ERDを使う中で、移動したテーブル位置が初期化されることや、キャンバスに説明を残せないことを不便に感じました。MySQL DDLへの出力も必要だったため、まずこれらを追加しました。

Crowfootは、スキーマとともに人が整理した配置と説明を残すことに重点を置いています。出力は、別のバックエンドなしでHTTP配信できる静的サイトです。

リンク

• Crowfootデモ
• GitHub
• npmパッケージ
• 使い方

上部と本文の画面は公開デモから撮影しました。デモのスキーマはNiVocaのレガシー版で、現在のFlutterアプリの本番DBとは別のものです。

主な機能

開き直しても残る配置

移動したテーブルの位置をURLに含めて共有できます。配信されたlayout.jsonにURLの編集内容を重ねる構造で、erd from-linkコマンドにより、リンクの変更を配置・グループ・メモのファイルへ保存できます。

これらのファイルをスキーマと一緒にバージョン管理し、生成したサイトに提供すれば、再ビルド後も配置と説明を引き継げます。位置が未設定のテーブルは自動配置を使うため、新しいテーブルが増えるたびに全体を最初から並べ直す必要はありません。

複数のテーブルやメモをまとめて選択し、移動や色の設定ができます。関連テーブルを名前付きグループにまとめると、キャンバスとサイドバーで同じ区分を確認できます。

拡大時はカラムを詳しく、縮小時はテーブル名やグループ名を中心に表示するよう、情報量も調整します。同じキャンバスで全体構造から気になるテーブルまで行き来できます。

図の上に説明を残す

キャンバスにメモを置き、サイズ・色・文字サイズを調整できます。テーブルや関係線だけでは伝わらない業務ルールや設計理由を、近くに書き添えるためのものです。

配置・グループ・メモをそれぞれlayout.json、groups.json、memos.jsonに保存し、スキーマと一緒に管理できます。共有したERDは標準で閲覧モードになり、編集モードを有効にしたときだけ配置や内容を変更できます。

ブラウザーでスキーマを編集する

編集モードでは、テーブル・カラム・制約・インデックスの修正と外部キーの接続ができます。変更対象はビューアー内で扱うスキーマであり、実際のデータベースにDDLを実行する機能ではありません。

作業結果はDDLや画像としてエクスポートできます。元の出力機能にMySQL DDLを追加し、構造を確認して別の形式に移す作業にも使えるようにしました。

CLIで生成して配置する

PostgreSQL SQLのほか、Prisma、Rails、Drizzle、tblsなどのスキーマを入力できます。簡単な生成コマンドは次のとおりです。

1
npx crowfoot erd build --input schema.sql --format postgres --output-dir dist
2
npx serve dist/

複数のマイグレーションSQLを順番に読み、最終的なスキーマを組み立てることにも対応しています。SQLをDBに実行する方式ではないため、動的SQLやデータ条件によって変わる変更までは再現できません。解釈できない構文を黙って飛ばさないよう、--strictオプションでビルドを失敗させられます。

erd planとerd arrangeは、座標を一つずつ指定する代わりに、テーブルをどのグループにまとめるかという計画から配置ファイルを作る機能です。AIエージェントもグループや説明を提案し、配置はCLIに任せられる構成にしました。

技術スタック

設計と実装

全体構成

スキーマを読み取って成果物を作るCLIと、それを探索・編集するブラウザービューアーを分けました。成果物は静的Webアプリなので、別のバックエンドなしで共有できます。

1
flowchart TB
2
  Input["SQL · ORMスキーマ"] --> CLI["Crowfoot CLI<br/>スキーマ解析 · Webアプリ生成"]
3
  CLI --> Static["静的ERD Webアプリ"]
4
  Metadata["配置 · グループ · メモJSON"] --> Viewer["React Flowビューアー"]
5
  Static --> Viewer
6
  URL["URLの編集内容"] --> Viewer
7
  Viewer --> Export["共有リンク · DDL · 画像"]
8
  Viewer --> FromLink["erd from-link"]
9
  FromLink --> Metadata

スキーマ解析の抜けを明らかにする流れ

1
flowchart TB
2
  Input["スキーマ · マイグレーションSQLの入力"] --> Parse["スキーマ解析"]
3
  Parse --> Unsupported{"解釈できない構文がある？"}
4
  Unsupported -->|なし| Build["静的ERDを生成"]
5
  Unsupported -->|あり| Strict{"strictモード？"}
6
  Strict -->|はい| Fail["ビルドを失敗させ欠落を通知"]
7
  Strict -->|いいえ| Build
8
  Parse -. JSON出力 .-> Report["解析結果 · 未対応構文の確認"]

スキーマを更新しても説明を残す

スキーマを作るデータと、画面上で整理した情報を分けて管理しました。スキーマを読み直しても既存テーブルの配置や説明を再適用できてこそ、図を使い捨てではなく継続して更新する文書として扱えるためです。

最近は、解析できなかった内容を明らかにすることにも力を入れました。--jsonで解析結果と未対応構文を確認し、入力ファイルのハッシュ・ツールのバージョン・ビルド時刻を成果物に残します。見栄えのよい図でもスキーマ変更が一つ黙って抜けると文書として信頼しにくいため、自動化の中で欠落を確認できるようにしたものです。

また、フォークで追加した機能と元の機能を分け、READMEとNOTICEに記載しました。CrowfootはLiam ERD全体を作り直したものではなく、既存ツールを実際に使う中で必要だった機能を加え、別の名前で配布するプロジェクトです。