Deploy CockroachDB Cluster

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

                         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

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:

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:

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

Connection URL:

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

Compatible clients and libraries include:

• DBeaver
• JDBC
• Node.js pg
• psycopg
• Prisma
• SQLAlchemy
• Go pgx

Example:

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.