DB2TOON MCP

db2toon

データベーススキーマをToonスキーマ定義形式に変換するCLIツールです。

概要

db2toonはデータベースに接続し、スキーマ情報（テーブル、カラム、型、制約、インデックス、ルーチン、トリガー、サンプル）を抽出して、データベース設計のドキュメント化や可視化に使える、人間が読みやすいToon形式に変換します。PostgreSQL、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、Microsoft SQL Server、Oracleに対応しています。pg2toonはPostgreSQL互換コマンドとして引き続き利用できます。

機能

• スキーマ抽出：PostgreSQL、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、Microsoft SQL Server、Oracleからテーブル、カラム、メタデータを自動的に抽出します
• 型の正規化：PostgreSQLの型を簡略化します（例：character varying → varchar）
• リレーションシップのマッピング：外部キー制約をインライン参照または複数カラム参照に変換します
• コメントの保持：データベースで公開されているコメントを含めます。SQLiteにはカタログコメントがありません
• インデックスのドキュメント化：データベースのインデックスを抽出してドキュメント化します
• データベースオブジェクト：対応する列挙型、型、シーケンス、シノニム、トリガー、ルーチン、拡張機能、マテリアライズドビュー、パッケージなどのベンダー固有オブジェクトを、明示的なTOONセクションに保持します
• クロスプラットフォーム：Linux、macOS、Windows（amd64およびarm64）向けにCGOなしでビルドできます
• DBMLアダプター：DBMLファイル（または標準入力）を同じTOON形式に変換します
• ローカルMCP：読み取り専用のSQLデータベースとプレーンテキストのSQLダンプからスキーマを抽出し、MCPクライアント向けにコンパクトなTOON形式に変換します。

インストール

ソースから

git clone https://github.com/kamil5b/db2toon.git
cd db2toon
CGO_ENABLED=0 go build -o output/db2toon ./cmd/db2toon
CGO_ENABLED=0 go build -o output/pg2toon ./cmd/pg2toon
CGO_ENABLED=0 go build -o output/dbml2toon ./cmd/dbml2toon

リリースから

お使いのプラットフォーム向けのビルド済みバイナリをリリースページからダウンロードしてください。

Goパッケージ

コマンドを実行せずに正規のスキーマモデルを使用したい場合に備えて、このモジュールでは公開Go APIも提供しています。

import (
    "context"
    "os"

    "github.com/kamil5b/db2toon"
)

func extract() error {
    db, err := db2toon.Extract(context.Background(), db2toon.Request{
        Dialect: "postgres",
        Dump:    "./schema.sql",
        Options: db2toon.Options{ExampleSample: 2},
    })
    if err != nil {
        return err
    }
    return db2toon.Encode(os.Stdout, db)
}

Request.DBまたはRequest.Dumpのどちらか一方だけを設定してください。ダンプの内容はオフラインで解析され、実行されることはありません。公開APIは*schema.Databaseを返すため、呼び出し側でエンコードする前にモデルを調査または変換できます。

使い方

LLMツールとの連携

MCP互換のstdioサーバーをビルドして実行します。

CGO_ENABLED=0 go build -o output/db2toon-mcp ./cmd/db2toon-mcp
./output/db2toon-mcp

サーバーはdb2toon.extract_schemaを公開します。必須引数はdialect（postgres、sqlite、duckdb、mysql、mariadb、cockroachdb、mssql、sqlserver、またはoracle）です。dbまたはdumpのどちらか一方だけを指定してください。任意の抽出設定はoptionsオブジェクトで指定します。ダンプファイルはオフラインで解析され、実行されることはありません。このツールは読み取り専用で、デフォルトのタイムアウトは30秒、応答サイズの上限は4 MiBです。必要に応じて、options.timeoutとoptions.max_output_bytesでより低い上限を設定してください。接続文字列がツールのエラーや結果に含まれることはありません。

基本的な使い方

./db2toon postgres -db "postgresql://user:password@localhost/dbname"

# SQLite database file
./db2toon sqlite -db ./schema.db

# Plain-text SQL dump
./db2toon postgres -dump ./schema.sql
./db2toon sqlite -dump ./schema.sql
./db2toon mysql -dump ./schema.sql
./db2toon mssql -dump ./schema.sql
./db2toon oracle -dump ./schema.sql

# DuckDB database file (requires libduckdb at runtime)
./db2toon duckdb -db ./analytics.duckdb

# Microsoft SQL Server (defaults to dbo)
./db2toon mssql -db 'sqlserver://sa:password@localhost:1433?database=app&encrypt=disable'

# Oracle Database; the current schema is used unless -schema/-schemas is set.
# go-ora accepts an EZConnect-style URL.
./db2toon oracle -db 'oracle://app:password@localhost:1521/FREEPDB1'

# Compatibility command; PostgreSQL is selected automatically.
./pg2toon -db "postgresql://user:password@localhost/dbname"

# Convert DBML, either from a file or standard input.
./dbml2toon schema.dbml
cat schema.dbml | ./dbml2toon -out schema.toon

ファイルに保存

./db2toon postgres -db "postgresql://user:password@localhost/dbname" -out schema.toon

PostgreSQLの各テーブルから、安定した順序と再現可能なサンプルシードを使って、最大2行のサンプルをTOON出力に含めます。

./db2toon postgres -db "postgresql://user:password@localhost/dbname" \
  -example-sample=2 -example-sample-ordered=true -seed=42

デフォルトの-example-sample=0では、@exampleセクションは省略されます。

SQLiteとDuckDBも-example-sampleに対応していますが、現在は単純なLIMITクエリを使用します。-example-sample-orderedと-seedが現在有効なのはPostgreSQLのみです。

複数のスキーマを選択し、パーティション分割されたテーブルを含め、デフォルトの30秒の処理タイムアウトを変更するには、次のようにします。

./db2toon postgres -db "$DATABASE_URL" -schema audit
./db2toon postgres -db "$DATABASE_URL" -schemas public,audit -include-partitioned -timeout 1m

# SQLite and DuckDB default to the `main` schema. SQL Server defaults to `dbo`.
# Oracle defaults to the session's CURRENT_SCHEMA.
./db2toon sqlite -db ./schema.db -schema main
./db2toon duckdb -db ./analytics.duckdb -schema analytics
./db2toon oracle -db 'oracle://app:password@localhost:1521/FREEPDB1' -schema APP

フラグ

• -db string：データベース接続 URL またはローカルデータベースパス。-dump とは併用できません
• -dump string：プレーンテキストの SQL ダンプパス。-db とは併用できません
• dialect：db2toon では postgres、sqlite、duckdb、mysql、mariadb、cockroachdb、mssql、sqlserver、または oracle を指定します。pg2toon は常に PostgreSQL を使用します
• -out string：出力ファイルパス（任意。デフォルトは標準出力）
• -schema string：抽出する単一のスキーマ（デフォルトは PostgreSQL では public、SQLite／DuckDB では main、SQL Server では dbo、Oracle ではセッションの CURRENT_SCHEMA）
• -schemas string：抽出するスキーマをカンマ区切りで指定します。-schema とは併用できません
• -include-partitioned：PostgreSQL のパーティションテーブルを含めます
• -include-views：サポート対象のビューを含めます
• -exclude-tables string：完全に除外するテーブルをカンマ区切りで指定します。table または schema.table を指定できます
• -exclude-example-tables string：@example のサンプリング対象から除外するテーブルをカンマ区切りで指定します
• -exclude-example-fields string：例から除外する、スキーマ修飾付きフィールドをカンマ区切りで指定します（例：public.users.password_hash）
• -example-sample int：テーブルごとに含めるサンプル行数（デフォルトは 0）
• -example-sample-ordered：PostgreSQL で決定的な順序を使ってサンプル行を選択します（デフォルトは false）
• -seed int：再現可能な PostgreSQL サンプル選択のシード値（デフォルトは 0。現在、SQLite／DuckDB では無視されます）
• -timeout duration：接続および抽出のタイムアウト（デフォルトは 30s）

ダンプモードは、PostgreSQL、SQLite、DuckDB、 MySQL／MariaDB、CockroachDB、SQL Server、Oracle のプレーンテキスト SQL エクスポートに対応しています。一般的なテーブル、カラム、制約、 インデックス、コメント、および上限付きの INSERT 例は、ダンプを実行せずに解析されます。PostgreSQL では、ドル引用符で囲まれたルーチン本体を含む、ネイティブの列挙型、シーケンス、ビュー、関数、 プロシージャ、トリガーが保持されます。MySQL／MariaDB では、 DELIMITER を使ったルーチンおよびトリガーの宣言に対応しています。SQL Server と Oracle では、サポート対象のビュー、関数、プロシージャ、トリガー、シーケンス、 型、シノニム、および一部のベンダーオブジェクトが保持されます。複雑なベンダー固有の PL/SQL／ T-SQL 本体は、利用可能なステートメントテキストとして保持されます。サポート対象外の宣言は実行されず、無視されます。

出力形式

Toon 形式では、すっきりとした読みやすいスキーマ定義を提供します。

@database app {dialect=postgres}

[users]
# User accounts table

  id int {pk}
  email varchar {req}
  name varchar
  created_at timestamptz {req}

@indices
  idx_email: ON users USING btree (email)

@example[2]{id,email,name,created_at}:
  1,[email protected],Alice,2026-01-10T09:00:00Z
  2,[email protected],Bob,2026-01-11T10:30:00Z

[posts]
# Blog posts

  id int {pk}
  user_id int {req} -> users(id)
  title varchar {req}
  content text
  published_at timestamptz

[comments]
# Post comments

  id int {pk}
  post_id int {req} -> posts(id)
  user_id int {req} -> users(id)
  content text {req}
  created_at timestamptz {req}

形式の要素

• @database name {dialect=dialect}：ソースデータベースのメタデータです。ライブ接続では接続文字列から名前を取得し、ダンプモードでは拡張子を除いたダンプファイル名を使用します
• [TableName]：テーブル定義
• # comment：テーブルまたはカラムのコメント
• name type {tags}：任意のタグを含むカラム定義
  • {pk}：主キー
  • {req}：必須（NOT NULL）
  • 複数のタグ：{pk,req}
• -> table(column)：外部キー参照（単一カラムの場合はインライン）
• @indices：データベースインデックスのセクション
• @enum：列挙型の値
• @type：ユーザー定義型のメタデータ
• @sequence：シーケンスの設定
• @synonym：代替オブジェクト名
• @routine：関数またはプロシージャのメタデータと、利用可能な場合は定義
• @triggers：テーブルトリガーのメタデータ
• @objects：ベンダー固有のスキーマオブジェクト。Oracle のマテリアライズド ビュー、パッケージ、パーティションテーブル、スケジューラージョブ、データベースリンクなどが含まれます
• @example[n]{columns}:：テーブルからサンプリングした最大 n 行
• // comment：インラインのカラムコメント

Oracle のカバレッジ

Oracle の抽出では、ユーザーが参照可能な ALL_* カタログビューを使用するため、出力は接続アカウントが検査できるオブジェクトに限られます。テーブル、ビュー、列とコメント、主キー／一意キー／外部キー／チェック制約、独立したインデックス、トリガー、スタンドアロンの関数とプロシージャ、ユーザーシーケンス、オブジェクト型、シノニム、マテリアライズドビュー、パッケージ／パッケージ本体、パーティション化テーブルのマーカー、スケジューラジョブ、データベースリンクに対応しています。Oracle が生成する ID 用シーケンスと、システムが生成する NOT NULL チェックは、情報がすでに列モデルに反映されているため省略されます。

パッケージ／型のソース本体、マテリアライズドビューのリフレッシュ設定、詳細なパーティション定義、権限／ロール、VPD ポリシー、表領域／ストレージの詳細、特殊な空間／ドメインインデックスのオプション、Oracle SQL ダンプの解析は、まだ標準モデルに反映されていません。

Microsoft SQL Server のカバレッジ

Microsoft SQL Server の抽出では sys.* カタログビューを使用し、-schema または -schemas が指定されない場合、既定で dbo スキーマを使用します。テーブルとビュー、列と MS_Description コメント、既定値、ID／計算列、主キー／一意キー／外部キー／チェック制約、独立したインデックス、トリガー、関数／プロシージャ、エイリアス型／テーブル型、シーケンス、シノニム、サンプル行に対応しています。ビュー定義とベンダー固有のスキーマオブジェクトは、該当する場合、TOON オブジェクトセクションに出力されます。

SQL Server のダンプ解析には対応していません。現在のモデルでは、パーティション関数／スキーム、ファイルグループ、テンポラルテーブルまたはメモリ最適化テーブルの設定、グラフテーブル、フルテキスト／空間／XML インデックスの内部情報、権限、説明以外の拡張プロパティ、Agent ジョブ、サーバーレベルのオブジェクトもまだ反映されていません。

要件

• Go 1.26.0 以降
• PostgreSQL 9.4 以降（JSON 集約関数用）、SQLite、DuckDB、MySQL/MariaDB、CockroachDB、Microsoft SQL Server 2022 以降、または Oracle Database
• 有効なデータベース接続文字列またはローカルデータベースパス
• DuckDB では、実行時に互換性のある libduckdb 共有ライブラリも必要です
• Oracle では純粋な Go 製の go-ora ドライバーを使用し、Oracle Instant Client や CGO は不要です

ライセンス

MIT