From cockroachdb
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.
npx claudepluginhub cockroachdb/claude-plugin --plugin cockroachdbThis skill uses the workspace's default tool permissions.
Guides you through downloading, installing, and starting a local CockroachDB cluster for development. Uses the official binary -- no Docker or external runtime dependencies required.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Guides you through downloading, installing, and starting a local CockroachDB cluster for development. Uses the official binary -- no Docker or external runtime dependencies required.
curl or wget available for downloading the binaryDetect the OS and architecture, then download the appropriate binary.
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.
# 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.
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
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
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
# 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;"
| 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 |
export COCKROACHDB_HOST=localhost
export COCKROACHDB_PORT=26257
export COCKROACHDB_USER=root
export COCKROACHDB_PASSWORD=
export COCKROACHDB_DATABASE=defaultdb
export COCKROACHDB_SSLMODE=disable
# 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
rm -rf ~/.cockroachdb/data ~/.cockroachdb/logs
For environments without internet access:
~/.cockroachdb/bin/cockroach or any PATH location| 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 |
~/.cockroachdb/data across restarts.~/.cockroachdb/) -- no sudo or system modifications.