docker.recipes

CockroachDB Cluster

advanced

CockroachDB distributed SQL database cluster.

Overview

CockroachDB is a distributed SQL database designed to survive data center failures while maintaining ACID guarantees and horizontal scalability. Developed by Cockroach Labs and built on Google's Spanner paper, it combines the familiar SQL interface with automatic sharding, replication, and fault tolerance. The database uses a multi-version concurrency control system and implements the Raft consensus algorithm to ensure data consistency across nodes. This deployment creates a three-node CockroachDB cluster with HAProxy as the load balancer and connection multiplexer. The HAProxy instance distributes SQL connections across all healthy CockroachDB nodes while providing a single endpoint for applications. Each CockroachDB node automatically replicates data using a default replication factor of 3, ensuring that the cluster can survive the loss of any single node without data loss or service interruption. This configuration targets organizations requiring a PostgreSQL-compatible database with built-in horizontal scaling and high availability. Ideal for teams transitioning from traditional SQL databases who need geographic distribution, automatic failover, and the ability to scale beyond single-machine limitations without application rewrites.

Key Features

  • Multi-active cluster with automatic leader election using Raft consensus
  • PostgreSQL wire protocol compatibility for existing application integration
  • Automatic range-based sharding with configurable replication zones
  • Distributed ACID transactions with serializable snapshot isolation
  • Built-in SQL optimizer with cost-based query planning
  • HAProxy TCP load balancing with health checks for connection distribution
  • Gossip protocol for cluster membership and metadata synchronization
  • Time-travel queries and point-in-time recovery capabilities

Common Use Cases

  • 1Multi-region financial applications requiring strong consistency guarantees
  • 2E-commerce platforms needing automatic scaling during traffic spikes
  • 3SaaS applications with tenant data isolation and geographic distribution
  • 4Gaming backends requiring low-latency writes with global read replicas
  • 5IoT data collection systems processing high-volume time-series data
  • 6Microservices architectures needing distributed transaction coordination
  • 7Disaster recovery setups with automated cross-datacenter replication

Prerequisites

  • Minimum 2GB RAM per CockroachDB node (6GB total for cluster)
  • Available ports 26257 (SQL) and 8080 (Admin UI) on Docker host
  • HAProxy configuration file (haproxy.cfg) with CockroachDB backend definitions
  • Understanding of distributed systems concepts and CAP theorem tradeoffs
  • Familiarity with PostgreSQL syntax and connection parameters
  • Network connectivity between nodes for gossip protocol communication

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  roach-1: 
3    image: cockroachdb/cockroach:latest
4    container_name: roach-1
5    restart: unless-stopped
6    command: start --insecure --join=roach-1,roach-2,roach-3
7    volumes: 
8      - roach1_data:/cockroach/cockroach-data
9
10  roach-2: 
11    image: cockroachdb/cockroach:latest
12    container_name: roach-2
13    restart: unless-stopped
14    command: start --insecure --join=roach-1,roach-2,roach-3
15    volumes: 
16      - roach2_data:/cockroach/cockroach-data
17
18  roach-3: 
19    image: cockroachdb/cockroach:latest
20    container_name: roach-3
21    restart: unless-stopped
22    command: start --insecure --join=roach-1,roach-2,roach-3
23    volumes: 
24      - roach3_data:/cockroach/cockroach-data
25
26  roach-init: 
27    image: cockroachdb/cockroach:latest
28    container_name: roach-init
29    command: init --insecure --host=roach-1
30    depends_on: 
31      - roach-1
32      - roach-2
33      - roach-3
34
35  haproxy: 
36    image: haproxy:lts-alpine
37    container_name: roach-haproxy
38    restart: unless-stopped
39    ports: 
40      - "${SQL_PORT:-26257}:26257"
41      - "${UI_PORT:-8080}:8080"
42    volumes: 
43      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
44    depends_on: 
45      - roach-1
46      - roach-2
47      - roach-3
48
49volumes: 
50  roach1_data: 
51  roach2_data: 
52  roach3_data:

.env Template

.env
1# CockroachDB
2SQL_PORT=26257
3UI_PORT=8080

Usage Notes

  1. 1CockroachDB UI at http://localhost:8080
  2. 2SQL at localhost:26257
  3. 3PostgreSQL wire protocol
  4. 4Automatic replication

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

roach-1
roach-1:
  image: cockroachdb/cockroach:latest
  container_name: roach-1
  restart: unless-stopped
  command: start --insecure --join=roach-1,roach-2,roach-3
  volumes:
    - roach1_data:/cockroach/cockroach-data
roach-2
roach-2:
  image: cockroachdb/cockroach:latest
  container_name: roach-2
  restart: unless-stopped
  command: start --insecure --join=roach-1,roach-2,roach-3
  volumes:
    - roach2_data:/cockroach/cockroach-data
roach-3
roach-3:
  image: cockroachdb/cockroach:latest
  container_name: roach-3
  restart: unless-stopped
  command: start --insecure --join=roach-1,roach-2,roach-3
  volumes:
    - roach3_data:/cockroach/cockroach-data
roach-init
roach-init:
  image: cockroachdb/cockroach:latest
  container_name: roach-init
  command: init --insecure --host=roach-1
  depends_on:
    - roach-1
    - roach-2
    - roach-3
haproxy
haproxy:
  image: haproxy:lts-alpine
  container_name: roach-haproxy
  restart: unless-stopped
  ports:
    - ${SQL_PORT:-26257}:26257
    - ${UI_PORT:-8080}:8080
  volumes:
    - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
  depends_on:
    - roach-1
    - roach-2
    - roach-3

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  roach-1:
5    image: cockroachdb/cockroach:latest
6    container_name: roach-1
7    restart: unless-stopped
8    command: start --insecure --join=roach-1,roach-2,roach-3
9    volumes:
10      - roach1_data:/cockroach/cockroach-data
11
12  roach-2:
13    image: cockroachdb/cockroach:latest
14    container_name: roach-2
15    restart: unless-stopped
16    command: start --insecure --join=roach-1,roach-2,roach-3
17    volumes:
18      - roach2_data:/cockroach/cockroach-data
19
20  roach-3:
21    image: cockroachdb/cockroach:latest
22    container_name: roach-3
23    restart: unless-stopped
24    command: start --insecure --join=roach-1,roach-2,roach-3
25    volumes:
26      - roach3_data:/cockroach/cockroach-data
27
28  roach-init:
29    image: cockroachdb/cockroach:latest
30    container_name: roach-init
31    command: init --insecure --host=roach-1
32    depends_on:
33      - roach-1
34      - roach-2
35      - roach-3
36
37  haproxy:
38    image: haproxy:lts-alpine
39    container_name: roach-haproxy
40    restart: unless-stopped
41    ports:
42      - "${SQL_PORT:-26257}:26257"
43      - "${UI_PORT:-8080}:8080"
44    volumes:
45      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
46    depends_on:
47      - roach-1
48      - roach-2
49      - roach-3
50
51volumes:
52  roach1_data:
53  roach2_data:
54  roach3_data:
55EOF
56
57# 2. Create the .env file
58cat > .env << 'EOF'
59# CockroachDB
60SQL_PORT=26257
61UI_PORT=8080
62EOF
63
64# 3. Start the services
65docker compose up -d
66
67# 4. View logs
68docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/cockroachdb-cluster/run | bash

Troubleshooting

  • Clock synchronization failed: Ensure Docker host system time is synchronized via NTP
  • Node won't join cluster: Verify --join parameter includes all node names exactly as defined
  • Connection refused on port 26257: Check if roach-init container completed cluster initialization
  • Range unavailable errors: Wait for cluster to achieve quorum, may take 2-3 minutes after startup
  • HAProxy 503 errors: Verify CockroachDB nodes are healthy using admin UI health endpoints
  • Persistent volume mounting issues: Ensure Docker daemon has sufficient permissions for volume creation

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

cockroachdbhaproxy

Tags

#cockroachdb#distributed#sql#cluster

Category

Database Stacks

Related Recipes

Ad Space