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
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPUs | 4+ vCPUs |
| RAM | 4 GB | 8+ GB |
| Storage | 50 GB SSD | 100+ GB NVMe SSD |
| OS | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
Required Ports
| Port | Protocol | Purpose |
|---|---|---|
| 26257 | TCP | SQL client & inter-node communication |
| 8080 | TCP | Admin UI web interface |
| 26258 | TCP | HTTP health endpoint (optional) |
System Preparation
# 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 UTCInstallation
Download CockroachDB
# 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 versionCreate System 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/cockroachGenerate Security 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/*.keyConfiguration
Create Systemd Service
sudo nano /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.targetConfigure System Limits
sudo nano /etc/security/limits.d/cockroach.confcockroach soft nofile 65535
cockroach hard nofile 65535
cockroach soft nproc 65535
cockroach hard nproc 65535Start CockroachDB
# 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 cockroachdbFirewall Configuration
# 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 verboseRestrict Admin UI Access (Production)
# 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 tcpInitial Database Setup
Access the SQL Shell
cockroach sql --certs-dir=/etc/cockroach/certsCreate Admin User
-- 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 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;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
| Node | IP Address | Role | Location |
|---|---|---|---|
| Node 1 | 10.0.1.1 | Primary | Data Center 1 |
| Node 2 | 10.0.1.2 | Replica | Data Center 2 |
| Node 3 | 10.0.1.3 | Replica | Data Center 3 |
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:26257Join Additional Nodes
# 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 \
--backgroundVerify Cluster Status
cockroach node status --certs-dir=/etc/cockroach/certsMonitoring 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
# 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
/var/lib/cockroach/logs/*.log {
daily
rotate 7
compress
delaycompress
missingok
notifempty
create 640 cockroach cockroach
}Backup and Recovery
Full Cluster Backup
-- 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 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
-- 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';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
-- 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
-- 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;Troubleshooting
Quick Reference
Essential Commands
| Command | Description |
|---|---|
| cockroach start | Start a CockroachDB node |
| cockroach init | Initialize a new cluster |
| cockroach sql | Open SQL shell |
| cockroach node status | View cluster node status |
| cockroach quit | Gracefully stop a node |
Important File Locations
| Path | Description |
|---|---|
| /usr/local/bin/cockroach | CockroachDB binary |
| /var/lib/cockroach | Data directory |
| /etc/cockroach/certs | TLS certificates |
| /var/lib/cockroach/logs | Log files |
Deployment Complete!
You now have a fully functional CockroachDB deployment on your RamNode VPS with distributed SQL, automatic replication, and PostgreSQL compatibility.
