Agent Skill · Cockroach Labs

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.

View SKILL.md on GitHub → Source repository Provider profile
Provider: Cockroach Labs Path in repo: skills/cockroachdb-onboarding-and-migrations/setting-up-local-cluster/SKILL.md

Skill body

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

Prerequisites

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.

# Start 3 nodes with separate SQL, RPC, and HTTP ports.
# Use $HOME instead of ~ in --store / --log-dir / --pid-file: tilde does not
# expand inside --flag=~/... in bash or zsh.
cockroach start --insecure --listen-addr=localhost:26357 --sql-addr=localhost:26257 \
  --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \
  --log-dir=$HOME/.cockroachdb/logs/node1 \
  --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

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

cockroach start --insecure --listen-addr=localhost:26359 --sql-addr=localhost:26259 \
  --http-addr=localhost:8082 --store=$HOME/.cockroachdb/data/node3 \
  --log-dir=$HOME/.cockroachdb/logs/node3 \
  --pid-file=$HOME/.cockroachdb/data/node3/cockroach.pid \
  --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=$HOME/.cockroachdb/data/node1 \
  --log-dir=$HOME/.cockroachdb/logs/node1 \
  --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid --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 node status --insecure --host=localhost:26257

# Check replication factor (should show num_replicas = 3)
cockroach sql --insecure --host=localhost:26257 \
  -e "SHOW ZONE CONFIGURATION FOR RANGE default;"

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 $HOME/.cockroachdb/data/node1/cockroach.pid) 2>/dev/null
kill $(cat $HOME/.cockroachdb/data/node2/cockroach.pid) 2>/dev/null
kill $(cat $HOME/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null

Destroying All Data

rm -rf $HOME/.cockroachdb/data $HOME/.cockroachdb/logs

Air-Gapped / Restricted Environments

For environments without internet access:

  1. Pre-download the binary on an allowed machine
  2. Transfer to the target machine via approved channels
  3. 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

References