How to Install CockroachDB Cluster on Debian 12

Debian 12 is a versatile and robust operating system ideal for hosting various applications, including distributed databases like CockroachDB. In this guide, we’ll walk through the process of installing and setting up a CockroachDB cluster on Debian 12. CockroachDB is a scalable, distributed SQL database designed for cloud-native applications, and installing it on Debian 12 provides a reliable foundation for building resilient and high-performance database clusters.

What is the CockroachDB Cluster?

A CockroachDB cluster is a distributed database system built on the principles of scalability, resilience, and consistency. It is designed to handle large-scale applications and workloads by distributing data across multiple nodes or servers. The cluster architecture of CockroachDB ensures high availability, fault tolerance, and data integrity, making it suitable for cloud-native and mission-critical applications.

Key features of a CockroachDB cluster include:

1. Horizontal Scalability: CockroachDB clusters can scale horizontally by adding more nodes, allowing applications to handle increasing data volumes and user loads without compromising performance.
2. Automatic Sharding: The database automatically shards data across nodes, distributing workload and ensuring balanced resource utilization.
3. Fault Tolerance: CockroachDB is fault-tolerant, meaning it can continue to operate even if some nodes fail, thanks to its distributed consensus algorithm and replication capabilities.
4. Strong Consistency: It provides strong consistency guarantees across distributed transactions, ensuring that data remains accurate and consistent even in a distributed environment.

Step 1: Update Your System in Debian 12

1. Before installing any new software, it’s a good practice to update your system’s package repository and install packages to the latest versions. Open a terminal and run the following command:

sudo apt update
sudo apt upgrade

2. Once the packages are updated, use the below command to download and install the wget, tar, and curl packages, allowing you to use these tools for downloading files and managing archives on your system.

sudo apt install wget tar

Step 2: Installation Process of CockroachDB

1. To install CockroachDB on your machine, visit the Cockroach Labs website to download the latest or desired version. Copy the download link and use wget or curl to download it onto your system.

2. After visiting the official website, use the wget command followed by the CockroachDB download link to download the desired version onto your system.

wget --no-check-certificate https://binaries.cockroachdb.com/cockroach-v23.2.4.linux-amd64.tgz

3. Optionally, you can download the SHA256 checksum from the same source to verify your download integrity. Use the ‘sha256sum‘ command with the -c flag to ensure the downloaded file matches the checksum.

sha256sum -c cockroach-v23.2.4.linux-amd64.tgz.sha256sum

4. To access the CockroachDB command from anywhere, copy the downloaded binary file to the bin folder of your machine. This ensures that the cockroach command can be executed from any directory in your system.

cp cockroach /usr/local/bin/
ls /usr/local/bin

5. You can now access CockroachDB using the cockroach command from anywhere on your system. Additionally, create a directory in your lib folder for CockroachDB’s files with the below command, and then copy both the binary and library files there.

mkdir -p /usr/local/lib/cockroach
cp -i lib/libgoes.so /usr/local/lib/cockroach/
cp -i lib/libgoes_c.so /usr/local/lib/cockroach/

6. To verify the installation of CockroachDB, simply run the command cockroach version to check the installed version. This confirms that the installation process has been completed successfully.

cockroach version

Step 3: Generate SSL certificates

CockroachDB prioritizes secure communication between nodes and clients. To ensure data protection, we’ll be using SSL certificates, so let’s generate them. Here are the steps:

1. Create directories for certificates and keys.

mkdir certs keys

2. The CA key will be used while creating certificates for nodes and clients, it forms the basis of trust in your cluster. Use the ‘cockroach cert‘ command:

cockroach cert create-ca --certs-dir=certs --ca-key=keys/ca.key

3. Each node requires its node certificates and keys, use the ‘cockroach cert’ command to generate them:

cockroach cert create-node localhost $(hostname) --certs-dir=certs --ca-key=keys/ca.key

Note that since we’ll be running a local cluster, all nodes will have the same hostname i.e. localhost hence we’ll need only one certificate. For multi-machine clusters, generate certificates for each node.

4. Create a certificate for your root user:

cockroach cert create-client root --certs-dir=certs --ca-key=keys/ca.key

Step 4: Start the Cluster

1. Start your first node with the cockroach start command

cockroach start --certs-dir=certs --store=node1 --listen-addr=localhost:2000 --http-addr=localhost:8080 --join=localhost:2000,localhost:2001,localhost:2002

The certificate directory is referenced by the –certs-dir directory. As this is a local cluster, the node will listen on localhost only hence we provide –listen-addr=localhost:2000 and –http-addr=localhost:8080. Internal and client traffic is routed through port 2000, and HTTP requests from the DB Console are routed through port 8080. Data and logs are stored in a location in –store

The addresses and ports of the nodes that will initially make up your cluster are specified by the –join flag. We’ll use these addresses to start new nodes.

2. Launch the remaining nodes, carefully adjusting ports and join addresses:

Node 2:

cockroach start --certs-dir=certs --store=node2 --listen-addr=localhost:2001 --http-addr=localhost:8081 --join=localhost:2000,localhost:2001,localhost:2002

Node 3:

cockroach start --certs-dir=certs --store=node3 --listen-addr=localhost:2002 --http-addr=localhost:8082 --join=localhost:2000,localhost:2001,localhost:2002

Step 5: Initialize the Cluster

With all the nodes running, let’s officially initialize the cluster:

1. In a new terminal window run ‘cockroach init‘ targetting any node:

cockroach init --certs-dir=certs --host=localhost:2000

Step 6: Verify the Cluster

Ensure that your cluster is working properly:

1. Open an SQL shell on the first node. Create a database and a table and insert some rows into it.

cockroach sql --certs-dir=certs --host=localhost:2000

2. Connect to a different node to verify cross-node communication. Start a SQL session with node2.

cockroach sql --certs-dir=certs --host=localhost:2001

3. Verify your data is accessible across the cluster by running a SELECT query. You should see the same rows here as you inserted into node1 earlier.

Here we see the same data we inserted into node1, affirming that our cluster is working properly and all data is being synced across the nodes.

Installing CockroachDB Cluster on Debian 12 – FAQs

What are the benefits of using a CockroachDB cluster?

A CockroachDB cluster offers several advantages, including:

• High Availability: If a node fails, the cluster remains operational and continues to serve requests.
• Scalability: You can easily add or remove nodes as needed.
• Data Consistency: Data is replicated across all nodes, ensuring consistency between reads and writes.
• ACID Compliance: CockroachDB guarantees ACID properties for transactions.

Do I need to generate SSL certificates for my cluster?

While not strictly necessary, using SSL certificates is highly recommended for production environments. It encrypts communication between nodes and clients, enhancing the security of your cluster.

How can I connect to my CockroachDB cluster and perform SQL operations?

Once your cluster is initialized, you can use the cockroach sql command-line tool to connect to any node in the cluster and execute SQL statements.

Is it possible to deploy a CockroachDB cluster on different cloud platforms?

Absolutely. CockroachDB is cloud-agnostic and can be deployed across various cloud providers like AWS, GCP, and Azure.

How do I scale my CockroachDB cluster horizontally?

To scale the cluster horizontally, you can simply add new nodes following the steps mentioned in this article. Assign them unique storage directories, listen addresses, and ports while ensuring they join the existing cluster using the correct addresses.

Conclusion

In conclusion, setting up a CockroachDB cluster on Debian 12 offers high availability, scalability, data consistency, and ACID compliance, making it a robust choice for cloud-native applications. Using SSL certificates enhances security, and scaling horizontally is straightforward by adding nodes to the cluster.