---
title: "Deploy CockroachDB Cluster"
description: "Always-on distributed SQL with 3-node replication and automatic failover."
category: "Storage"
url: https://railway.com/deploy/cockroachdb-cluster
---

# Deploy CockroachDB Cluster

Always-on distributed SQL with 3-node replication and automatic failover.

**[Deploy CockroachDB Cluster on Railway](https://railway.com/template/cockroachdb-cluster)**

- **Creator:** INF Labs
- **Category:** Storage

## Template content

### cockroach-3 https://www.gravatar.com/avatar/6a6972086023626a1bfc3019a5823ce7.svg

- **Image:** cockroachdb/cockroach:latest
- **Start command:** `/bin/bash -c 'exec cockroach start --insecure --store="$COCKROACH_STORE" --listen-addr=0.0.0.0:"$SQL_PORT" --advertise-addr="$COCKROACH_NODE:$SQL_PORT" --http-addr=0.0.0.0:"$HTTP_PORT" --join="$COCKROACH_JOIN"'`

### cockroach-lb https://raw.githubusercontent.com/docker-library/docs/4da3e2446a4c257c3a32faac6256bee81f770316/haproxy/logo.png

- **Image:** haproxy:3.2-alpine
- **Start command:** `/bin/sh -c 'printf "%s\n" "global" "    log stdout format raw local0" "    maxconn 4096" "" "defaults" "    log global" "    mode tcp" "    option log-health-checks" "    timeout connect 5s" "    timeout client 1h" "    timeout server 1h" "" "listen cockroachdb" "    bind *:${PORT}" "    mode tcp" "    balance leastconn" "    option tcp-check" "    server cockroach1 ${COCKROACH_NODE_1}:${COCKROACH_SQL_PORT} check inter 5s fall 3 rise 2" "    server cockroach2 ${COCKROACH_NODE_2}:${COCKROACH_SQL_PORT} check inter 5s fall 3 rise 2" "    server cockroach3 ${COCKROACH_NODE_3}:${COCKROACH_SQL_PORT} check inter 5s fall 3 rise 2" > /tmp/haproxy.cfg; exec haproxy -W -db -f /tmp/haproxy.cfg'`

### cockroach-2 https://www.gravatar.com/avatar/6a6972086023626a1bfc3019a5823ce7.svg

- **Image:** cockroachdb/cockroach:latest
- **Start command:** `/bin/bash -c 'exec cockroach start --insecure --store="$COCKROACH_STORE" --listen-addr=0.0.0.0:"$SQL_PORT" --advertise-addr="$COCKROACH_NODE:$SQL_PORT" --http-addr=0.0.0.0:"$HTTP_PORT" --join="$COCKROACH_JOIN"'`

### cockroach-1 https://www.gravatar.com/avatar/6a6972086023626a1bfc3019a5823ce7.svg

- **Image:** cockroachdb/cockroach:latest
- **Start command:** `/bin/bash -c 'cockroach start --insecure --store="$COCKROACH_STORE" --listen-addr=0.0.0.0:"$SQL_PORT" --advertise-addr="$COCKROACH_NODE:$SQL_PORT" --http-addr=0.0.0.0:"$HTTP_PORT" --join="$COCKROACH_JOIN" & PID=$!; sleep 8; cockroach init --insecure --host=127.0.0.1:"$SQL_PORT" || true; wait "$PID"'`
- **Public domain:** Yes

## Documentation

# Deploy and Host CockroachDB Cluster on Railway

CockroachDB is a distributed SQL database built for resilient and horizontally scalable applications. This template deploys a 3-node CockroachDB cluster behind HAProxy, combining PostgreSQL-compatible SQL, replicated storage, distributed consensus, persistent volumes, and a built-in DB Console.

## About Hosting CockroachDB Cluster

Hosting CockroachDB Cluster on Railway gives you three peer database nodes connected through Railway's private network, with HAProxy providing a stable SQL entry point.

Each CockroachDB node stores data on its own persistent Railway Volume. SQL clients connect through HAProxy, while the CockroachDB DB Console is exposed separately for monitoring cluster health, SQL activity, storage, and node status.

This architecture better represents CockroachDB's native distributed design than a single-node deployment.

## Common Use Cases

- Build resilient transactional applications
- Run PostgreSQL-compatible distributed SQL workloads
- Develop multi-tenant SaaS platforms
- Evaluate fault-tolerant database architectures
- Scale relational workloads horizontally
- Test CockroachDB clustering and replication

## Dependencies for CockroachDB Cluster Hosting

- Three CockroachDB database nodes
- HAProxy for SQL connection distribution
- Persistent Railway Volume for each CockroachDB node
- Railway private networking between cluster services
- Railway TCP networking for SQL access
- Railway HTTP networking for the DB Console

## Cluster Architecture

```text
                         Applications
                              │
                              │ PostgreSQL-compatible SQL
                              ▼
                      Railway TCP Proxy
                              │
                              ▼
                           HAProxy
                              │
                    least-connections
                ┌─────────────┼─────────────┐
                ▼             ▼             ▼
          CockroachDB    CockroachDB    CockroachDB
            Node 1         Node 2         Node 3
              │              │              │
           Volume         Volume         Volume
````

CockroachDB does not use a permanent coordinator/worker topology. All three nodes are peers and participate in SQL processing, distributed storage, replication, consensus, and cluster membership.

With three nodes, the cluster can maintain a majority when one node becomes unavailable. HAProxy distributes new SQL connections across healthy nodes and avoids nodes that fail health checks.

Each CockroachDB node has its own persistent volume, so database storage is not tied to a single container.

## CockroachDB vs Similar Platforms

| Feature                       | CockroachDB Cluster | PostgreSQL | Citus | MySQL |
| ----------------------------- | ------------------: | ---------: | ----: | ----: |
| Relational SQL                |                   ✅ |          ✅ |     ✅ |     ✅ |
| PostgreSQL wire protocol      |                   ✅ |          ✅ |     ✅ |     ❌ |
| Distributed architecture      |                   ✅ |          ❌ |     ✅ |     ❌ |
| Peer database nodes           |                   ✅ |          ❌ |     ❌ |     ❌ |
| Automatic data replication    |                   ✅ |         ⚠️ |    ⚠️ |    ⚠️ |
| Horizontal scaling            |                   ✅ |         ⚠️ |     ✅ |    ⚠️ |
| ACID transactions             |                   ✅ |          ✅ |     ✅ |     ✅ |
| Distributed consensus         |                   ✅ |          ❌ |     ❌ |     ❌ |
| Built-in DB Console           |                   ✅ |          ❌ |     ❌ |     ❌ |
| Node failover capability      |                   ✅ |         ⚠️ |    ⚠️ |    ⚠️ |
| PostgreSQL-compatible drivers |                   ✅ |          ✅ |     ✅ |     ❌ |

CockroachDB is a strong choice when you want PostgreSQL-compatible application development on top of a database engine designed for distributed storage and consensus.

PostgreSQL is simpler for traditional single-node workloads, while Citus extends PostgreSQL with distributed tables and worker nodes. CockroachDB distributes the database engine itself across peer nodes.

## How to Use

This template exposes two main interfaces:

| Interface              | Purpose                                                |
| ---------------------- | ------------------------------------------------------ |
| CockroachDB DB Console | Monitoring and administration                          |
| HAProxy TCP endpoint   | SQL connections from applications and database clients |

### Open the DB Console

Open the Railway public domain associated with the first CockroachDB node.

The Console provides visibility into:

* Cluster and node health
* Databases
* SQL activity
* Sessions and transactions
* Query performance
* Storage and metrics

The DB Console is primarily for administration and observability, not for normal application SQL connections.

### Connect to SQL

Use the Railway TCP Proxy configured on the HAProxy service.

CockroachDB speaks the PostgreSQL wire protocol, so PostgreSQL-compatible clients can connect directly.

Example DBeaver configuration:

```text
Driver: PostgreSQL
Host: 
Port: 
Database: defaultdb
Username: root
Password: none
SSL mode: disable
```

Connection URL:

```text
postgresql://root@HOST:PORT/defaultdb?sslmode=disable
```

Compatible clients and libraries include:

* DBeaver
* JDBC
* Node.js `pg`
* psycopg
* Prisma
* SQLAlchemy
* Go `pgx`

Example:

```sql
CREATE DATABASE myapp;

CREATE TABLE myapp.public.users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name STRING NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now()
);

INSERT INTO myapp.public.users (name)
VALUES ('Alice');

SELECT * FROM myapp.public.users;
```

CockroachDB manages distributed storage and replication internally while applications continue using familiar relational SQL.

## Security Notice

This template currently uses CockroachDB's insecure mode to keep the multi-node Railway deployment simple and reproducible.

In insecure mode:

* SQL connections do not require a password
* The `root` SQL user can connect without authentication
* Node-to-node traffic is not protected with CockroachDB TLS certificates
* SQL access should only be exposed intentionally

This setup is best suited for development, testing, evaluation, internal environments, and learning distributed CockroachDB architecture.

For security-sensitive production environments, configure CockroachDB in secure mode with appropriate CA, node, and client certificates.

## Why Deploy CockroachDB Cluster on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying CockroachDB Cluster on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

## Similar templates

- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.
- [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway
- [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system.

Open this page in a browser: https://railway.com/deploy/cockroachdb-cluster