setting-up-local-cluster

Downloads and starts a local CockroachDB cluster for development using the official binary. Use when a developer needs a local CockroachDB instance, when no cluster is available, or when setting up a new development environment.

Quality

83%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Setting Up a Local CockroachDB Cluster

Guides you through downloading, installing, and starting a local CockroachDB cluster for development. Uses the official binary -- no Docker or external runtime dependencies required.

When to Use This Skill

Developer asks to "set up CockroachDB" or "start a local database"
No CockroachDB cluster is reachable
Developer wants to build an app with CockroachDB from scratch
Setting up a new development environment

Prerequisites

macOS (Intel or Apple Silicon), Linux (Intel or ARM), or Windows (Intel)
curl or wget available for downloading the binary
~500 MB disk space per node
Ports 26257-26259 (SQL), 26357-26359 (RPC), and 8080-8082 (DB Console) available for a 3-node cluster

Step 1: Detect Platform and Download

Detect the OS and architecture, then download the appropriate binary.

Download URLs

Base URL: https://binaries.cockroachdb.com/

OS	Architecture	Filename Pattern
Linux	Intel (amd64)	`cockroach-v{VERSION}.linux-amd64.tgz`
Linux	ARM (arm64)	`cockroach-v{VERSION}.linux-arm64.tgz`
macOS	Intel (amd64)	`cockroach-v{VERSION}.darwin-10.9-amd64.tgz`
macOS	Apple Silicon (arm64)	`cockroach-v{VERSION}.darwin-11.0-arm64.tgz`
Windows	Intel (amd64)	`cockroach-v{VERSION}.windows-6.2-amd64.zip`

Replace {VERSION} with the desired release (e.g., 25.4.9). See CockroachDB Releases for the latest GA version.

Installation

# Example: macOS Apple Silicon, v25.4.9
curl -fsSL https://binaries.cockroachdb.com/cockroach-v25.4.9.darwin-11.0-arm64.tgz | tar xz
mkdir -p ~/.cockroachdb/bin
cp cockroach-v25.4.9.darwin-11.0-arm64/cockroach ~/.cockroachdb/bin/
export PATH="$HOME/.cockroachdb/bin:$PATH"

If cockroach is already on PATH, skip the download.

Step 2: Start the Cluster

A 3-node cluster is recommended for development because it exercises replication, range distribution, leaseholder balancing, and survival goals -- core CockroachDB capabilities that a single node cannot demonstrate.

3-Node Cluster (Recommended)

# Start 3 nodes with separate SQL, RPC, and HTTP ports
cockroach start --insecure --listen-addr=localhost:26357 --sql-addr=localhost:26257 \
  --http-addr=localhost:8080 --store=~/.cockroachdb/data/node1 \
  --log-dir=~/.cockroachdb/logs/node1 \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

cockroach start --insecure --listen-addr=localhost:26358 --sql-addr=localhost:26258 \
  --http-addr=localhost:8081 --store=~/.cockroachdb/data/node2 \
  --log-dir=~/.cockroachdb/logs/node2 \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

cockroach start --insecure --listen-addr=localhost:26359 --sql-addr=localhost:26259 \
  --http-addr=localhost:8082 --store=~/.cockroachdb/data/node3 \
  --log-dir=~/.cockroachdb/logs/node3 \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

# Initialize the cluster (only needed on first start)
cockroach init --insecure --host=localhost:26357

Single-Node (Lightweight)

For minimal resource usage when full cluster capabilities are not needed:

cockroach start-single-node --insecure --listen-addr=localhost:26257 \
  --http-addr=localhost:8080 --store=~/.cockroachdb/data/node1 \
  --log-dir=~/.cockroachdb/logs/node1 --background

Step 3: Verify the Cluster

# Check SQL connectivity
cockroach sql --insecure --host=localhost:26257 -e "SELECT version();"

# Verify all nodes joined (3-node cluster)
cockroach sql --insecure --host=localhost:26257 \
  -e "SELECT node_id, address, is_live FROM crdb_internal.gossip_nodes;"

# Check replication (should show num_replicas=3)
cockroach sql --insecure --host=localhost:26257 \
  -e "SHOW RANGES FROM DATABASE defaultdb;"

Connection Details

Property	Value
SQL URL	`postgresql://root@localhost:26257/defaultdb?sslmode=disable`
DB Console	`http://localhost:8080`
User	`root` (no password in insecure mode)
Database	`defaultdb`

Environment Variables for MCP Toolbox

export COCKROACHDB_HOST=localhost
export COCKROACHDB_PORT=26257
export COCKROACHDB_USER=root
export COCKROACHDB_PASSWORD=
export COCKROACHDB_DATABASE=defaultdb
export COCKROACHDB_SSLMODE=disable

Stopping the Cluster

# Graceful shutdown via PID files
kill $(cat ~/.cockroachdb/data/node1/cockroach.pid) 2>/dev/null
kill $(cat ~/.cockroachdb/data/node2/cockroach.pid) 2>/dev/null
kill $(cat ~/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null

Destroying All Data

rm -rf ~/.cockroachdb/data ~/.cockroachdb/logs

Air-Gapped / Restricted Environments

For environments without internet access:

Pre-download the binary on an allowed machine
Transfer to the target machine via approved channels
Place at ~/.cockroachdb/bin/cockroach or any PATH location

What a 3-Node Cluster Enables

Capability	Single Node	3-Node
SQL execution	Yes	Yes
Replication (num_replicas=3)	No	Yes
Range distribution	No	Yes
Leaseholder balancing	No	Yes
Node failure simulation	No	Yes
`SHOW RANGES` with real distribution	No	Yes
Survival goals (`SURVIVE ZONE FAILURE`)	No	Yes
Contention between nodes	No	Yes

Safety Considerations

The cluster runs in insecure mode (no TLS, no authentication) -- suitable for local development only.
Data persists in ~/.cockroachdb/data across restarts.
The binary and data are user-local (~/.cockroachdb/) -- no sudo or system modifications.
A 3-node cluster uses approximately 750 MB of RAM total.

References

Repository: cockroachlabs/cockroachdb-skills
Commit: 84bc1e4

Last updated: about 22 hours ago
Created: about 22 hours ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.