CockroachDB Cluster

advanced

Distributed SQL database with automatic replication and strong consistency.

Overview

CockroachDB is a distributed SQL database designed to survive datacenter failures while maintaining ACID transactions and strong consistency guarantees. Built by former Google engineers who worked on Spanner, CockroachDB automatically replicates data across multiple nodes, rebalances data as the cluster grows or shrinks, and provides PostgreSQL wire protocol compatibility for easy application migration. The database gets its name from the cockroach's legendary survivability - the system is designed to keep running even when individual nodes fail catastrophically. This three-node CockroachDB cluster configuration creates a production-ready distributed database with automatic failover capabilities and horizontal scaling. Each node runs independently while participating in the Raft consensus protocol to maintain data consistency across the cluster. The cluster can survive the loss of one node without service interruption, automatically promoting replicas and continuing to serve read and write requests. The built-in load balancer distributes queries across healthy nodes, while the gossip protocol ensures cluster membership and routing information stays current. This setup is ideal for teams transitioning from traditional PostgreSQL deployments who need global scalability, automatic failover, and geo-distributed capabilities without changing their application code. Financial services, SaaS platforms, and e-commerce applications benefit from CockroachDB's ability to maintain strict consistency while scaling across multiple regions. The PostgreSQL compatibility means existing ORMs, drivers, and database tools work without modification, making it an attractive option for organizations needing distributed database capabilities without a complete application rewrite.

Key Features

Automatic data replication with configurable replication factor across cluster nodes
PostgreSQL wire protocol compatibility supporting existing drivers and ORMs
Raft consensus algorithm ensuring strong consistency and ACID transaction guarantees
Built-in Admin UI at port 8080 for cluster monitoring, query analysis, and performance metrics
Automatic range splitting and rebalancing as data grows across the cluster
Geo-partitioning capabilities for data locality and compliance requirements
Time Travel queries using AS OF SYSTEM TIME for historical data access
Distributed SQL execution engine with cost-based query optimization

Common Use Cases

1Multi-region SaaS applications requiring low-latency reads with global consistency
2Financial trading platforms needing ACID transactions across geographically distributed data
3E-commerce systems handling high-volume transactions with automatic scaling requirements
4IoT data ingestion pipelines requiring horizontal write scalability and real-time analytics
5Migration path from single-node PostgreSQL to distributed architecture without code changes
6Disaster recovery scenarios where automatic failover and data replication are critical
7Development and testing environments replicating production distributed database behavior

Prerequisites

Minimum 8GB RAM available as CockroachDB requires 2GB per node plus overhead
Docker Engine 20.10+ with support for multi-container networking and volume management
Ports 26257 (SQL) and 8080 (Admin UI) available on the host system
Basic understanding of distributed systems concepts and SQL database administration
Familiarity with PostgreSQL query syntax and connection management
At least 10GB available disk space per node for data storage and transaction logs

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

docker-compose.yml

1services: 
2  roach1: 
3    image: cockroachdb/cockroach:latest
4    container_name: roach1
5    command: start --insecure --join=roach1,roach2,roach3
6    volumes: 
7      - roach1_data:/cockroach/cockroach-data
8    ports: 
9      - "26257:26257"
10      - "8080:8080"
11    networks: 
12      - roach-network
13
14  roach2: 
15    image: cockroachdb/cockroach:latest
16    container_name: roach2
17    command: start --insecure --join=roach1,roach2,roach3
18    volumes: 
19      - roach2_data:/cockroach/cockroach-data
20    networks: 
21      - roach-network
22
23  roach3: 
24    image: cockroachdb/cockroach:latest
25    container_name: roach3
26    command: start --insecure --join=roach1,roach2,roach3
27    volumes: 
28      - roach3_data:/cockroach/cockroach-data
29    networks: 
30      - roach-network
31
32  init: 
33    image: cockroachdb/cockroach:latest
34    command: init --insecure --host=roach1
35    depends_on: 
36      - roach1
37      - roach2
38      - roach3
39    networks: 
40      - roach-network
41
42volumes: 
43  roach1_data: 
44  roach2_data: 
45  roach3_data: 
46
47networks: 
48  roach-network: 
49    driver: bridge

.env Template

.env

1# CockroachDB runs in insecure mode for development
2# For production, configure certificates

Usage Notes

1Docs: https://www.cockroachlabs.com/docs/
2Admin UI at http://localhost:8080 | SQL on port 26257
3Connect: docker exec -it roach1 cockroach sql --insecure
4PostgreSQL-compatible - use any PG client or ORM
5Automatic data replication - survives node failures
6For production: configure TLS certificates and remove --insecure flag

Individual Services(4 services)

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

roach1

roach1:
  image: cockroachdb/cockroach:latest
  container_name: roach1
  command: start --insecure --join=roach1,roach2,roach3
  volumes:
    - roach1_data:/cockroach/cockroach-data
  ports:
    - "26257:26257"
    - "8080:8080"
  networks:
    - roach-network

roach2

roach2:
  image: cockroachdb/cockroach:latest
  container_name: roach2
  command: start --insecure --join=roach1,roach2,roach3
  volumes:
    - roach2_data:/cockroach/cockroach-data
  networks:
    - roach-network

roach3

roach3:
  image: cockroachdb/cockroach:latest
  container_name: roach3
  command: start --insecure --join=roach1,roach2,roach3
  volumes:
    - roach3_data:/cockroach/cockroach-data
  networks:
    - roach-network

init

init:
  image: cockroachdb/cockroach:latest
  command: init --insecure --host=roach1
  depends_on:
    - roach1
    - roach2
    - roach3
  networks:
    - roach-network

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  roach1:
5    image: cockroachdb/cockroach:latest
6    container_name: roach1
7    command: start --insecure --join=roach1,roach2,roach3
8    volumes:
9      - roach1_data:/cockroach/cockroach-data
10    ports:
11      - "26257:26257"
12      - "8080:8080"
13    networks:
14      - roach-network
15
16  roach2:
17    image: cockroachdb/cockroach:latest
18    container_name: roach2
19    command: start --insecure --join=roach1,roach2,roach3
20    volumes:
21      - roach2_data:/cockroach/cockroach-data
22    networks:
23      - roach-network
24
25  roach3:
26    image: cockroachdb/cockroach:latest
27    container_name: roach3
28    command: start --insecure --join=roach1,roach2,roach3
29    volumes:
30      - roach3_data:/cockroach/cockroach-data
31    networks:
32      - roach-network
33
34  init:
35    image: cockroachdb/cockroach:latest
36    command: init --insecure --host=roach1
37    depends_on:
38      - roach1
39      - roach2
40      - roach3
41    networks:
42      - roach-network
43
44volumes:
45  roach1_data:
46  roach2_data:
47  roach3_data:
48
49networks:
50  roach-network:
51    driver: bridge
52EOF
53
54# 2. Create the .env file
55cat > .env << 'EOF'
56# CockroachDB runs in insecure mode for development
57# For production, configure certificates
58EOF
59
60# 3. Start the services
61docker compose up -d
62
63# 4. View logs
64docker 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/run | bash

Troubleshooting

Cluster initialization fails: Ensure all three nodes are running before the init container executes, add health checks if needed
Node cannot join cluster: Verify the --join parameter includes all node hostnames and the roach-network allows inter-container communication
Admin UI shows unavailable replicas: Check that all nodes have sufficient disk space and restart any failed containers
Connection refused on port 26257: Wait for cluster initialization to complete, verify the init container ran successfully
Performance issues with queries: Use EXPLAIN ANALYZE to identify distributed query bottlenecks and consider adding indexes
Memory errors in container logs: Increase Docker memory limits or reduce concurrent connection limits in client applications

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

cockroachdb

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download