Setting Up Local Cluster

作者 cockroachdb6c96c6394a61无许可证4 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

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.

仅含说明DevOps & Cloud

AI 生成的概览

使用官方二进制文件下载并启动用于开发的本地 CockroachDB 集群。

功能: 该技能指导如何为检测到的平台下载 CockroachDB 官方二进制文件，将其安装到用户主目录下，并启动推荐的 3 节点集群或轻量级单节点实例。它还涵盖集群初始化、SQL 连接与节点状态验证、连接信息、环境变量，以及如何停止集群或销毁数据。它仅包含说明，不附带脚本。
适用场景: 当开发者需要本地 CockroachDB 实例、没有可访问的集群，或正在搭建新的开发环境时使用。也适用于开发者想从零开始用 CockroachDB 构建应用的情况。
运行要求: macOS、Linux 或 Windows（Intel 或 ARM）；用于下载二进制文件的 curl 或 wget；每个节点约 500 MB 磁盘空间；3 节点集群需要空闲端口 26257-26259、26357-26359 和 8080-8082；除非为隔离环境预先下载二进制文件，否则需要访问 binaries.cockroachdb.com 的网络。不需要 Docker 或外部运行时，也不包含脚本。

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

bash

# Example: macOS Apple Silicon, v25.4.9curl -fsSL https://binaries.cockroachdb.com/cockroach-v25.4.9.darwin-11.0-arm64.tgz | tar xzmkdir -p ~/.cockroachdb/bincp cockroach-v25.4.9.darwin-11.0-arm64/cockroach ~/.cockroachdb/bin/export PATH="$HOME/.cockroachdb/bin:$PATH"

# Example: macOS Apple Silicon, v25.4.9curl -fsSL https://binaries.cockroachdb.com/cockroach-v25.4.9.darwin-11.0-arm64.tgz | tar xzmkdir -p ~/.cockroachdb/bincp 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

# 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

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 connectivitycockroach 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;"

# Check SQL connectivitycockroach 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

bash

export COCKROACHDB_HOST=localhostexport COCKROACHDB_PORT=26257export COCKROACHDB_USER=rootexport COCKROACHDB_PASSWORD=export COCKROACHDB_DATABASE=defaultdbexport COCKROACHDB_SSLMODE=disable

export COCKROACHDB_HOST=localhostexport COCKROACHDB_PORT=26257export COCKROACHDB_USER=rootexport COCKROACHDB_PASSWORD=export COCKROACHDB_DATABASE=defaultdbexport COCKROACHDB_SSLMODE=disable

Stopping the Cluster

bash

# Graceful shutdown via PID fileskill $(cat $HOME/.cockroachdb/data/node1/cockroach.pid) 2>/dev/nullkill $(cat $HOME/.cockroachdb/data/node2/cockroach.pid) 2>/dev/nullkill $(cat $HOME/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null

# Graceful shutdown via PID fileskill $(cat $HOME/.cockroachdb/data/node1/cockroach.pid) 2>/dev/nullkill $(cat $HOME/.cockroachdb/data/node2/cockroach.pid) 2>/dev/nullkill $(cat $HOME/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null

Destroying All Data

Air-Gapped / Restricted Environments

For environments without internet access:

Pre-download the binary on an allowed machine
Transfer to the target machine via approved channels
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

来源与署名

来源：cockroachdb/claude-plugin位于skills/cockroachdb-onboarding-and-migrations/setting-up-local-cluster提交6c96c63

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

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`

Setting Up Local Cluster

Setting Up a Local CockroachDB Cluster

When to Use This Skill

Prerequisites

Step 1: Detect Platform and Download

Download URLs

Installation

Step 2: Start the Cluster

3-Node Cluster (Recommended)

Single-Node (Lightweight)

Step 3: Verify the Cluster

Connection Details

Environment Variables for MCP Toolbox

Stopping the Cluster

Destroying All Data

Air-Gapped / Restricted Environments

What a 3-Node Cluster Enables

Safety Considerations

References

来源与署名

更多来自 cockroachdb/claude-plugin 的技能

Cockroachdb Sql

Molt Verify

Molt Replicator

Molt Fetch

更多DevOps & Cloud技能

M5 Onboard

Spanner Basics

Secops Cases

Managed Airflow Migrations

Managed Airflow Dag Troubleshooting

Iam Helper For Privileged Access Management