setting-up-local-cluster

ローカル CockroachDB クラスターのセットアップ

開発用のローカル CockroachDB クラスターをダウンロード、インストールして起動する手順を説明します。公式バイナリを使用するため、Docker や外部ランタイムの依存関係は不要です。

このスキルを使うタイミング

• 開発者が「CockroachDB をセットアップしたい」または「ローカルデータベースを起動したい」と尋ねた場合
• 接続可能な CockroachDB クラスターがない場合
• 開発者が CockroachDB を使ってアプリをゼロから構築したい場合
• 新しい開発環境をセットアップする場合

前提条件

• macOS（Intel または Apple Silicon）、Linux（Intel または ARM）、または Windows（Intel）
• バイナリのダウンロードに使用できる curl または wget
• ノードごとに約 500 MB のディスク容量
• 3 ノードクラスター用に、ポート 26257-26259（SQL）、26357-26359（RPC）、8080-8082（DB Console）が使用可能であること

ステップ 1：プラットフォームを検出してダウンロードする

OS とアーキテクチャを検出し、適切なバイナリをダウンロードします。

ダウンロード URL

ベース URL：https://binaries.cockroachdb.com/

OS	アーキテクチャ	ファイル名のパターン
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

{VERSION} を希望するリリース（例：25.4.9）に置き換えます。最新の GA バージョンについては、CockroachDB リリースを参照してください。

インストール

# 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"

cockroach がすでに PATH 上にある場合は、ダウンロードをスキップしてください。

ステップ 2：クラスターを起動する

開発には 3 ノードクラスターを推奨します。レプリケーション、レンジの分散、リースホルダーのバランシング、サバイバルゴールなど、単一ノードでは実証できない CockroachDB の中核機能を試せるためです。

3 ノードクラスター（推奨）

# 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

単一ノード（軽量）

クラスターの全機能が不要な場合に、リソースの使用を最小限に抑えるには次のようにします。

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

ステップ 3：クラスターを確認する

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

接続情報

プロパティ	値
SQL URL	postgresql://root@localhost:26257/defaultdb?sslmode=disable
DB Console	http://localhost:8080
ユーザー	root（非セキュアモードではパスワード不要）
データベース	defaultdb

MCP Toolbox 用の環境変数

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 $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

すべてのデータの削除

rm -rf $HOME/.cockroachdb/data $HOME/.cockroachdb/logs

エアギャップ環境／アクセス制限環境

インターネットに接続できない環境の場合：

1. 許可されたマシンでバイナリを事前にダウンロードします
2. 承認された方法で対象マシンに転送します
3. ~/.cockroachdb/bin/cockroach または PATH 上の任意の場所に配置します

3 ノードクラスターで可能になること

機能	単一ノード	3 ノード
SQL の実行	はい	はい
レプリケーション（num_replicas=3）	いいえ	はい
レンジの分散	いいえ	はい
リースホルダーのバランシング	いいえ	はい
ノード障害のシミュレーション	いいえ	はい
実際の分散状況を示す SHOW RANGES	いいえ	はい
サバイバルゴール（SURVIVE ZONE FAILURE）	いいえ	はい
ノード間の競合	いいえ	はい

安全に関する考慮事項

• クラスターは非セキュアモード（TLS なし、認証なし）で動作します。ローカル開発でのみ使用してください。
• データは再起動後も $HOME/.cockroachdb/data に保持されます。
• バイナリとデータはユーザーのローカル領域（~/.cockroachdb/）に置かれます。sudo やシステムの変更は不要です。
• 3 ノードクラスターは合計で約 750 MB の RAM を使用します。

参考資料

• CockroachDB のインストール
• ローカルクラスターの起動
• CockroachDB リリース
• cockroach start
• cockroach init