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 doctor
Homebrew commands before installing any new package, to be sure the new program installs correctly. Execute the following command to run the update
and doctor
Homebrew utilities:
1 | 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:
1 | 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:
1 | brew install cockroachdb/tap/cockroach |
The CockroachDB repository can also be tapped, before installation, with the following complex-shell command:
1 | 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 wget
command.
The following bash command will get v19.2.2
of the CockroachDB binary tarball archive and extract it into a folder:
1 | 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
) command:
1 | 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:
1 | 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:
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:
1 | 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:
1 | 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:
1 2 3 4 5 6 7 8 9 10 | 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 \ --join=node1,node2 |
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:
1 | docker exec -it node1 ./cockroach init --insecure |
Once inside, execute the following command to start the cluster:
1 | 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:
1 2 | 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:
1 | ./cockroach start --logtostderr |
The results of the above command should produce the following statement at the beginning of the response:
1 | 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
command:
rm -rf /cockroach/cockroach-data/cockroach-temp1234
CockroachDB connection refused
If connection to a CockroachDB node fails, the following error may occur:
1 | dial tcp 127.0.0.1:26257: connect: connection refused |
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.
Pilot the ObjectRocket Platform Free!
Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.
Get Started