CockroachDB is a distributed SQL database built for applications that need strong consistency, horizontal scalability, and high availability across multiple nodes or data centers. It speaks PostgreSQL wire protocol, so existing tools and drivers work out of the box. Unlike traditional relational databases that require complex sharding setups, CockroachDB handles data distribution and replication automatically across all nodes in a cluster.
This guide walks through installing CockroachDB v26.1 on Rocky Linux 10 and AlmaLinux 10, covering single-node setup, systemd service configuration, basic SQL operations, web UI access, firewall rules, and a brief overview of multi-node cluster deployment.
Key Features of CockroachDB
CockroachDB brings several capabilities that set it apart from traditional SQL databases:
- Distributed SQL – full ACID transactions across a horizontally scalable cluster with no single point of failure
- PostgreSQL compatibility – uses the PostgreSQL wire protocol, so existing psql clients, drivers, and ORMs work without modification
- Automatic replication – data is replicated across nodes with configurable replication factors, no manual sharding required
- Survivability – the cluster continues serving reads and writes even when individual nodes go down
- Geo-partitioning – pin data to specific geographic regions for compliance and latency optimization
- Built-in web UI – a monitoring dashboard on port 8080 provides cluster health, query performance, and node status at a glance
- Online schema changes – ALTER TABLE operations run without locking the table or blocking reads/writes
- JWT/OpenID Connect authentication – v26.1 adds automatic user provisioning and role synchronization from identity providers
Prerequisites
Before starting the installation, make sure you have:
- A Rocky Linux 10 or AlmaLinux 10 server with at least 4 GB RAM and 2 CPU cores
- Root or sudo access
- A stable network connection for downloading binaries
- Firewall access to ports 26257 (SQL) and 8080 (Web UI)
Step 1: Install Required Dependencies
CockroachDB ships as a self-contained binary, but a few system utilities are needed during setup.
sudo dnf install -y wget tar glibc
Step 2: Download and Install CockroachDB Binary
Download the latest CockroachDB v26.1.1 binary archive from the official Cockroach Labs repository.
wget https://binaries.cockroachdb.com/cockroach-v26.1.1.linux-amd64.tgz
Extract the archive once the download completes.
tar -xvzf cockroach-v26.1.1.linux-amd64.tgz
Copy the
cockroach binary to
/usr/local/bin so it’s available system-wide.
sudo cp cockroach-v26.1.1.linux-amd64/cockroach /usr/local/bin/
CockroachDB includes GEOS libraries for spatial data support. Copy these to the expected library path.
sudo mkdir -p /usr/local/lib/cockroach
sudo cp cockroach-v26.1.1.linux-amd64/lib/*.so /usr/local/lib/cockroach/
Verify the installation by checking the version.
cockroach version
You should see CockroachDB v26.1.1 confirmed in the output:
Build Tag: v26.1.1
Build Time: 2026/03/03
Distribution: CCL
Platform: linux amd64
Step 3: Create CockroachDB System User and Directories
Running CockroachDB as a dedicated system user is a security best practice. Never run database processes as root in production.
sudo useradd -r -s /sbin/nologin cockroach
Create the data directory and log directory for CockroachDB.
sudo mkdir -p /var/lib/cockroach /var/log/cockroach
sudo chown cockroach:cockroach /var/lib/cockroach /var/log/cockroach
Step 4: Create a Systemd Service for CockroachDB
A proper systemd unit file ensures CockroachDB starts on boot, restarts on failure, and integrates with standard service management tools.
Create the service file.
sudo vi /etc/systemd/system/cockroachdb.service
Add the following configuration:
[Unit]
Description=CockroachDB Server
Documentation=https://www.cockroachlabs.com/docs/
Requires=network.target
After=network.target
[Service]
Type=notify
User=cockroach
Group=cockroach
ExecStart=/usr/local/bin/cockroach start-single-node \
--insecure \
--store=/var/lib/cockroach \
--log-dir=/var/log/cockroach \
--listen-addr=0.0.0.0:26257 \
--http-addr=0.0.0.0:8080 \
--cache=.25 \
--max-sql-memory=.25
Restart=always
RestartSec=10
LimitNOFILE=65535
LimitNPROC=65535
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cockroachdb
[Service]
TimeoutStopSec=60
[Install]
WantedBy=multi-user.target
The
--cache=.25 and
--max-sql-memory=.25 flags allocate 25% of available RAM to the cache and SQL memory respectively. Adjust these values based on your server’s total memory and other workloads.
Reload the systemd daemon to pick up the new service file.
sudo systemctl daemon-reload
Rocky Linux 10 and AlmaLinux 10 run SELinux in enforcing mode by default. CockroachDB needs a custom SELinux policy to allow the
cockroach binary to bind to its ports and access its data directories.
Allow the CockroachDB ports through SELinux.
sudo semanage port -a -t http_port_t -p tcp 8080
sudo semanage port -a -t postgresql_port_t -p tcp 26257
Set the correct SELinux context on the CockroachDB data and log directories.
sudo semanage fcontext -a -t var_lib_t "/var/lib/cockroach(/.*)?"
sudo restorecon -Rv /var/lib/cockroach
sudo semanage fcontext -a -t var_log_t "/var/log/cockroach(/.*)?"
sudo restorecon -Rv /var/log/cockroach
If SELinux still blocks CockroachDB after starting the service, generate a custom policy module from the audit log.
sudo ausearch -m avc -ts recent | audit2allow -M cockroachdb-custom
sudo semodule -i cockroachdb-custom.pp
Open the SQL port (26257) and the web UI port (8080) in firewalld.
sudo firewall-cmd --permanent --add-port=26257/tcp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
Verify that the rules are active.
sudo firewall-cmd --list-ports
The output should include both ports:
26257/tcp 8080/tcp
Step 7: Start and Enable CockroachDB
Start CockroachDB and enable it to launch automatically on boot.
sudo systemctl enable --now cockroachdb
Check that the service is running properly.
sudo systemctl status cockroachdb
The service should show active (running) with the CockroachDB node ready:
● cockroachdb.service - CockroachDB Server
Loaded: loaded (/etc/systemd/system/cockroachdb.service; enabled; preset: disabled)
Active: active (running) since Mon 2026-03-24 10:15:32 UTC; 5s ago
Docs: https://www.cockroachlabs.com/docs/
Main PID: 4521 (cockroach)
Tasks: 32 (limit: 23081)
Memory: 128.4M
CPU: 2.341s
CGroup: /system.slice/cockroachdb.service
└─4521 /usr/local/bin/cockroach start-single-node --insecure
Confirm that CockroachDB is listening on the expected ports.
ss -tlnp | grep cockroach
You should see both port 26257 (SQL) and port 8080 (HTTP UI) bound:
LISTEN 0 128 *:26257 *:* users:(("cockroach",pid=4521,fd=3))
LISTEN 0 128 *:8080 *:* users:(("cockroach",pid=4521,fd=12))
Step 8: Access the CockroachDB SQL Shell
Connect to the CockroachDB SQL shell using the built-in
cockroach sql command.
cockroach sql --insecure --host=localhost
You should see the interactive SQL prompt:
Welcome to the CockroachDB SQL shell.
All statements must be terminated by a semicolon.
Type: \q to exit.
root@localhost:26257/defaultdb>
Step 9: Basic SQL Operations
With the SQL shell open, run through common database operations to verify everything works.
Create a Database
Create a new database for testing.
CREATE DATABASE appdb;
USE appdb;
Create a Table
Create a sample table with a few columns.
CREATE TABLE servers (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
hostname STRING NOT NULL,
ip_address STRING NOT NULL,
os_version STRING,
created_at TIMESTAMP DEFAULT now()
);
Insert Data
Add some rows to the table.
INSERT INTO servers (hostname, ip_address, os_version) VALUES
('web01', '10.0.1.10', 'Rocky Linux 10'),
('web02', '10.0.1.11', 'Rocky Linux 10'),
('db01', '10.0.1.20', 'AlmaLinux 10'),
('monitor01', '10.0.1.30', 'Rocky Linux 10');
Query Data
Run a SELECT query to retrieve the data.
SELECT hostname, ip_address, os_version FROM servers ORDER BY hostname;
The query should return all four rows:
hostname | ip_address | os_version
-------------+-------------+-----------------
db01 | 10.0.1.20 | AlmaLinux 10
monitor01 | 10.0.1.30 | Rocky Linux 10
web01 | 10.0.1.10 | Rocky Linux 10
web02 | 10.0.1.11 | Rocky Linux 10
(4 rows)
Show Database and Table Details
Check the list of databases and tables.
SHOW DATABASES;
The output lists all databases including the one just created:
database_name | owner | primary_region | secondary_region | regions | survival_goal
----------------+-------+----------------+------------------+---------+----------------
appdb | root | NULL | NULL | {} | NULL
defaultdb | root | NULL | NULL | {} | NULL
postgres | root | NULL | NULL | {} | NULL
system | node | NULL | NULL | {} | NULL
(4 rows)
View the table schema.
SHOW COLUMNS FROM servers;
This confirms the table structure:
column_name | data_type | is_nullable | column_default | generation_expression | indices | is_hidden
---------------+-----------+-------------+-------------------------+-----------------------+-----------+------------
id | UUID | false | gen_random_uuid() | | {servers_pkey} | false
hostname | STRING | false | NULL | | {} | false
ip_address | STRING | false | NULL | | {} | false
os_version | STRING | true | NULL | | {} | false
created_at | TIMESTAMP | true | now():::TIMESTAMP | | {} | false
(5 rows)
Exit the SQL shell when done.
\q
Step 10: Access CockroachDB Web UI
CockroachDB includes a built-in web dashboard accessible on port 8080. Open a browser and navigate to:
http://YOUR_SERVER_IP:8080
Replace
YOUR_SERVER_IP with your server’s actual IP address, for example
http://10.0.1.50:8080.
The web UI provides:
- Cluster Overview – node count, uptime, storage capacity, and replication status
- Metrics – real-time graphs for queries per second, latency, memory usage, and CPU
- Databases – browse all databases, tables, and their sizes
- SQL Activity – active queries, query statistics, and slow query analysis
- Jobs – background tasks like schema changes, imports, and backups
- Advanced Debug – troubleshooting tools for cluster diagnostics
For production environments, secure the web UI by restricting port 8080 access through firewall rules to only trusted management networks.
sudo firewall-cmd --permanent --remove-port=8080/tcp
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.1.0/24" port protocol="tcp" port="8080" accept'
sudo firewall-cmd --reload
Step 11: Create a SQL User with Password
The insecure mode used in this guide is suitable for testing and development only. For any environment beyond local testing, create SQL users with passwords and enable TLS certificates.
Connect to the SQL shell and create a user.
cockroach sql --insecure --host=localhost -e "CREATE USER dbadmin WITH PASSWORD 'StrongP@ssw0rd2026';"
Grant admin privileges to the user.
cockroach sql --insecure --host=localhost -e "GRANT admin TO dbadmin;"
Verify the user was created.
cockroach sql --insecure --host=localhost -e "SHOW USERS;"
The output should list the new user:
username | options | member_of
-----------+---------+------------
admin | | {}
dbadmin | | {admin}
root | | {admin}
(3 rows)
Multi-Node Cluster Setup Overview
A single-node CockroachDB instance is useful for development and testing. Production deployments should run at least three nodes for fault tolerance – CockroachDB uses the Raft consensus protocol and needs a majority of nodes alive to maintain quorum.
Cluster Architecture
A typical three-node cluster setup looks like this:
- Node 1 – 10.0.1.51 (initial node that bootstraps the cluster)
- Node 2 – 10.0.1.52 (joins the cluster)
- Node 3 – 10.0.1.53 (joins the cluster)
Start the First Node
On the first node, start CockroachDB without the
--join flag to initialize it as the seed node.
cockroach start \
--insecure \
--store=/var/lib/cockroach \
--listen-addr=10.0.1.51:26257 \
--http-addr=10.0.1.51:8080 \
--join=10.0.1.51:26257,10.0.1.52:26257,10.0.1.53:26257 \
--background
Start Additional Nodes
On nodes 2 and 3, start CockroachDB with the
--join flag pointing to all nodes.
cockroach start \
--insecure \
--store=/var/lib/cockroach \
--listen-addr=10.0.1.52:26257 \
--http-addr=10.0.1.52:8080 \
--join=10.0.1.51:26257,10.0.1.52:26257,10.0.1.53:26257 \
--background
Initialize the Cluster
After all nodes are running, initialize the cluster from any node.
cockroach init --insecure --host=10.0.1.51:26257
The cluster initialization should complete successfully:
Cluster successfully initialized
Verify the cluster status by checking the node list.
cockroach node status --insecure --host=10.0.1.51:26257
All three nodes should appear as live:
id | address | sql_address | build | started_at | updated_at | locality | is_available | is_live
-----+-----------------+-----------------+-------------+------------+------------+----------+--------------+---------
1 | 10.0.1.51:26257 | 10.0.1.51:26257 | v26.1.1 | ... | ... | | true | true
2 | 10.0.1.52:26257 | 10.0.1.52:26257 | v26.1.1 | ... | ... | | true | true
3 | 10.0.1.53:26257 | 10.0.1.53:26257 | v26.1.1 | ... | ... | | true | true
(3 rows)
For production multi-node clusters, use TLS certificates instead of
--insecure. CockroachDB provides the
cockroach cert command to generate CA certificates, node certificates, and client certificates. See the
official security documentation for the complete TLS setup procedure.
Useful CockroachDB Commands Reference
Here is a quick reference of commonly used CockroachDB commands for day-to-day operations.
Check cluster node status.
cockroach node status --insecure --host=localhost
View cluster settings.
cockroach sql --insecure --host=localhost -e "SHOW ALL CLUSTER SETTINGS;" | head -30
Check cluster health.
cockroach node status --insecure --host=localhost --decommission
Back up a database.
cockroach sql --insecure --host=localhost -e "BACKUP DATABASE appdb TO 'nodelocal://1/backups/appdb';"
Stop CockroachDB gracefully through systemd.
sudo systemctl stop cockroachdb
Check CockroachDB logs for troubleshooting.
sudo journalctl -u cockroachdb -f
Troubleshooting Common Issues
CockroachDB fails to start with permission denied
This usually means SELinux is blocking access. Check for recent AVC denials.
sudo ausearch -m avc -ts recent
Generate and apply a custom SELinux policy if needed.
sudo ausearch -m avc -ts recent | audit2allow -M cockroachdb-custom
sudo semodule -i cockroachdb-custom.pp
sudo systemctl restart cockroachdb
Port 26257 or 8080 already in use
Check what process is using the port.
ss -tlnp | grep -E '26257|8080'
If a previous CockroachDB instance is still running, stop it before starting the service.
Cannot connect to SQL shell
Verify CockroachDB is listening and the firewall allows the connection.
sudo systemctl status cockroachdb
sudo firewall-cmd --list-ports
High memory usage
CockroachDB caches data aggressively by default. Reduce the cache and SQL memory allocation in the systemd service file.
sudo vi /etc/systemd/system/cockroachdb.service
Change the cache flags to lower values:
--cache=128MiB \
--max-sql-memory=128MiB
Then reload and restart the service.
sudo systemctl daemon-reload
sudo systemctl restart cockroachdb
Conclusion
CockroachDB is running on Rocky Linux 10 / AlmaLinux 10 with a systemd-managed service, SQL access working through the built-in shell, and the web UI available for monitoring. The single-node setup covered here works well for development and testing. For production, deploy a minimum of three nodes with TLS certificates enabled, proper backup schedules, and monitoring through the web dashboard or Prometheus integration. Check the
official CockroachDB documentation for advanced topics like geo-partitioning, change data capture, and backup/restore strategies.
Frequently Asked Questions
Is CockroachDB free to use?
CockroachDB Core is open source under the Business Source License (BSL). You can run it freely in production on self-hosted infrastructure. Enterprise features like encrypted backups, geo-partitioning controls, and SSO authentication require a paid license. CockroachDB Cloud is a fully managed option with a free tier for small workloads.
Can I use PostgreSQL clients and tools with CockroachDB?
Yes. CockroachDB implements the PostgreSQL wire protocol, so tools like
psql, pgAdmin, DBeaver, and standard PostgreSQL drivers for Python, Go, Java, and Node.js all work with CockroachDB. Some PostgreSQL-specific features like stored procedures and custom extensions may not be fully supported – check the
compatibility documentation for details.
How many nodes do I need for a production cluster?
A minimum of three nodes is required for production. CockroachDB uses Raft consensus, which needs a majority of nodes alive to process writes. With three nodes, the cluster survives one node failure. Five nodes survive two failures. For multi-region deployments, plan at least three nodes per region.
What is the difference between start and start-single-node?
The
start-single-node command runs CockroachDB as a standalone instance that does not expect other nodes to join. The
start command is for multi-node clusters and requires the
--join flag to specify peer nodes. A cluster started with
start also requires a one-time
cockroach init command to bootstrap.
