Claude Media
Claude CodeにCockroachDBプラグインを入れてスキーマ設計とクエリ診断を任せる
Claude CodeClaude連携チュートリアル

Claude CodeにCockroachDBプラグインを入れてスキーマ設計とクエリ診断を任せる

cockroachdbプラグインの入れ方、読み取り専用の既定、SQL検査フック、DBA・開発者・運用担当の3エージェントの使い分けまでを、スキーマ設計とクエリ診断の流れに沿って説明します。

読了目安 約13分

Claude CodeでCockroachDBを扱うなら、Cockroach Labsが公開している cockroachdb プラグインを入れるのが近道です。MCPサーバー、3種類のエージェント、スキル、SQLを検査するフックが1つにまとまっています。

特徴は、既定が読み取り専用で、書き込みには明示的な設定が要る点です。この記事では、導入から接続設定、スキーマ設計とクエリ診断の頼み方、書き込みを許す場合の注意までを順に説明します。

cockroachdbプラグインに何が入っているか

プラグインは、CockroachDBクラスターに接続して「スキーマを調べる、SQLを書く、遅いクエリを調べる、クラスターを管理する」作業をClaude Codeの中で進めるためのものです。構成要素は4つあります。

構成

プラグインの構成要素

  • MCPバックエンド

    自前のクラスター向けのMCP Toolbox(標準入出力)と、CockroachDB Cloudが提供するマネージドMCPサーバーの2本が最初から有効です。

  • エージェント

    cockroachdb-dba、cockroachdb-developer、cockroachdb-operator の3種類です。

  • スキル

    クエリとスキーマ設計、観測と診断、セキュリティ、移行、運用などの領域に分かれています。

  • フック

    SQLの実行前と、ファイルの書き込み・編集後に走る2つの検査です。

マーケットプレイスの説明文は「3つの中核MCPツール」「22以上のスキル」「9つの運用領域」と書いています。リポジトリのREADMEはスキルを領域ごとの例で示す形です。件数は版によって変わりうるため、手元で何が入ったかは導入後に確認するのが確実です。

導入前に揃えるもの

スキル、エージェント、フックは追加の準備なしで動きます。MCPサーバーはそれぞれ前提が違い、ここで詰まりやすくなります。

MCPサーバー必要なもの
cockroachdb-toolbox必要なものPATH上のMCP Toolbox for Databases v1.0.0以降と、到達できるクラスター
cockroachdb-cloud必要なものCockroachDB Cloudのアカウント

Toolboxはセッション開始時に接続します。クラスターに届かない環境では、このサーバーは起動に失敗します。クラスターを持たない人は、先に使わないサーバーを止めておきます。

macOSやLinuxでは、Toolboxを次のように入れます。

brew install mcp-toolbox
toolbox --version

Windowsはtoolbox.exeをPATHの通ったフォルダーに置きます。PATHを変えたあとはClaude Codeを再起動します。

プラグインを入れる

マーケットプレイス経由なら、Claude Codeの中で次を実行します。

/plugin install cockroachdb@claude-plugins-official

マーケットプレイスのページには、シェルから claude plugin install cockroachdb で入れる書き方もあります。READMEにはCockroach Labs自身のマーケットプレイスから入れる手順も載っています。

/plugin marketplace add cockroachdb/claude-plugin
/plugin install cockroachdb@cockroachdb-claude-plugin

プラグインの仕組み自体はClaude Codeプラグイン完全ガイドにまとめています。同梱されたMCPサーバーのツール名がどう付くかはプラグイン同梱MCPサーバーの解説が詳しく扱っています。

接続先を環境変数で渡す

自前のクラスターに繋ぐcockroachdb-toolboxは、接続情報を環境変数から読みます。どれも省略でき、未設定なら既定値が使われます。

環境変数既定値
COCKROACHDB_HOST既定値localhost
COCKROACHDB_PORT既定値26257
COCKROACHDB_USER既定値root
COCKROACHDB_PASSWORD既定値空
COCKROACHDB_DATABASE既定値defaultdb
COCKROACHDB_SSLMODE既定値require

SSLモードは、ローカルの --insecure クラスターなら disable、本番なら verify-full を使う想定です。設定はClaude Codeを起動する環境に入れます。

export COCKROACHDB_HOST="your-cluster-host"
export COCKROACHDB_PORT="26257"
export COCKROACHDB_USER="your-user"
export COCKROACHDB_PASSWORD="your-password"
export COCKROACHDB_DATABASE="your-database"
export COCKROACHDB_SSLMODE="verify-full"

パスワードをシェルの設定ファイルに平文で置く形になるので、本番のクラスターに繋ぐ場合は、書き込み権限の扱い(次の節)と合わせて検討してください。

CockroachDB Cloudを使う場合は、Claude Code内で /mcp を開き、cockroachdb-cloud を選んでサインインします。同意画面では読み取り、書き込み、またはその両方の権限を選べます。何も指定しなければ、あなたのCloudロールで届くすべてのクラスターに接続できます。1つに絞るには、そのクラスターのIDを COCKROACHDB_CLUSTER_ID に入れます。

使わない側のサーバーは /mcp から無効化できます。Claude Codeは両方を毎回起動するため、片方しか使わないなら止めておきます。無効化の選択はプロジェクトごとに記憶されます。

既定は読み取り専用: 書き込みを許す前に知ること

Toolboxはread-onlyモードで動きます。SELECT、SHOW、EXPLAINは通り、書き込みとスキーマ変更は拒否されます。マーケットプレイスの説明文には「データを管理できる」とありますが、標準構成のToolboxでは変更系は動きません。

書き込みを許す方法は2通りあります。

  • Toolboxの tools.yaml を自分用に複製して enableWriteMode: true を設定し、自分のMCPサーバーとして登録する。同時にプラグイン側のcockroachdb-toolboxは止める
  • CockroachDB Cloudの同意画面で書き込み権限を付ける。書き込み系のツールとして create_database、create_table、insert_rows が挙がっている

用途で考えると、設計とクエリ診断だけなら、読み取り専用のままで足ります。スキーマ案をSQLとして出させ、適用は自分で行う運用です。

スキーマ設計を頼む

読み取り専用でも、既存のスキーマを読ませる作業は成立します。cockroachdb-list-tables が列・型・制約を返すので、設計レビューの材料は揃います。

頼み方の例は次のとおりです。

このデータベースのテーブルを一覧し、それぞれのスキーマを説明して。
そのうえで、書き込みが一点に集中しそうなホットスポットの危険を指摘して。

マーケットプレイスの説明文は、同種の指示として「テーブルを一覧してスキーマを説明する」「最適化したクエリを書く」「書き込みホットスポットの危険がないかスキーマを見る」「マルチリージョン構成を計画する」を挙げています。

フックは SERIAL の使用に警告を出します。連番の主キーを避けたいという設計上の勘所を、書き込み前の段階で拾う仕組みです。設計の依頼は、まずDBAエージェントに投げます。

cockroachdb-dbaエージェントに、このスキーマをレビューしてもらって

エージェントはタスクの文脈から自動で呼ばれます。名前を挙げて直接指名することもできます。

クエリ診断を頼む

遅いクエリの調査には、cockroachdb-execute-sql でEXPLAINを流せます。EXPLAINは読み取り専用モードでも通ります。

次のクエリが遅い。EXPLAINの実行計画を読んで、足りないインデックスを提案して。
SELECT ... （対象のクエリ）

Cloud側のMCPには、explain_query と show_running_queries があります。いま実行中のクエリを確認する用途です。スキル側には、文の指紋(statement fingerprint)ごとの集計を見るもの、実行中のSQL活動を切り分けるものが例として載っています。

エージェントに丸ごと任せたいなら、次のように頼みます。

cockroachdb-dbaエージェントで、このクエリが遅い理由を診断して

提案されたインデックスは、そのまま実行しないでください。読み取り専用のToolboxは作成を拒否しますが、仮に書き込みを許していても、本番への適用は変更管理の手順に載せるものです。

3つのエージェントの使い分け

エージェント想定する担当
cockroachdb-dba想定する担当性能チューニング、スキーマレビュー、クラスター診断
cockroachdb-developer想定する担当ORMの設定、リトライ処理、トランザクションの書き方
cockroachdb-operator想定する担当クラスター運用、監視、バックアップ、スケール、障害対応

アプリケーションの実装中なら、developerが担当です。リトライ処理の欠如は、後述のフックの検査対象でもあります。

2つのフックが止めるもの

フックはPython 3のスクリプトで、外部ライブラリを使いません。

フック走るタイミング動作
validate-sql走るタイミングSQL実行の前動作DROP DATABASE と TRUNCATE をブロックし、SERIAL と複数DDLのトランザクションに警告する
check-sql-files走るタイミングファイルのWrite/Edit後動作SQLやコード内の SERIAL、SELECT *、リトライ欠如を検出する

ここで見落としやすい点が2つあります。

落とし穴

フックはToolboxにだけ効く

validate-sqlがかかるのは、同梱のToolboxサーバーへのSQLです。自分で足した別のMCPサーバー(READMEが紹介するcockroachdb-mcp-serverなど)にはこのフックが働かず、そのサーバー自身の保護機能に頼ることになります。

落とし穴

Windowsではpython3がないとフックが黙って動かない

フックは python3 を呼びます。python.orgのインストーラーは python.exe と py ランチャーを作りますが python3.exe は作りません。その環境では、フックは編集を妨げないまま何もせず終わります。Microsoft StoreのPythonを入れるか、python3 の別名を用意すると有効になります。

フック全般の仕組みはClaude Code Hooks完全ガイドで扱っています。

公式サーバー以外のバックエンドを足す

READMEは、既定の2本に加えて自分で足せる接続先を紹介しています。

  • ToolboxのHTTP版: 複数人で使う場合に向きます。toolbox --config tools.yaml --address 0.0.0.0 --port 5000 で起動し、claude mcp add --transport http で登録します
  • cockroachdb-mcp-server: Cockroach Labs自身のMCPサーバーで、自前のクラスター向けです。標準では list_databases、list_tables、get_table_schema、select_query、explain_query などの読み取り系だけを登録します。CRDB_MCP_ENABLE_WRITE_QUERIES=true で書き込み系が加わり、WHERE句のないUPDATEとDELETEは拒否されます
  • ccloud CLI: クラスターの作成、接続文字列の取得、バックアップ、ディザスタリカバリ、ネットワーク設定などを担うコマンドラインツールです。MCP経由ではなくシェルから直接呼ばれ、どのコマンドも -o json で構造化出力を返します

cockroachdb-mcp-serverはmacOS用のビルド済みバイナリがなく、go install かDockerで入れます。Goは1.26以降が必要です。

動かないときの切り分け

動作が不安定なとき、最初に疑うのは次の3点です。

切り分け

接続できないときの確認順

  1. Qtoolbox --version が通るか?
    答えがいいえのとき

    MCP Toolboxが入っていません。PATHを確認し、Claude Codeを再起動します。

    答えがはい
  2. QCOCKROACHDB_ 系の環境変数が、Claude Codeを起動した環境に入っているか?
    答えがいいえのとき

    シェルの設定ファイルを変えたなら、起動し直します。ホスト名とポートの誤りでも、Toolboxは初期化の途中で止まります。

    答えがはい
  3. Qクラスターに自分の端末から届くか?
    答えがいいえのとき

    ファイアウォールやネットワーク許可リストを疑います。届かない環境では、cockroachdb-toolboxを無効化して、Cloud側だけを使う手もあります。

    答えがはい

接続できた

cockroachdb-list-schemas に相当する質問から試します。

Toolboxを単体で起動すると、クラスターに届かないあいだ「Fetching tools...」のまま止まります。READMEが挙げる症状です。

導入後の使い方の目安

最後に、このプラグインを使う順序の目安を挙げます。

  1. 読み取り専用のまま、既存スキーマの一覧と説明を頼む
  2. 気になるクエリのEXPLAINを流させ、インデックス案をSQL文として出させる
  3. 案を人が確認し、適用は自分のマイグレーション手順で行う
  4. 実装中はdeveloperエージェントにリトライとトランザクションの書き方を見てもらう
  5. 書き込みを許す必要が出たら、専用のユーザーと権限を用意した別のサーバー設定に分ける

5番目の専用ユーザーは、READMEの接続例でも ai_agent のような名前が使われています。AIエージェント用のロールを分けておくと、操作の記録も追いやすくなります。

まとめ

cockroachdbプラグインの強みは、分散SQLに特有の落とし穴(連番の主キー、リトライ、複数DDL)を、スキルとフックの両面で拾ってくれる点です。標準のToolboxは読み取り専用なので、設計レビューとクエリ診断から始めるのが無理のない入り方です。書き込みを許す段階では、フックが効く範囲と効かない範囲を先に確かめてください。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →