// 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.
| name | setting-up-local-cluster |
| description | 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. |
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.Guides benchmarking and comparing explicit multi-statement transactions versus single-statement CTE transactions in CockroachDB, with fair test methodology, contention analysis, and performance interpretation. Use when comparing transaction formulations, benchmarking CockroachDB workloads under contention, investigating retry pressure, or deciding whether to rewrite multi-step application flows into single SQL statements.
Estimates storage requirements for CockroachDB online schema change backfills using SHOW RANGES WITH DETAILS, KEYS, INDEXES. Use before CREATE INDEX, ADD COLUMN with INDEX/UNIQUE, ALTER PRIMARY KEY, CREATE MATERIALIZED VIEW, CREATE TABLE AS, REFRESH, or SET LOCALITY on tables with large per-index footprints, to avoid mid-backfill disk exhaustion.
Guides application developers in designing correct and performant transaction patterns for CockroachDB, covering transaction lifetime, implicit vs explicit transactions, retry handling with exponential backoff, pushing invariants into SQL, selective pessimistic locking, set-based operations, connection pooling, prepared statements, keyset pagination, follower reads, and separating business logic from database logic. Use when building applications on CockroachDB, designing transaction workflows, handling retries, optimizing application-layer database interactions, or configuring connection pools.
Guides developers in selecting and implementing multi-region patterns for CockroachDB applications, covering active-passive vs active-active architectures, REGIONAL BY ROW, GLOBAL tables, manual geo-partitioning with lease preferences, and live demo setup with validation queries. Use when designing multi-region database topologies, choosing between REGIONAL BY ROW and manual partitioning, building multi-region demos, or optimizing cross-region latency.
Analyzes CockroachDB range distribution across tables and indexes using SHOW RANGES to identify range count, size patterns, leaseholder placement, and replication health. Use when investigating hotspots, uneven data distribution, range fragmentation, or validating zone configuration effects without DB Console access.
Ranks and analyzes statement fingerprints using aggregated SQL statistics from crdb_internal.statement_statistics to identify slow, resource-intensive, or error-prone query patterns. Use when investigating historical performance trends, identifying optimization opportunities, or diagnosing recurring slowness without DB Console access.