Install and Run the CockroachDB Client - Part 1

Introduction

This is part one of a two-part tutorial series providing an in-depth explanation on how to install and access the CockroachDB client interface. CockroachDB has an included interactive client that comes standard with the CockroachDB installation that allows for making SQL commands to modify a cluster data. This tutorial will explain how to install, initialize and start a CockroachDB cluster and some common troubleshooting issues when using CockroachDB in Docker.

Prerequisites

CockroachDB must be properly installed and configured before its client interface can be used to execute commands.

Install CockroachDB on a Mac

If Homebrew is already installed, execute the brew command to install CockroachDB on a MacOS

Note that newer versions of Homebrew will automatically update repositories before installing a new package. However, it is always a good idea to run the update and doctorHomebrew commands before installing any new package, to be sure the new program installs correctly. Execute the following command to run the update and doctorHomebrew utilities:

Once the update is finished, confirm the results and make sure there weren’t any issue with the kegs, links or repositories. If issues are found, run the brew doctor utility to resolve those problems.

When everything is working properly, execute the following command to install CockroachDB:

If the installation is successful, Homebrew should download the keg for CockroachDB and install the server.

No available formula with the name “cockroach”

If a “no-available-formula” error occurs while attempting to execute the above command, try instead to install the package with the following command:

The CockroachDB repository can also be tapped, before installation, with the following complex-shell command:

The results should resemble the following image:

Install CockroachDB on Linux

Before installing CockroachDB from its source on a Linux machine or server, the latest binary must first be downloaded using the wget command.

The following bash command will get v19.2.2 of the CockroachDB binary tarball archive and extract it into a folder:

NOTE: If the tarball is downloaded without extraction, the GUI file manager must be opened and the package must be double clicked on for extraction. Alternatively, executing the tar -xzvf cockroach-v19.2.2.linux-amd64.tgz command via the command line will carry out the same function.

Once the download has completed, move the extracted folder to the /usr/local/bin/ Linux directory for binary applications so CockroachDB can be accessed and executed globally. This can be done in a terminal window, at the same directory level as the binary folder, with the following copy (cp) command:

NOTE: If a Permission denied error occurs while executing the above command, the directory will have to be copied using elevated sudo privileges. The cockroach commands should function properly once the folder has been moved or copied. Execute the following statement for more information on any of the available Cockroach commands:

The cockroach version command can also be used to verify the currently installed version of CockroachDB. Alternatively, execute the which cockroach command, in a UNIX terminal, to view the source directory for the command.

The results of the above command should resemble the following image:

Run CockroachDB in Docker

It is not recommended to run CockroachDB in Docker as it will require more tweaking and troubleshooting. However, first confirmed that the Docker engine is installed and running properly before trying to run CockroachDB in Docker.

The following response should be visible after executing the docker --version command in a terminal or command prompt window:

Pull Docker image for CockroachDB

The following docker pull command will obtain the latest Docker image of CockroachDB from the official Cockroach Labs repository:

Multiple CockroachDB nodes can be ran on an insecure cluster using the Docker image, as obtained above, by executing the following docker run command:

NOTE: The -v option will bind mount a directory on the host machine as a volume for the CockroachDB data. Then executing the -p flag will open ports so the host machine will be able to access the cluster on the default CockroachDB port of 26257.

Once the program is running, execute the docker ps command to list all of the running containers. A container can then be entered using the docker exec command to access a node from the inside.

Execute the following Docker exec command to initialize an insecure cluster while accessing a node container:

Once inside, execute the following command to start the cluster:

Troubleshooting CockroachDB in Docker

One of the more common issues when running CockroachDB in Docker is with the temporary directories. Here the logs must be cleaned before the cluster can be started if the following “could not cleanup temporary directories” error occurs:

Execute the following --logtostderr option to have Cockroach log the more verbose error messages while starting the cluster:

The results of the above command should produce the following statement at the beginning of the response:

The logs can also be viewed inside of the bind-mounted volume for the node inside of the /logs directory. The following screenshot provides an example:

Now open the logs folder and delete the files. Alternatively, execute the following recursive rm command:

rm -rf /cockroach/cockroach-data/cockroach-temp1234

CockroachDB connection refused

If connection to a CockroachDB node fails, the following error may occur:

Conclusion

This was part one of a two-part tutorial series providing an in-depth explanation on installing and accessing the CockroachDB client interface. Part one specifically covered installing CockroachDB on MacOS and Linux machines and running CockroachDB in Docker. Part one of this series also explained how to pull a Docker image for CockroachDB, how to troubleshoot CockroachDB in Docker and CockroachDB refusing a connection in Docker. Remember that running CockroachDB in Docker is not recommended as it will require additional troubleshooting. If attempted, however, be sure to first confirm that the Docker engine is installed and running properly before attempting to run CockroachDB in Docker. Part two of this tutorial series will cover how to create and then start a secure cluster to gain access to the client interface for CockroachDB.