dbhub

DBHub データベースクエリガイド

DBHub の MCP サーバー経由でデータベースを操作する場合は、必ず探索してからクエリを実行するパターンに従ってください。スキーマを理解せずにいきなり SQL を実行するのが最もよくある間違いです。クエリの失敗、トークンの浪費、ユーザーの不満につながります。

利用可能なツール

DBHub では、デフォルトで 2 つの MCP ツールが提供され、オプトインで利用できるツールもあります。

ツール	目的
search_objects	データベース構造（スキーマ、テーブル、カラム、インデックス、プロシージャ、関数）を探索します
execute_sql	データベースに対して SQL 文を実行します
explain_sql（オプトイン）	クエリを実行せずに実行計画を表示します。ソースの設定で有効になっている場合にのみ利用できます
health_check（オプトイン）	接続プールの状態とバッファキャッシュのヒット率を報告します。ソースの設定で有効になっている場合にのみ利用できます。PostgreSQL、MySQL、MariaDB、SQL Server、Oracle のみ

複数のデータベースが設定されている場合、DBHub は各ソースに対して個別のツールを登録します（例：search_objects_prod_pg、execute_sql_staging_mysql）。対応する名前のツールを呼び出して、目的のデータベースを選択してください。

explain_sql が利用可能な場合（ツール一覧で確認してください）、クエリの効率性を推測するよりも、こちらを優先してください。文を実行しないため、書き込み可能なソースでも読み取り専用のソースでも、常に安全に呼び出せます。

health_check が利用可能で、クエリが遅い場合や接続が枯渇しているように見える場合は、原因を推測する前に呼び出してください。原因を推測するのではなく、接続プールとキャッシュヒットの実際の数値を報告します。

探索してからクエリを実行するワークフロー

データベースに関するすべてのタスクで、次の手順に従ってください。各ステップで対象を絞り込むため、不要な情報の読み込みにトークンを浪費することがありません。

ステップ 1：存在するスキーマを確認する

search_objects(object_type="schema", detail_level="names")

これで全体像を把握できます。ほとんどのデータベースには、プライマリスキーマ（例：PostgreSQL の public、SQL Server の dbo）と、無視してよいシステムスキーマがあります。

ステップ 2：関連するテーブルを見つける

スキーマがわかったら、そのテーブルを一覧表示します。

search_objects(object_type="table", schema="public", detail_level="names")

特定のものを探している場合は、パターンを使います。

search_objects(object_type="table", schema="public", pattern="%user%", detail_level="names")

pattern パラメーターでは SQL の LIKE 構文を使います。% は任意の文字列に一致し、_ は任意の 1 文字に一致します。

適切なテーブルを特定するために、行数、カラム数、テーブルコメントなどの詳細な情報が必要な場合は、代わりに detail_level="summary" を使います。

ステップ 3：テーブル構造を調べる

クエリを書く前に、カラムを把握してください。

search_objects(object_type="column", schema="public", table="users", detail_level="full")

カラム名、データ型、NULL 許容性、デフォルト値が返されます。正しい SQL を書くために必要な情報がすべて含まれています。

クエリのパフォーマンスや結合パターンを理解するには、インデックスも確認してください。

search_objects(object_type="index", schema="public", table="users", detail_level="full")

ステップ 4：クエリを書く、実行する

正確なテーブル名とカラム名がわかったので、正確な SQL を書きます。

execute_sql(sql="SELECT id, email, created_at FROM public.users WHERE created_at > '2024-01-01' ORDER BY created_at DESC")

段階的な情報開示：適切な詳細レベルの選択

detail_level パラメーターは、search_objects が返す情報量を制御します。まず最小限の情報から始め、必要な場合にのみ詳細を確認してください。これにより、応答が速くなり、トークンも効率的に使えます。

レベル	取得できる情報	使用する場面
names	オブジェクト名のみ	閲覧、適切なテーブルの検索
summary	名前とメタデータ（行数、カラム数、コメント）	類似したテーブルの選択、データ量の把握
full	完全な構造（型付きカラム、インデックス、プロシージャ定義）	クエリを書く前、リレーションシップの把握

目安： 広範な探索には names、対象の絞り込みには summary を使い、クエリ対象の特定テーブルに限って full を使います。

複数のデータベースを操作する

DBHub に複数のデータベースソースが設定されている場合、ソースごとに個別のツールインスタンスが登録されます。ツール名は {tool}_{source_id} のパターンに従います。

# Query the production PostgreSQL database
search_objects_prod_pg(object_type="table", schema="public", detail_level="names")
execute_sql_prod_pg(sql="SELECT count(*) FROM orders")

# Query the staging MySQL database
search_objects_staging_mysql(object_type="table", detail_level="names")
execute_sql_staging_mysql(sql="SELECT count(*) FROM orders")

単一データベース構成では、ツール名は接尾辞のない search_objects と execute_sql です。ユーザーが特定のデータベースや環境を指定した場合は、対応する名前のツールを呼び出してください。

特定のオブジェクトを検索する

search_objects ツールは、すべてのオブジェクトタイプを対象に検索できます。

# Find all tables with "order" in the name
search_objects(object_type="table", pattern="%order%", detail_level="names")

# Find columns named "email" across all tables
search_objects(object_type="column", pattern="email", detail_level="names")

# Find stored procedures matching a pattern
search_objects(object_type="procedure", schema="public", pattern="%report%", detail_level="summary")

# Find functions
search_objects(object_type="function", schema="public", detail_level="names")

よくあるパターン

「どのようなデータがありますか？」

1. スキーマを一覧表示 → summary の詳細度でテーブルを一覧表示 → 関連するテーブルを選択 → full の詳細度で確認

「データベースから X を取得してください」

1. X に関連するテーブルを検索 → 列を確認 → 対象を絞った SELECT を作成

「これらのテーブルはどのように関連していますか？」

1. 両方のテーブルを full の詳細度で確認（列とインデックスから外部キーと結合列を把握できます）

「この特定の SQL を実行してください」

ユーザーが正確な SQL を提示した場合は、そのまま実行できます。ただし、列またはテーブルのエラーで失敗した場合は、修正方法を推測せず、調査ワークフローに切り替えてください。

エラーからの復旧

クエリが失敗した場合：

• 不明なテーブル／列：候補を推測するのではなく、search_objects を使って正しい名前を探します
• スキーマエラー：まず利用可能なスキーマを一覧表示します。想定とは異なるスキーマにテーブルがある可能性があります
• 権限エラー：データベースが読み取り専用モードの可能性があります。SELECT 文のみ許可されているか確認します
• 複数のステートメント：execute_sql は、; で区切られた複数の SQL ステートメントをサポートしています

してはいけないこと

• **テーブル名や列名を推測しないでください。**必ず最初に search_objects で確認してください。誤った推測は余計な往復を招き、会話を混乱させます。
• **スキーマ全体を最初に出力しないでください。**段階的に情報を開示し、まず names から始め、実際にクエリするテーブルだけ full まで掘り下げます。
• **複数データベースの構成で誤ったツールを使わないでください。**ユーザーが特定のデータベースに言及した場合は、汎用の execute_sql ではなく、データベース固有のツールバリアント（例：execute_sql_prod_pg）を呼び出します。
• **失敗したクエリをやみくもに再試行しないでください。**SQL が失敗した場合は、再試行する前にスキーマを調べて原因を把握します。