Installation Guide

Overview

CockroachDB can be installed in multiple ways depending on your environment and requirements. This guide covers all installation methods from development to production deployments.

Pre-built Binary

Fastest way to get started - download and run

Docker

Containerized deployment for any environment

Kubernetes

Cloud-native orchestrated deployment

Build from Source

Compile CockroachDB yourself for customization

Installation Methods

Pre-built Binary
Docker
Kubernetes
Build from Source

Download Pre-built Executable

The simplest installation method - download the binary for your platform:

Download for Your Platform

curl https://binaries.cockroachdb.com/cockroach-latest.darwin-10.9-amd64.tgz | tar -xz
sudo cp -i cockroach-latest.darwin-10.9-amd64/cockroach /usr/local/bin/

Verify Installation

cockroach version

Expected output:

Build Tag:        v24.3.0
Build Time:       2024/11/18 18:00:00
Distribution:     CCL
Platform:         darwin amd64 (x86_64-apple-darwin)
Go Version:       go1.22.0

Install GEOS Library (Optional)

For spatial operations, install the GEOS library:

brew install geos

The binary includes all necessary components. Just download, extract, and run!

Docker Installation

Run CockroachDB in a container for easy deployment and isolation:

Pull the Docker Image

docker pull cockroachdb/cockroach:latest

Or specify a version:

docker pull cockroachdb/cockroach:v24.3.0

Start a Single-Node Cluster

docker run -d \
  --name=cockroachdb \
  --hostname=cockroachdb \
  -p 26257:26257 \
  -p 8080:8080 \
  -v cockroach-data:/cockroach/cockroach-data \
  cockroachdb/cockroach:latest start-single-node --insecure

Parameters explained:

-d: Run in detached mode
--name: Container name
-p 26257:26257: SQL port
-p 8080:8080: Admin UI port
-v: Persistent data volume
--insecure: Development mode (use certificates for production)

Connect to the SQL Shell

docker exec -it cockroachdb ./cockroach sql --insecure

Multi-Node Docker Setup (Optional)

Use Docker Compose for a local multi-node cluster:

docker-compose.yml

version: '3.8'
services:
  roach1:
    image: cockroachdb/cockroach:latest
    command: start --insecure --join=roach1,roach2,roach3
    ports:
      - "26257:26257"
      - "8080:8080"
    volumes:
      - roach1-data:/cockroach/cockroach-data

  roach2:
    image: cockroachdb/cockroach:latest
    command: start --insecure --join=roach1,roach2,roach3
    volumes:
      - roach2-data:/cockroach/cockroach-data

  roach3:
    image: cockroachdb/cockroach:latest
    command: start --insecure --join=roach1,roach2,roach3
    volumes:
      - roach3-data:/cockroach/cockroach-data

  init:
    image: cockroachdb/cockroach:latest
    command: init --insecure --host=roach1
    depends_on:
      - roach1

volumes:
  roach1-data:
  roach2-data:
  roach3-data:

Start the cluster:

docker-compose up -d

Kubernetes Deployment

Deploy CockroachDB on Kubernetes for production-grade orchestration:

Using Helm (Recommended)

Install the CockroachDB Helm chart:

# Add the CockroachDB Helm repository
helm repo add cockroachdb https://charts.cockroachdb.com/
helm repo update

# Install CockroachDB
helm install my-release cockroachdb/cockroachdb

With custom values:

helm install my-release cockroachdb/cockroachdb \
  --set statefulset.replicas=3 \
  --set storage.persistentVolume.size=100Gi \
  --set tls.enabled=true

Using Kubernetes Operator

The CockroachDB Kubernetes Operator automates deployment and management:

# Install the operator
kubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml

# Create a CockroachDB cluster
kubectl apply -f - <<EOF
apiVersion: crdb.cockroachlabs.com/v1alpha1
kind: CrdbCluster
metadata:
  name: cockroachdb
spec:
  nodes: 3
  dataStore:
    pvc:
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 100Gi
EOF

Verify Deployment

# Check pod status
kubectl get pods

# Access the SQL client
kubectl exec -it cockroachdb-0 -- ./cockroach sql --insecure

# Port-forward to access Admin UI
kubectl port-forward cockroachdb-0 8080:8080

For production Kubernetes deployments, always enable TLS and use secrets management for certificates.

Build from Source

Build CockroachDB from source for development or customization:

Prerequisites

Required tools:

Go 1.22 or later
Bazel (installed automatically via ./dev)
Git
C++ compiler (GCC or Clang)
At least 4GB RAM for building

# Install Xcode Command Line Tools
xcode-select --install

# Install Go
brew install go

Clone the Repository

git clone https://github.com/cockroachdb/cockroach.git
cd cockroach

Build CockroachDB

Use the ./dev tool (recommended):

# Build the full cockroach binary with UI
./dev build cockroach

# Or build without UI (faster)
./dev build short

Using make (alternative):

make build

Building CockroachDB can take 20-30 minutes depending on your system. Be patient!

Build GEOS Library

For spatial functionality:

./dev build buildgeos

Install the Binary

# Install to system location
make install

# Or copy manually
sudo cp cockroach /usr/local/bin/

Verify the Build

cockroach version

For development, use ./dev build as it handles dependencies automatically and integrates with Bazel’s caching for faster rebuilds.

Post-Installation Setup

Directory Structure

CockroachDB stores data in the following structure:

cockroach-data/
├── auxiliary/         # Auxiliary files
├── logs/             # Log files
├── temp-dirs-record/ # Temporary directory tracking
└── 000001.sst        # RocksDB storage files

Storage Requirements

Plan for adequate storage:

Development: 10-20GB minimum
Production: Depends on dataset size
Recommendation: 3x replication factor means 3x raw data size
Best practice: Keep 20-30% free disk space

CockroachDB will refuse to write data when disk space falls below 10% to prevent corruption.

Security Setup

For production, always use secure mode with certificates:

Create CA Certificate

mkdir certs my-safe-directory
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

Create Node Certificates

cockroach cert create-node \
  localhost \
  $(hostname) \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

Create Client Certificates

cockroach cert create-client \
  root \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

Start in Secure Mode

cockroach start \
  --certs-dir=certs \
  --advertise-addr=localhost:26257 \
  --http-addr=localhost:8080 \
  --join=localhost:26257

Deployment Options

CockroachCloud

Fully managed CockroachDB - let us run it for you

Manual Deployment

Deploy on your own infrastructure with full control

Cloud Platforms

Deploy on AWS, GCP, Azure, or other cloud providers

Orchestration

Use Kubernetes, Terraform, or other orchestration tools

Verification Steps

After installation, verify everything works:

# Check version
cockroach version

# Start a test cluster
cockroach start-single-node --insecure --background

# Run SQL commands
cockroach sql --insecure -e "SELECT 1;"

# Check cluster status
cockroach node status --insecure

# Stop the test cluster
cockroach quit --insecure

Next Steps

Quick Start

Run your first queries and explore CockroachDB features

Production Checklist

Configure CockroachDB for production workloads

Client Drivers

Connect your application with PostgreSQL-compatible drivers

Cluster Topology

Design your cluster topology for optimal performance

Troubleshooting

Build fails with 'out of memory'

Increase available RAM or build with reduced parallelism:

./dev build cockroach -- --local_ram_resources=2048

Permission denied errors

Ensure proper permissions for installation:

sudo chown -R $(whoami) /usr/local/bin/cockroach

Port already in use

Find and stop processes using ports 26257 or 8080:

# Find process
lsof -i :26257

# Kill process
kill -9 <PID>

Certificate errors in secure mode

Verify certificates are in the correct location and have proper permissions:

ls -la certs/
cockroach cert list --certs-dir=certs

Getting Started

Architecture

SQL Reference

Administration

Operations

Performance

Overview

Pre-built Binary

Docker

Kubernetes

Build from Source

Installation Methods

Download Pre-built Executable

Docker Installation

Kubernetes Deployment

Build from Source

Post-Installation Setup

Directory Structure

Storage Requirements

Security Setup

Deployment Options

CockroachCloud

Manual Deployment

Cloud Platforms

Orchestration

Verification Steps

Next Steps

Quick Start

Production Checklist

Client Drivers

Cluster Topology

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Architecture

SQL Reference

Administration

Operations

Performance

​Overview

Pre-built Binary

Docker

Kubernetes

Build from Source

​Installation Methods

​Download Pre-built Executable

​Docker Installation

​Kubernetes Deployment

​Build from Source

​Post-Installation Setup

​Directory Structure

​Storage Requirements

​Security Setup

​Deployment Options

CockroachCloud

Manual Deployment

Cloud Platforms

Orchestration

​Verification Steps

​Next Steps

Quick Start

Production Checklist

Client Drivers

Cluster Topology

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Installation Methods

Download Pre-built Executable

Docker Installation

Kubernetes Deployment

Build from Source

Post-Installation Setup

Directory Structure

Storage Requirements

Security Setup

Deployment Options

Verification Steps

Next Steps

Troubleshooting