Distributed Database Guide

    Deploy CockroachDB

    CockroachDB is a distributed SQL database built for cloud applications requiring high availability, strong consistency, and horizontal scalability. Deploy it on your RamNode VPS for resilient, PostgreSQL-compatible databases.

    Ubuntu 22.04/24.04
    Distributed SQL
    ⏱️ 30-45 minutes

    Introduction

    CockroachDB is a distributed SQL database built for cloud applications that require high availability, strong consistency, and horizontal scalability.

    Key Features

    • • Distributed SQL with auto replication & failover
    • • Horizontal scalability across nodes/DCs
    • • Strong consistency with serializable isolation
    • • PostgreSQL wire protocol compatibility
    • • Built-in web UI for monitoring
    • • Zero-downtime rolling upgrades

    Use Cases

    • • Financial services applications
    • • E-commerce platforms
    • • Gaming backends
    • • Geographic distribution
    • • High availability requirements
    • • ACID-compliant workloads

    Prerequisites

    RamNode VPS Requirements

    ComponentMinimumRecommended
    CPU2 vCPUs4+ vCPUs
    RAM4 GB8+ GB
    Storage50 GB SSD100+ GB NVMe SSD
    OSUbuntu 22.04 LTSUbuntu 24.04 LTS

    Required Ports

    PortProtocolPurpose
    26257TCPSQL client & inter-node communication
    8080TCPAdmin UI web interface
    26258TCPHTTP health endpoint (optional)

    System Preparation

    Update system and install dependencies
    # Update package lists and upgrade existing packages
    sudo apt update && sudo apt upgrade -y
    
    # Install required dependencies
    sudo apt install -y curl wget gnupg2 software-properties-common
    
    # Set timezone (recommended for log consistency)
    sudo timedatectl set-timezone UTC
    3

    Installation

    Download CockroachDB

    Download and install binary
    # Download the latest CockroachDB binary
    curl https://binaries.cockroachdb.com/cockroach-v24.3.0.linux-amd64.tgz | tar -xz
    
    # Move binary to system path
    sudo cp cockroach-v24.3.0.linux-amd64/cockroach /usr/local/bin/
    
    # Copy the spatial libraries (required for geospatial features)
    sudo mkdir -p /usr/local/lib/cockroach
    sudo cp -r cockroach-v24.3.0.linux-amd64/lib/* /usr/local/lib/cockroach/
    
    # Verify installation
    cockroach version

    Create System User and Directories

    Setup user and directories
    # Create cockroach system user
    sudo useradd -r -s /bin/false cockroach
    
    # Create data and certificate directories
    sudo mkdir -p /var/lib/cockroach
    sudo mkdir -p /etc/cockroach/certs
    
    # Set ownership
    sudo chown -R cockroach:cockroach /var/lib/cockroach
    sudo chown -R cockroach:cockroach /etc/cockroach

    Generate Security Certificates

    Create TLS certificates
    # Create CA certificate
    cockroach cert create-ca \
        --certs-dir=/etc/cockroach/certs \
        --ca-key=/etc/cockroach/certs/ca.key
    
    # Create node certificate (replace YOUR_VPS_IP with actual IP)
    cockroach cert create-node \
        localhost \
        $(hostname) \
        YOUR_VPS_IP \
        --certs-dir=/etc/cockroach/certs \
        --ca-key=/etc/cockroach/certs/ca.key
    
    # Create root client certificate for admin access
    cockroach cert create-client \
        root \
        --certs-dir=/etc/cockroach/certs \
        --ca-key=/etc/cockroach/certs/ca.key
    
    # Set proper permissions
    sudo chown -R cockroach:cockroach /etc/cockroach/certs
    sudo chmod 700 /etc/cockroach/certs
    sudo chmod 600 /etc/cockroach/certs/*.key
    4

    Configuration

    Create Systemd Service

    Create service file
    sudo nano /etc/systemd/system/cockroachdb.service
    /etc/systemd/system/cockroachdb.service
    [Unit]
    Description=CockroachDB Server
    After=network.target
    
    [Service]
    Type=simple
    User=cockroach
    Group=cockroach
    ExecStart=/usr/local/bin/cockroach start-single-node \
        --certs-dir=/etc/cockroach/certs \
        --store=/var/lib/cockroach \
        --listen-addr=0.0.0.0:26257 \
        --http-addr=0.0.0.0:8080 \
        --cache=.25 \
        --max-sql-memory=.25
    ExecStop=/usr/local/bin/cockroach quit --certs-dir=/etc/cockroach/certs
    Restart=on-failure
    RestartSec=10
    LimitNOFILE=65535
    
    [Install]
    WantedBy=multi-user.target

    Configure System Limits

    Create limits configuration
    sudo nano /etc/security/limits.d/cockroach.conf
    /etc/security/limits.d/cockroach.conf
    cockroach soft nofile 65535
    cockroach hard nofile 65535
    cockroach soft nproc 65535
    cockroach hard nproc 65535

    Start CockroachDB

    Enable and start service
    # Reload systemd configuration
    sudo systemctl daemon-reload
    
    # Enable service to start on boot
    sudo systemctl enable cockroachdb
    
    # Start CockroachDB
    sudo systemctl start cockroachdb
    
    # Check status
    sudo systemctl status cockroachdb
    5

    Firewall Configuration

    Configure UFW
    # Enable UFW if not already enabled
    sudo ufw enable
    
    # Allow SSH (important - do this first!)
    sudo ufw allow 22/tcp
    
    # Allow CockroachDB SQL port
    sudo ufw allow 26257/tcp
    
    # Allow Admin UI (restrict to specific IPs in production)
    sudo ufw allow 8080/tcp
    
    # Verify firewall rules
    sudo ufw status verbose

    Restrict Admin UI Access (Production)

    Limit Admin UI to specific IP
    # Remove general rule
    sudo ufw delete allow 8080/tcp
    
    # Allow only from specific IP (replace with your IP)
    sudo ufw allow from YOUR_ADMIN_IP to any port 8080 proto tcp
    6

    Initial Database Setup

    Access the SQL Shell

    Connect to CockroachDB
    cockroach sql --certs-dir=/etc/cockroach/certs

    Create Admin User

    SQL commands
    -- Create admin user
    CREATE USER admin_user WITH PASSWORD 'YourSecurePassword123!';
    
    -- Grant admin privileges
    GRANT admin TO admin_user;
    
    -- Verify user creation
    SHOW USERS;

    Create Application Database

    Create database and user
    -- Create application database
    CREATE DATABASE myapp_production;
    
    -- Create application user
    CREATE USER app_user WITH PASSWORD 'AppSecurePassword456!';
    
    -- Grant database privileges
    GRANT ALL ON DATABASE myapp_production TO app_user;
    
    -- Connect to the new database
    USE myapp_production;
    
    -- Create sample table
    CREATE TABLE users (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        email STRING UNIQUE NOT NULL,
        created_at TIMESTAMP DEFAULT current_timestamp()
    );
    
    -- Grant table privileges
    GRANT ALL ON TABLE users TO app_user;
    7

    Multi-Node Cluster Setup

    For production deployments requiring high availability, deploy CockroachDB across multiple RamNode VPS instances. A minimum of three nodes is recommended for fault tolerance.

    Cluster Architecture

    NodeIP AddressRoleLocation
    Node 110.0.1.1PrimaryData Center 1
    Node 210.0.1.2ReplicaData Center 2
    Node 310.0.1.3ReplicaData Center 3

    Initialize First Node

    Start and initialize first node
    # Start first node
    cockroach start \
        --certs-dir=/etc/cockroach/certs \
        --store=/var/lib/cockroach \
        --listen-addr=NODE1_IP:26257 \
        --http-addr=NODE1_IP:8080 \
        --join=NODE1_IP:26257,NODE2_IP:26257,NODE3_IP:26257 \
        --cache=.25 \
        --max-sql-memory=.25 \
        --background
    
    # Initialize the cluster (run only once on first node)
    cockroach init --certs-dir=/etc/cockroach/certs --host=NODE1_IP:26257

    Join Additional Nodes

    Start nodes 2 and 3
    # Start additional nodes
    cockroach start \
        --certs-dir=/etc/cockroach/certs \
        --store=/var/lib/cockroach \
        --listen-addr=NODE_IP:26257 \
        --http-addr=NODE_IP:8080 \
        --join=NODE1_IP:26257,NODE2_IP:26257,NODE3_IP:26257 \
        --cache=.25 \
        --max-sql-memory=.25 \
        --background

    Verify Cluster Status

    Check node status
    cockroach node status --certs-dir=/etc/cockroach/certs
    8

    Monitoring and Maintenance

    Admin UI

    Access the CockroachDB Admin UI at: https://YOUR_VPS_IP:8080

    The Admin UI provides real-time metrics for cluster health, SQL performance, hardware utilization, and replication status.

    Command-Line Monitoring

    Monitor cluster status
    # Check node status
    cockroach node status --certs-dir=/etc/cockroach/certs
    
    # View cluster settings
    cockroach sql --certs-dir=/etc/cockroach/certs -e "SHOW CLUSTER SETTINGS;"
    
    # Check database sizes
    cockroach sql --certs-dir=/etc/cockroach/certs -e \
        "SELECT database_name, sum(range_count) as ranges, \
         sum(approximate_disk_bytes) as disk_bytes \
         FROM crdb_internal.tenant_span_stats() GROUP BY database_name;"

    Log Management

    /etc/logrotate.d/cockroachdb
    /var/lib/cockroach/logs/*.log {
        daily
        rotate 7
        compress
        delaycompress
        missingok
        notifempty
        create 640 cockroach cockroach
    }
    9

    Backup and Recovery

    Full Cluster Backup

    Backup commands
    -- Backup to local filesystem
    BACKUP INTO 'nodelocal://1/backups/full_backup'
    WITH revision_history;
    
    -- Backup to S3 (requires AWS credentials)
    BACKUP INTO 's3://bucket-name/cockroach/backups?AWS_ACCESS_KEY_ID=xxx&AWS_SECRET_ACCESS_KEY=xxx'
    WITH revision_history;

    Scheduled Backups

    Create backup schedule
    -- Create daily full backup schedule
    CREATE SCHEDULE daily_backup
    FOR BACKUP INTO 'nodelocal://1/backups'
    RECURRING '@daily'
    FULL BACKUP ALWAYS
    WITH SCHEDULE OPTIONS first_run = 'now';
    
    -- View scheduled backups
    SHOW SCHEDULES;

    Restore from Backup

    Restore database
    -- List available backups
    SHOW BACKUPS IN 'nodelocal://1/backups';
    
    -- Restore specific database
    RESTORE DATABASE myapp_production
    FROM LATEST IN 'nodelocal://1/backups'
    WITH new_db_name = 'myapp_restored';
    10

    Performance Tuning

    Memory Configuration

    Recommended settings for 8GB RAM VPS:

    • --cache=2GB (25% of RAM for storage layer cache)
    • --max-sql-memory=2GB (25% of RAM for SQL operations)

    Storage Optimization

    Zone configuration
    -- Enable zone configuration for specific tables
    ALTER TABLE users CONFIGURE ZONE USING
        gc.ttlseconds = 86400,
        num_replicas = 3;
    
    -- View zone configurations
    SHOW ZONE CONFIGURATION FOR TABLE users;

    Query Performance

    Analyze queries
    -- Enable query tracing
    SET tracing = on;
    SELECT * FROM users WHERE email = 'test@example.com';
    SET tracing = off;
    SHOW TRACE FOR SESSION;
    
    -- View query statistics
    SELECT * FROM crdb_internal.node_statement_statistics
    ORDER BY count DESC LIMIT 10;
    11

    Troubleshooting

    12

    Quick Reference

    Essential Commands

    CommandDescription
    cockroach startStart a CockroachDB node
    cockroach initInitialize a new cluster
    cockroach sqlOpen SQL shell
    cockroach node statusView cluster node status
    cockroach quitGracefully stop a node

    Important File Locations

    PathDescription
    /usr/local/bin/cockroachCockroachDB binary
    /var/lib/cockroachData directory
    /etc/cockroach/certsTLS certificates
    /var/lib/cockroach/logsLog files

    Deployment Complete!

    You now have a fully functional CockroachDB deployment on your RamNode VPS with distributed SQL, automatic replication, and PostgreSQL compatibility.