ERD Tool

Unique Visionで使われているデータベースERD管理システム。

JSONベースのスキーマ定義から、EJSテンプレートを使ったコード生成・ドキュメント生成を行うツールです。VSCode拡張機能とCLI、MCPサーバーとして利用できます。

主な機能

• スキーマ解決 (resolve): 複数ファイルに分割されたスキーマを1つに統合
• テンプレート生成 (generate): EJSテンプレートからソースコード・ドキュメントを自動生成
• スキーマ検証 (validate): スキーマファイルの構文・整合性チェック
• EDM変換: EDM形式（XML）との相互変換

パッケージ構成

CLI使用方法 (npx)

GitHub Packagesから直接CLIを実行できます：

# 初回のみ：GitHub Packagesへの認証設定
npm login --scope=@uniquevision --registry=https://npm.pkg.github.com
# ユーザー名: GitHubユーザー名
# パスワード: Personal Access Token（packages:read権限が必要）

# CLIの実行
npx @uniquevision/erd-tool-cli@latest

# コマンド例
npx @uniquevision/erd-tool-cli@latest validate schema.erd.json
npx @uniquevision/erd-tool-cli@latest generate schema.erd.json
npx @uniquevision/erd-tool-cli@latest resolve schema.erd.json -o resolved.json

CLIコマンド

# スキーマファイルの検証
erd validate <schema-file>
erd validate schema.erd.json --no-warnings

# テンプレートからコード生成
erd generate <schema-file>
erd generate schema.erd.json -o ./output
erd generate schema.erd.json -w ./workspace

# スキーマの解決（インクルード展開）
erd resolve <schema-file>
erd resolve schema.erd.json -o resolved.json

スキーマファイル (.erd.json)

ERDスキーマはJSON形式で記述します。以下の要素を定義できます。

基本構造

{
  "meta": {
    "version": "1.0.0",
    "lname": "プロジェクト名"
  },
  "includes": ["other_schema.erd.json"],
  "domains": [...],
  "tables": [...],
  "kbns": [...],
  "errors": [...],
  "structs": [...],
  "interfaces": [...],
  "templates": {...}
}

主要な定義要素

domains（ドメイン）

カラム型の再利用可能な定義です。各カラムはdomainを参照して型情報を継承します。

{
  "domains": [
    {
      "lname": "ID",
      "pname": "id",
      "type": "BIGINT",
      "default": "0"
    },
    {
      "lname": "名前",
      "as": "名",
      "pname": "nm",
      "type": "TEXT",
      "default": "''"
    },
    {
      "lname": "日時",
      "pname": "at",
      "type": "TIMESTAMPZ",
      "default": "NOW()"
    }
  ]
}

tables（テーブル）

データベーステーブルの定義です。カラム、主キー、外部キー、ユニークキーを記述できます。

{
  "tables": [
    {
      "lname": "ユーザー",
      "pname": "users",
      "columns": [
        {
          "domain": "ID",
          "pk": true
        },
        {
          "domain": "名前",
          "lname": "ユーザー",
          "pname": "user"
        },
        {
          "domain": "日時",
          "lname": "作成",
          "pname": "created"
        }
      ],
      "uniqueKeys": [
        {
          "keys": ["user_nm"]
        }
      ]
    },
    {
      "lname": "投稿",
      "pname": "posts",
      "columns": [
        {
          "domain": "ID",
          "pk": true
        },
        {
          "domain": "ID",
          "lname": "ユーザー",
          "fk": {
            "table": "ユーザー"
          }
        }
      ]
    }
  ]
}

kbns（区分値）

コード値（Enum相当）の定義です。

{
  "kbns": [
    {
      "lname": "ステータス",
      "pname": "status",
      "code": "001",
      "values": [
        { "lname": "下書き", "pname": "draft", "code": "01" },
        { "lname": "公開", "pname": "published", "code": "02" },
        { "lname": "非公開", "pname": "archived", "code": "03" }
      ]
    }
  ]
}

errors（エラー定義）

エラーコードとメッセージの定義です。

{
  "errors": [
    {
      "lname": "認証",
      "pname": "auth",
      "code": "001",
      "values": [
        {
          "lname": "認証失敗",
          "pname": "failed",
          "code": "01",
          "db_code": "A0001",
          "message": "認証に失敗しました。",
          "warning": false
        }
      ]
    }
  ]
}

structs（構造体）

データ構造の定義です。APIのリクエスト/レスポンス型などに使用します。

{
  "structs": [
    {
      "lname": "ユーザー情報",
      "pname": "user_info",
      "parameters": [
        { "domain": "ID" },
        { "domain": "名前", "lname": "ユーザー", "pname": "user" }
      ]
    }
  ]
}

interfaces（インターフェース）

APIエンドポイントなどの入出力定義です。

{
  "interfaces": [
    {
      "lname": "ユーザー一覧取得",
      "pname": "get_users",
      "input": "user_list_request",
      "output": "user_list_response"
    }
  ]
}

includes（インクルード）

スキーマを複数ファイルに分割できます。

{
  "includes": [
    "common.erd.json",
    {
      "path": "tables.erd.json",
      "schemaIgnoreKeys": ["templates"]
    }
  ]
}

schemaIgnoreKeysで特定のキーを無視してインクルードできます。

テンプレート生成

EJSテンプレートを使ってスキーマからコードを生成します。

テンプレート設定

{
  "templates": {
    "table": [
      {
        "template": "table.ejs",
        "dir": "models",
        "extension": "ts"
      },
      {
        "template": "table_doc.ejs",
        "file": "docs/${table}.md"
      }
    ],
    "kbn": [
      {
        "template": "kbn.ejs",
        "file": "constants/kbn.ts"
      }
    ],
    "error": [
      {
        "template": "errors.ejs",
        "file": "constants/errors.ts"
      }
    ],
    "struct": [
      {
        "template": "types.ejs",
        "file": "types/structs.ts"
      }
    ],
    "interface": [
      {
        "template": "api.ejs",
        "file": "api/interfaces.ts"
      }
    ]
  }
}

テンプレート出力先の指定方法

テンプレートの出力先は2通りの方法で指定できます：

1. dir + extension: テーブルごとに個別ファイル生成

   { "template": "model.ejs", "dir": "models", "extension": "ts" }
   

   → models/users.ts, models/posts.ts などが生成される

2. file: 固定パスまたは変数展開でファイル生成

   { "template": "doc.ejs", "file": "docs/${table}.md" }
   

ファイル名で使える変数

• ${table} - テーブルのpname
• ${pname} - テーブルのpname
• ${index} - テーブルのインデックス（1から開始）
• ${meta.pname} - メタ情報のpname

タグによるフィルタリング

テーブルにタグを付けて、テンプレート適用対象を制御できます。

{
  "tables": [
    { "lname": "一般テーブル", "pname": "normal", "columns": [...] },
    { "lname": "特殊テーブル", "pname": "special", "tag": ["special"], "columns": [...] }
  ],
  "templates": {
    "table": [
      {
        "template": "normal.ejs",
        "file": "normal/${table}.ts",
        "tag": { "exclude": ["special"] }
      },
      {
        "template": "special.ejs",
        "file": "special/${table}.ts",
        "tag": { "include": ["special"] }
      }
    ]
  }
}

refreshオプション

"refresh": trueを指定すると、テンプレートで生成されたファイルが出力先のファイルと異なる場合のみ更新します。

テンプレート内で使える変数

tableテンプレート

<%# スキーマ全体 %>
<%- schema.meta.version %>
<%- schema.tables.length %>

<%# 現在のテーブル %>
<%- table.lname %>
<%- table.pname %>

<%# カラム %>
<% for (const column of table.columns) { %>
  <%- column.pname %> (<%- column.domain %>)
<% } %>

<%# 全テーブル一覧 %>
<% for (const t of tables) { %>
  <%- t.pname %>
<% } %>

kbn/error/struct/interfaceテンプレート

<%# 全区分値 %>
<% kbns.forEach((kbn) => { %>
  <%- kbn.lname %> (<%- kbn.code %>)
  <% kbn.values.forEach((v) => { %>
    <%- v.pname %>: <%- v.code %>
  <% }) %>
<% }) %>

lodash拡張関数

テンプレート内では_でlodashが利用可能で、以下の追加関数が使えます：

<%- _.pluralize('user') %>      <%# → users %>
<%- _.singularize('users') %>   <%# → user %>
<%- _.camelize('user_name') %>  <%# → userName %>

また、fsとpathモジュールも利用可能です（外部ファイル読み込み等に使用）。

VSCode拡張機能

VSCode拡張機能では以下の機能が利用できます：

• .erd.jsonファイルのプレビュー表示
• JSONスキーマによる入力補完・バリデーション
• EDMファイル（.edm）のインポート/エクスポート
• テンプレートからのコード生成（コマンドパレット）

MCPサーバー

AI支援ツール向けのMCPサーバーを提供しています。Claude DesktopやCursor等で利用できます。

npx @uniquevision/erd-tool-mcp

開発

# 依存関係のインストール
yarn install

# 全パッケージのビルド
yarn build

# ウォッチモード（core + extension）
yarn watch

# テスト実行
yarn test

# Lint
yarn lint

# VSCode拡張のパッケージング
yarn package

ライセンス

MIT