cockroachdb-sql

CockroachDB SQL 技能

将自然语言问题转换为符合 CockroachDB 规范的 SQL 查询，并遵循 CockroachDB 最佳实践。用于模式设计、编写查询和优化查询。

如何使用此技能

1. 连接检测 — 已在调用技能时完成；请复用当前活动连接。

2. 解析自然语言意图

   • 确定操作类型（SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER 等）

3. 收集上下文

   • 检查对话中是否已有模式上下文
   • 如果已连接到数据库，查询现有模式：
     • 使用 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. 根据数据库验证（必须）

   • 连接到数据库时，始终对每条生成的 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 示例和模式