cockroachdb-sql

CockroachDB SQL スキル

自然言語の質問を、CockroachDB のベストプラクティスに従った CockroachDB 準拠の SQL クエリに変換します。スキーマの設計、クエリの作成、クエリの最適化に使用します。

このスキルの適用方法

1. 接続の検出 — スキルの呼び出し時にすでに実行されています。有効な接続を再利用します。

2. 自然言語の意図を解析

   • 操作の種類（SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER など）を特定します。

3. コンテキストの収集

   • 会話内に既存のスキーマコンテキストがあるか確認します
   • DB に接続している場合は、既存のスキーマを照会します：
     • 既存のテーブルを確認するには SHOW TABLES;
     • 既存の構造を確認するには SHOW CREATE TABLE table_name;
   • 必要に応じて、確認の質問をします：
     • 指定されていない場合はテーブル構造
     • カラムのデータ型
     • インデックスの要件
     • マルチリージョンの要件
     • パフォーマンス特性

4. CockroachDB のルールを適用

   • references/cockroachdb-rules/ のルールを参照します
   • CockroachDB のベストプラクティスに準拠していることを確認します
   • 操作に基づいてルールのカテゴリを判断し、該当するルールを適用します：
     • 00-fundamental-principles.md - これらを必ず最初に適用します
     • 01-schema-design.md - テーブルの作成と構造
     • 02-dml-operations.md - データの変更
     • 03-query-patterns.md - クエリの構築
     • 04-optimization.md - パフォーマンス、最適化、アンチパターン
     • 05-operational.md - 管理とメンテナンス
   • 04-optimization.md のアンチパターンに照らして検証します

5. DB に対して検証（必須）

   • DB に接続している場合、生成したすべての SQL クエリで必ず EXPLAIN を実行します。
   • EXPLAIN が解析エラーまたは構文エラーを返した場合は、クエリを修正し、成功するまで EXPLAIN を再実行します。
   • EXPLAIN の出力を回答に含めます。

応答の動作

初回の応答

スキルが呼び出されたとき：

1. クエリを適切なクラスターに対して実行できるよう、利用可能な接続を確認します：

   • プロンプトに接続文字列（postgresql://...）が指定されているか確認します。
     • 指定されている場合は、cockroach sql --url "<provided-url>" -e "SQL" を使用してクエリを実行します。psql は使用しないでください。
   • それ以外の場合は、COCKROACH_URL 環境変数を確認します（echo $COCKROACH_URL）。
     • 設定されている場合は、cockroach sql --url $COCKROACH_URL -e "SQL" を使用してクエリを実行します。psql は使用しないでください。
   • それ以外の場合は、cockroach-cloud MCP サーバーが利用可能か確認します。
   • いずれも利用できない場合、または使用するクラスターが不明な場合は、何も実行する前にユーザーに確認します。

2. CockroachDB にのみ焦点を当てます

3. 「データベース変換」ではなく、「自然言語から CockroachDB SQL への変換」を強調します

4. ルールが PostgreSQL との互換性に由来する場合でも、CockroachDB 固有の構文を提示します

出力形式

• 生成した SQL を説明コメントとともに表示します
• 使用した CockroachDB 固有の機能を列挙します
• パフォーマンスに関する考慮事項を含めます
• 最適化する場合は、各ステップで次の内容を示します：1- ステップの目的を説明します。2- ステップを実行し、結果を報告します。3- すべての調査結果と実行した操作をまとめます。
• ルールを含め、使用した参照資料を提示します

例

スキーマ設計 — UUID 主キー（ホットスポットを回避）

CREATE TABLE orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  customer_id UUID NOT NULL,
  status STRING NOT NULL DEFAULT 'pending',
  total DECIMAL(10,2) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  INDEX idx_orders_customer (customer_id),
  INDEX idx_orders_status_created (status, created_at DESC)
);

UNNEST を使用したバッチ UPSERT

UPSERT INTO inventory (sku, warehouse, quantity, updated_at)
SELECT * FROM UNNEST(
  ARRAY['SKU-001', 'SKU-002', 'SKU-003']::STRING[],
  ARRAY['us-east', 'us-east', 'us-west']::STRING[],
  ARRAY[100, 250, 75]::INT[],
  ARRAY[now(), now(), now()]::TIMESTAMPTZ[]
);

キーセットページネーション（OFFSET を回避）

前のページの最後の (created_at, id) をカーソルとして使用します。アプリケーションコードではこれらはバインドパラメーターです。ここに示したリテラルはプレースホルダーです。

SELECT id, customer_id, created_at
FROM orders
WHERE (created_at, id) > ('2025-01-01'::TIMESTAMPTZ, '00000000-0000-0000-0000-000000000000'::UUID)
ORDER BY created_at, id
LIMIT 50;

関連ドキュメント

• references/cockroachdb-rules/ - CockroachDB SQL のルール
• references/EXAMPLES.md - SQL の例とパターン