Install and Run the CockroachDB Client - Part 1

Have a Database Problem? Speak with an Expert for Free
Get Started >>


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.


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:

brew update && brew doctor

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:

brew install cockroach

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:

brew install cockroachdb/tap/cockroach

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

brew tap cockroachdb/tap && brew install cockroach

The results should resemble the following image:

Screenshot of installing the service for a CockroachDB client on macOS with Homebrew

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:

wget -qO- | tar xvz

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:

cp -i cockroach-v19.2.2.linux-amd64/cockroach /usr/local/bin/

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:

cockroach init --help

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:

Screenshot of an install CockroachDB on Linux example from source binary

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:

Docker version 19.03.5, build 633a0ea

Pull Docker image for CockroachDB

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

docker pull cockroachdb/cockroach

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

docker run -d                                        \
    --name=node1                                     \
    --name=node2                                     \
    --hostname=cdb_container                         \
    --net=cdb_network                                \
    -p 26257:26257 -p 8080:8080                      \
    -v "./cdb-data/node1:/cockroach/cockroach-data"  \
    cockroachdb/cockroach:v19.2.2 start              \
    --insecure                                       \

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:

docker exec -it node1 ./cockroach init --insecure

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

cockroach start local 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:

ERROR: could not cleanup temporary directories from record file:
could not lock temporary directory

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

./cockroach start --logtostderr

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

logging to directory /cockroach/cockroach-data/logs

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:

Screenshot of the Docker logs for the CockroachDB client in a macOS Finder window 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:

dial tcp connect: connection refused


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.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.