← Explore all skills

DATABASES / Cockroach Labs

CockroachDB SQL

Cockroach Labs skill that turns a natural-language request into CockroachDB SQL, applies the relevant rule files with 00-fundamental-principles.md first, and tells the agent to run EXPLAIN on every generated query when a cluster connection is available.

“Converts natural language questions into CockroachDB-compliant SQL queries, following CockroachDB best practices. Use it for schema design, writing queries and optimizing query.”

01 / THE REASONING

Why this made the selection.

  • SKILL.md marks plan validation as mandatory: when connected, it tells the agent to run EXPLAIN on every generated query, fix and re-run it after a parsing or syntax error, and include the EXPLAIN output in the response.
  • It applies the relevant rule files under references/cockroachdb-rules/ for each operation, 00-fundamental-principles.md first; that file requires a PRIMARY KEY in every table, prefers UUID primary keys and says to avoid sequential IDs that cause hotspots.
  • Cockroach Labs maintains the repository, per the README footer, and LICENSE carries the line Copyright 2026 Cockroach Labs Inc.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
  • README.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
  • docs/installation.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
  • skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
  • skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd: section headings and the statements quoted in limitations
  • skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md, 03-query-patterns.md and 04-optimization.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd: the statements quoted in limitations
  • LICENSE at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
  • Repository tree at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd: 34 SKILL.md files

Our findings

  • Connection detection checks a postgresql:// string in the prompt, then the COCKROACH_URL environment variable, then a cockroach-cloud MCP server; if none is available or the cluster is unclear, the agent is told to ask the user before running anything.
  • Queries run through `cockroach sql --url … -e "SQL"`, and SKILL.md says not to use psql.
  • Nothing in SKILL.md limits execution to read-only statements: its frontmatter asks for SELECT, INSERT, UPDATE, DELETE or admin privilege when connected, and the optimizing step says to execute each step and report the outcome.
  • docs/installation.md shows --skill only with reviewing-cluster-health and with '*'; no printed line names cockroachdb-sql.

Not established by this review

  • Not executed: it was not installed or run.
  • No SQL was generated, no EXPLAIN plan was produced and no cluster was connected.
  • references/EXAMPLES.md was not read, and rule files 01 to 04 were read only at the statements quoted in limitations.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Add a skill to your workflow.

Upstream setup instructions ↗
  1. README.md prints `npx skills add cockroachlabs/cockroachdb-skills` as its one-line installation. At this revision that line offers all 34 SKILL.md skills in the repository, not this skill alone.
  2. docs/installation.md says the interactive installer lets you select which skills to install; its non-interactive examples use `--skill '*'` and `--skill reviewing-cluster-health`. No printed line selects cockroachdb-sql.
  3. The manual options in docs/installation.md clone the repository and symlink or copy the whole skills/ directory into .claude/skills.

Before you start

  • Node.js 18+ for the npx installer, as docs/installation.md states
  • A connection for EXPLAIN validation: the cockroach CLI with a connection URL in the prompt or COCKROACH_URL, or a cockroach-cloud MCP server

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md

    Supports: upstreamDescription, whySelected, bestFor, limitations, access, install.prerequisites, review.findings

  2. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/README.md

    Supports: install, compatibility, homepage, whySelected, limitations

  3. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/docs/installation.md

    Supports: install, compatibility, limitations, review.findings

  4. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md

    Supports: whySelected

  5. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md

    Supports: limitations

  6. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/LICENSE

    Supports: license, limitations, whySelected

  7. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md

    Supports: limitations

  8. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md

    Supports: limitations

  9. https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md

    Supports: limitations

Evidence & Ask