setting-up-local-cluster

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

• The cluster runs in insecure mode (no TLS, no authentication) -- suitable for local development only.
• Data persists in $HOME/.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

• Install CockroachDB
• Start a Local Cluster
• CockroachDB Releases
• cockroach start
• cockroach init