Install and Run the CockroachDB Client - Part 1
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
doctorHomebrew commands before installing any new package, to be sure the new program installs correctly. Execute the following command to run the
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:
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
The following bash command will get
v19.2.2 of the CockroachDB binary tarball archive and extract it into a folder:
wget -qO- https://binaries.cockroachdb.com/cockroach-v19.2.2.linux-amd64.tgz | 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 -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
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:
Docker version 19.03.5, build 633a0ea
Pull Docker image for CockroachDB
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 \
-p 26257:26257 -p 8080:8080 \
-v "./cdb-data/node1:/cockroach/cockroach-data" \
cockroachdb/cockroach:v19.2.2 start \
-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
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:
Now open the logs folder and delete the files. Alternatively, execute the following recursive
rm -rf /cockroach/cockroach-data/cockroach-temp1234
CockroachDB connection refused
If connection to a CockroachDB node fails, the following error may occur:
dial tcp 127.0.0.1:26257: 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