setting-up-local-cluster

What this skill does

# 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](https://www.cockroachlabs.com/docs/releases/) for the latest GA version.

### Installation

```bash
# 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)

```bash
# 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:

```bash
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

```bash
# 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

```bash
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

```bash
# 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

```bash
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](https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html)
- [Start a Local Cluster](https://www.cockroachlabs.com/docs/stable/start-a-local-cluster.html)
- [CockroachDB Releases](https://www.cockroachlabs.com/docs/releases/)
- [cockroach start](https://www.cockroachlabs.com/docs/stable/cockroach-start.html)
- [cockroach init](https://www.cockroachlabs.com/docs/stable/cockroach-init.html)