Update to CockroachDB

{
  "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.",
  "included_files": [],
  "name": "setting-up-local-cluster",
  "skill_md_contents": "---\nname: setting-up-local-cluster\ndescription: 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.\n---\n\n# Setting Up a Local CockroachDB Cluster\n\nGuides you through downloading, installing, and starting a local CockroachDB cluster for development. Uses the official binary -- no Docker or external runtime dependencies required.\n\n## When to Use This Skill\n\n- Developer asks to \"set up CockroachDB\" or \"start a local database\"\n- No CockroachDB cluster is reachable\n- Developer wants to build an app with CockroachDB from scratch\n- Setting up a new development environment\n\n## Prerequisites\n\n- macOS (Intel or Apple Silicon), Linux (Intel or ARM), or Windows (Intel)\n- `curl` or `wget` available for downloading the binary\n- ~500 MB disk space per node\n- Ports 26257-26259 (SQL), 26357-26359 (RPC), and 8080-8082 (DB Console) available for a 3-node cluster\n\n## Step 1: Detect Platform and Download\n\nDetect the OS and architecture, then download the appropriate binary.\n\n### Download URLs\n\nBase URL: `https://binaries.cockroachdb.com/`\n\n| OS | Architecture | Filename Pattern |\n|----|-------------|-----------------|\n| Linux | Intel (amd64) | `cockroach-v{VERSION}.linux-amd64.tgz` |\n| Linux | ARM (arm64) | `cockroach-v{VERSION}.linux-arm64.tgz` |\n| macOS | Intel (amd64) | `cockroach-v{VERSION}.darwin-10.9-amd64.tgz` |\n| macOS | Apple Silicon (arm64) | `cockroach-v{VERSION}.darwin-11.0-arm64.tgz` |\n| Windows | Intel (amd64) | `cockroach-v{VERSION}.windows-6.2-amd64.zip` |\n\nReplace `{VERSION}` with the desired release (e.g., `25.4.9`). See [CockroachDB Releases](https://www.cockroachlabs.com/docs/releases/) for the latest GA version.\n\n### Installation\n\n```bash\n# Example: macOS Apple Silicon, v25.4.9\ncurl -fsSL https://binaries.cockroachdb.com/cockroach-v25.4.9.darwin-11.0-arm64.tgz | tar xz\nmkdir -p ~/.cockroachdb/bin\ncp cockroach-v25.4.9.darwin-11.0-arm64/cockroach ~/.cockroachdb/bin/\nexport PATH=\"$HOME/.cockroachdb/bin:$PATH\"\n```\n\nIf `cockroach` is already on PATH, skip the download.\n\n## Step 2: Start the Cluster\n\nA 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.\n\n### 3-Node Cluster (Recommended)\n\n```bash\n# Start 3 nodes with separate SQL, RPC, and HTTP ports.\n# Use $HOME instead of ~ in --store / --log-dir / --pid-file: tilde does not\n# expand inside --flag=~/... in bash or zsh.\ncockroach start --insecure --listen-addr=localhost:26357 --sql-addr=localhost:26257 \\\n  --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \\\n  --log-dir=$HOME/.cockroachdb/logs/node1 \\\n  --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid \\\n  --join=localhost:26357,localhost:26358,localhost:26359 --background\n\ncockroach start --insecure --listen-addr=localhost:26358 --sql-addr=localhost:26258 \\\n  --http-addr=localhost:8081 --store=$HOME/.cockroachdb/data/node2 \\\n  --log-dir=$HOME/.cockroachdb/logs/node2 \\\n  --pid-file=$HOME/.cockroachdb/data/node2/cockroach.pid \\\n  --join=localhost:26357,localhost:26358,localhost:26359 --background\n\ncockroach start --insecure --listen-addr=localhost:26359 --sql-addr=localhost:26259 \\\n  --http-addr=localhost:8082 --store=$HOME/.cockroachdb/data/node3 \\\n  --log-dir=$HOME/.cockroachdb/logs/node3 \\\n  --pid-file=$HOME/.cockroachdb/data/node3/cockroach.pid \\\n  --join=localhost:26357,localhost:26358,localhost:26359 --background\n\n# Initialize the cluster (only needed on first start)\ncockroach init --insecure --host=localhost:26357\n```\n\n### Single-Node (Lightweight)\n\nFor minimal resource usage when full cluster capabilities are not needed:\n\n```bash\ncockroach start-single-node --insecure --listen-addr=localhost:26257 \\\n  --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \\\n  --log-dir=$HOME/.cockroachdb/logs/node1 \\\n  --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid --background\n```\n\n## Step 3: Verify the Cluster\n\n```bash\n# Check SQL connectivity\ncockroach sql --insecure --host=localhost:26257 -e \"SELECT version();\"\n\n# Verify all nodes joined (3-node cluster)\ncockroach node status --insecure --host=localhost:26257\n\n# Check replication factor (should show num_replicas = 3)\ncockroach sql --insecure --host=localhost:26257 \\\n  -e \"SHOW ZONE CONFIGURATION FOR RANGE default;\"\n```\n\n## Connection Details\n\n| Property | Value |\n|----------|-------|\n| SQL URL | `postgresql://root@localhost:26257/defaultdb?sslmode=disable` |\n| DB Console | `http://localhost:8080` |\n| User | `root` (no password in insecure mode) |\n| Database | `defaultdb` |\n\n### Environment Variables for MCP Toolbox\n\n```bash\nexport COCKROACHDB_HOST=localhost\nexport COCKROACHDB_PORT=26257\nexport COCKROACHDB_USER=root\nexport COCKROACHDB_PASSWORD=\nexport COCKROACHDB_DATABASE=defaultdb\nexport COCKROACHDB_SSLMODE=disable\n```\n\n## Stopping the Cluster\n\n```bash\n# Graceful shutdown via PID files\nkill $(cat $HOME/.cockroachdb/data/node1/cockroach.pid) 2>/dev/null\nkill $(cat $HOME/.cockroachdb/data/node2/cockroach.pid) 2>/dev/null\nkill $(cat $HOME/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null\n```\n\n## Destroying All Data\n\n```bash\nrm -rf $HOME/.cockroachdb/data $HOME/.cockroachdb/logs\n```\n\n## Air-Gapped / Restricted Environments\n\nFor environments without internet access:\n\n1. Pre-download the binary on an allowed machine\n2. Transfer to the target machine via approved channels\n3. Place at `~/.cockroachdb/bin/cockroach` or any PATH location\n\n## What a 3-Node Cluster Enables\n\n| Capability | Single Node | 3-Node |\n|-----------|-------------|--------|\n| SQL execution | Yes | Yes |\n| Replication (num_replicas=3) | No | Yes |\n| Range distribution | No | Yes |\n| Leaseholder balancing | No | Yes |\n| Node failure simulation | No | Yes |\n| `SHOW RANGES` with real distribution | No | Yes |\n| Survival goals (`SURVIVE ZONE FAILURE`) | No | Yes |\n| Contention between nodes | No | Yes |\n\n## Safety Considerations\n\n- The cluster runs in **insecure mode** (no TLS, no authentication) -- suitable for local development only.\n- Data persists in `$HOME/.cockroachdb/data` across restarts.\n- The binary and data are user-local (`~/.cockroachdb/`) -- no `sudo` or system modifications.\n- A 3-node cluster uses approximately 750 MB of RAM total.\n\n## References\n\n- [Install CockroachDB](https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html)\n- [Start a Local Cluster](https://www.cockroachlabs.com/docs/stable/start-a-local-cluster.html)\n- [CockroachDB Releases](https://www.cockroachlabs.com/docs/releases/)\n- [cockroach start](https://www.cockroachlabs.com/docs/stable/cockroach-start.html)\n- [cockroach init](https://www.cockroachlabs.com/docs/stable/cockroach-init.html)\n"
}