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/

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

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

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