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