---
title: "CockroachDB SQL: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/cockroachlabs-cockroachdb-sql/
description: "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."
---

# CockroachDB SQL: review, setup & limitations · Undominated.ai

> 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.

[← Explore all skills](/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.

 [See setup guidance ↓](#setup)[Original source ↗](https://www.cockroachlabs.com/docs/)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 9 linked sources
 Publisher Cockroach Labs
 Licence [Apache-2.0 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/LICENSE)
 Revision e14e86d23ce8
 [Read what was—and wasn’t—checked ↓](#review)

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

 [Cockroach Labs · upstream description ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md) Our analysis follows below.

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.

### A good fit for

 - Turn a natural-language request into a CockroachDB SELECT, INSERT, UPDATE, DELETE, CREATE or ALTER statement
- Design a table with a UUID primary key and secondary indexes instead of a sequential key
- Check generated SQL with EXPLAIN against a connected cluster before using it
- Rewrite OFFSET pagination as keyset pagination, or batch writes with UPSERT and UNNEST

### Weigh up before choosing

 - The skill directory skills/cockroachdb-query-and-schema-design/cockroachdb-sql last changed in a commit dated 2026-07-22, which is also the date of the pinned revision.
- Without a database connection the skill only generates SQL and connection instructions; EXPLAIN validation needs a connected cluster, reached through a postgresql:// string in the prompt, COCKROACH_URL or a cockroach-cloud MCP server.
- The rule files it applies include statements that drop data or change access and cluster settings: DROP TABLE IF EXISTS users, orders, products CASCADE in 01-schema-design.md, and DROP DATABASE IF EXISTS mydb CASCADE, CREATE USER username WITH PASSWORD, GRANT ALL ON DATABASE and SET CLUSTER SETTING in 05-operational.md.
- They also include statements that send data off the cluster: BACKUP … INTO 's3://bucket/backup' and CREATE CHANGEFEED … INTO 'kafka://…', 's3://…' or 'webhook-https://…' in 05-operational.md, whose backup and changefeed sections are headed Enterprise; a changefeed into Kafka in 04-optimization.md; and EXPORT INTO CSV in 03-query-patterns.md.
- The printed install lines add skills from the whole repository, which holds 34 SKILL.md files at this revision; neither README.md nor docs/installation.md prints a line that selects cockroachdb-sql.
- LICENSE is the Apache License 2.0 text with the appendix 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 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/README.md)
 - 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.
- 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.
- 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

### Compatibility

Claude Code · Cursor · Windsurf · Cline · OpenHands · Roo Code · GitHub Copilot

### Implementation

SQL

### Runs generated SQL on the connected cluster

 - Reads a postgresql:// connection string from the prompt or the COCKROACH_URL environment variable (`echo $COCKROACH_URL`), or uses a cockroach-cloud MCP server when one is available.
- Runs SQL with `cockroach sql --url "<provided-url>" -e "SQL"` or `cockroach sql --url $COCKROACH_URL -e "SQL"`, including SHOW TABLES, SHOW CREATE TABLE and EXPLAIN on every generated query.
- Its frontmatter asks for SELECT, INSERT, UPDATE, DELETE or admin privilege on the target database and tables when connected; operation types include INSERT, UPDATE, DELETE, CREATE and ALTER.
- When optimizing, it tells the agent to execute each step and report the outcome.

### Cost model

Apache-2.0 skill text. The files read do not state a fee for the skill or for a CockroachDB cluster.

04 / FOLLOW THE EVIDENCE

## The source trail.

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

 - [cockroachdb-sql SKILL.md at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md) Checked 2026-10-21 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
- [Repository README at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/README.md) Checked 2026-10-21 https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/README.md Supports: install, compatibility, homepage, whySelected, limitations
- [Installation guide at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/docs/installation.md) Checked 2026-10-21 https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/docs/installation.md Supports: install, compatibility, limitations, review.findings
- [00-fundamental-principles.md at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md) Checked 2026-10-21 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
- [05-operational.md at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md) Checked 2026-10-21 https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md Supports: limitations
- [Apache-2.0 LICENSE at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/LICENSE) Checked 2026-10-21 https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/LICENSE Supports: license, limitations, whySelected
- [01-schema-design.md at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md) Checked 2026-10-21 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
- [03-query-patterns.md at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md) Checked 2026-10-21 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
- [04-optimization.md at e14e86d2 ↗](https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md) Checked 2026-10-21 https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md Supports: limitations

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Postgres ↗ Timescale's postgres skill from pg-aiguide: a dispatcher that sends the agent to nine reference guides for schema exploration, table design, pgvector and hybrid search, TimescaleDB hypertables and schema migrations.](/skills/timescale-postgres/)[### dbt Documentation Maintenance ↗ Audits descriptions in a dbt manifest and drafts missing model or column documentation in the project’s existing style.](/skills/dbt-labs-maintaining-dbt-documentation/)[### DuckDB read file ↗ DuckDB's read-file skill: one DuckDB CLI command that picks a reader by file extension and returns a file's schema, row count and first 20 rows, for local paths or HTTPS, S3, GCS and Azure URLs.](/skills/duckdb-read-file/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
