Recipes

erdscope レシピ集

「何ができるか」ではなく「やりたいこと」からたどる実践ガイド。各レシピはコピペで動くコマンドと、その先の発展アイデア付きです。

$ pip install erdscope && erdscope demo

RECIPE 1 稼働中のデータベースから5分でER図 ドキュメントのないDBを引き継いだ。まず全体像が見たい。 RECIPE 2 データベースなしで、コードからER図 Rails / Django / Prisma / SQLAlchemy / Laravel のコードだけでモデル関連図を作る。 RECIPE 3 AI にスキーマを読ませる DB構造を踏まえた実装・レビューを AI にさせる。トークン効率よく。 RECIPE 4 CI/CD に組み込む スキーマドキュメントを自動更新し、想定外の変更はドリフト検知で止める。

レシピは今後追加予定です（DB×コードの突き合わせ、Excel定義書、dbdiagram.io 連携など）。

Recipe 1 — 稼働中のデータベースから5分でER図 #

場面: ドキュメントのないシステムを引き継いだ。テーブルが数十個あり、どれとどれが繋がっているのか分からない。まず全体像を眺めたい。

erdscope に接続URLを渡すだけで、テーブル・カラム・外部キーを読み取って 1枚の自己完結HTMLを生成します。サーバーもアカウントも不要、生成されたファイルを開くだけです。

# MySQL（ドライバ: pip install pymysql — 無ければ mysql CLI に自動フォールバック）
erdscope "mysql://readonly_user:PASS@127.0.0.1:3306/myapp_production" -o schema.html

# PostgreSQL（ドライバ: pip install psycopg）
erdscope "postgresql://readonly_user:PASS@localhost/myapp" -o schema.html

# SQLite はドライバ不要（標準ライブラリで動作）
erdscope sqlite:///path/to/app.db -o schema.html

安全に接続する erdscope はスキーマ情報を読むだけで書き込みは一切しませんが、本番DBに繋ぐなら SELECT 権限だけの読み取り専用ユーザーを作って渡すのが安心です: GRANT SELECT ON myapp_production.* TO 'readonly_user'@'%';

生成されるビューア（クリックでライブデモ）。テーブルをクリックすると列詳細、ダブルクリックで関連テーブルにフォーカス。

見どころ

左のテーブル一覧で表示するテーブルを選択。チェックした起点から関連を自動展開できます。
エッジの種類で情報の出所が分かります — DBの実FK、コード由来の関連、名前からの推測は区別して描かれます。
テーブルが多すぎるときは生成時に絞り込み: --only 'order*' --exclude 'tmp_*'

発展アイデア

図と一緒に Excel テーブル定義書も出す: --excel 定義書.xlsx
気づいたことを設計メモ（notes）として設定ファイルに書き溜め、図に表示する
このスキーマを AI に読ませる → Recipe 3

Recipe 2 — データベースなしで、コードからER図 #

場面: DBへの接続権限がない。あるいはコードレビューで「このPRのモデル変更で関連はどうなる？」を図で確認したい。

erdscope はアプリケーションコードを静的解析します（コードは実行しません）。 Rails / Django / Prisma / SQLAlchemy / Laravel のプロジェクトを渡すと自動判定してモデルと関連を読み取ります。

# プロジェクトのパスを渡すだけ（Rails / Django / Prisma / SQLAlchemy / Laravel を自動判定）
erdscope --models path/to/your-app -o schema.html

コードだけの図は「論理モデル」— アプリが宣言している関連（belongs_to や ForeignKey、Prisma の @relation、Eloquent の hasMany）がエッジになります。マイグレーション漏れや「コードには関連があるのにDBにはFKがない」の検出にも役立ちます。

見どころ

DBがなくても列情報が出ます（Django / Prisma / SQLAlchemy はフィールド定義から。Rails は db/schema.rb があれば列も揃います。Laravel は関連のみ＝DBと組み合わせる前提です）。
関連名（has_many :items, through: など）がエッジのラベルに反映されます。

発展アイデア

DBとコードを突き合わせるのが erdscope の本領です: erdscope "mysql://…" --models path/to/app -o schema.html — 物理（DB）と論理（コード）を1枚に統合し、情報の出所をバッジで区別します。
dbdiagram.io の DBML や Mermaid のスケッチも入力にできます（design-first の下書きから開始）。

Recipe 3 — AI にスキーマを読ませる #

場面: ChatGPT / Claude に「このDBを踏まえて実装して」と頼みたい。でもダンプSQLを貼るとトークンを浪費するし、ER図の画像は読み違える。

--emit-digest は、スキーマ全体をトークン効率の高い Markdown に凝縮します。列・型・PK/FK・関連に加えて、設定ファイルに書いた設計メモ（notes）— 機械には推測できない設計意図 — も一緒に含められるのが特長です。

# スキーマを Markdown ダイジェストに（- で標準出力）
erdscope "mysql://readonly_user:PASS@localhost/myapp" --emit-digest schema.md

出力はこんな形です（同梱のサンプルDBの例）:

# demo_shop — schema digest

## Tables (13)

### addresses
- id: integer, pk
- user_id: integer, fk→users
- kind: string
- line1: string
- city: string
- country: string
Rel: belongs_to users as user fk=user_id

### categories
- id: integer, pk
- parent_id: integer, fk→categories
- name: string
Rel: belongs_to categories as parent fk=parent_id
…

使い方の例

チャットに貼る: schema.md を貼り付けて「この構造を踏まえて注文キャンセルAPIを設計して」。
コーディングエージェントに常備させる: リポジトリに schema.md をコミットし、 CLAUDE.md やプロジェクトの README から参照させる。スキーマ変更時に再生成するだけ。
設計レビューをさせる: 「正規化の問題、命名の不整合、インデックス漏れを指摘して」。

設計意図も渡す 設定ファイルの notes に「論理削除は deleted_at 方式」「この列は廃止予定」のようなメモを書いておくと、digest にそのまま含まれます。AI が推測でなく宣言された意図を前提に答えられるようになります。

発展アイデア

スナップショットを撮って（--emit-json schema.json）、CI で --diff schema.json — 「DBが基準からズレたら落とす」ドリフト検知ゲートに → Recipe 4
マイグレーション前後で digest を2回生成して AI に差分の影響を聞く。

Recipe 4 — CI/CD に組み込む: ドキュメント自動更新とドリフト検知 #

場面: ER図や定義書は作った瞬間から腐り始める。手動更新は必ず忘れられる。最新のドキュメントは機械に作らせて、想定外のスキーマ変更は CI で止めたい。

スキーマドキュメントを自動更新する

erdscope は CI 向きにできています — 生成物は自己完結の1ファイルなので、そのまま GitHub Pages や社内ポータルに置けます。--emit-digest の Markdown は、ビルド時に生成してプロダクトのマニュアルの「データモデル」章として組み込む部品にもなります。

# HTML と Markdown ダイジェストをビルド成果物として生成
erdscope "$DB_URL" -o site/schema.html --no-open --emit-digest site/schema.md

ドリフト検知ゲート

基準スナップショットをリポジトリにコミットしておき、CI で現在のDBと照合します。 exit code は 0 = 一致 / 1 = 差分あり / 2 = エラー — 差分があればジョブがそのまま落ちます。

# 基準を作ってコミット（意図したスキーマ変更を取り込むときに更新）
erdscope "$DB_URL" --emit-json schema.lock.json --no-open

# CI 側: 基準からズレていたら exit 1（差分は人間可読で表示）
erdscope "$DB_URL" --diff schema.lock.json

GitHub Actions の最小テンプレート:

name: schema-docs
on:
  push: { branches: [main] }
  schedule:
    - cron: '0 6 * * 1'   # 毎週月曜、鮮度チェック
jobs:
  schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install erdscope pymysql
      - name: Generate schema docs (HTML + digest)
        run: erdscope "$DB_URL" -o site/schema.html --no-open --emit-digest site/schema.md
        env:
          DB_URL: ${{ secrets.READONLY_DB_URL }}
      - name: Schema drift gate
        run: erdscope "$DB_URL" --diff schema.lock.json
        env:
          DB_URL: ${{ secrets.READONLY_DB_URL }}
      # site/ を Pages / artifact として公開する step をここに

接続情報は secrets に CI から渡す接続URLも読み取り専用ユーザーで（Recipe 1 と同じ）。 URL は必ず secrets に入れ、ログに出さないでください。

ポイント

レポートだけ欲しい（落としたくない）ときは --diff-exit-zero。機械処理するなら --diff-format json。
「意図した変更」はマイグレーションと同じ PR で schema.lock.json を更新する運用にすると、基準を動かせるのはレビューを通った変更だけになります。

発展アイデア

PR ごとに schema.html を artifact に添付 — レビュー中いつでも最新の図が見られる。
schema.md（digest）をリポジトリにコミットして、コーディングエージェントの常備知識にする → Recipe 3

つまずいたら #

ブラウザが開かない（サーバー / WSL / SSH先で実行した） — 生成自体は成功しています。 --no-open を付けて生成し、出来た HTML ファイルを手元にコピーして開いてください。1ファイルで完結しているのでコピーするだけで動きます。
MySQL / PostgreSQL に繋がらない — ドライバ（pip install pymysql / pip install psycopg）を確認。無い場合は CLI（mysql/psql）へのフォールバックを試みます — 詳細。
日本語コメントが文字化けする — マニュアルのトラブルシューティング参照。
テーブルが多すぎて図が重い — 大規模スキーマの扱い参照（--only/--exclude）。

その他はマニュアルのトラブルシューティング / FAQ へ。解決しなければ GitHub Issues でお知らせください。