Cockroach Start Local Cluster
Introduction
The horizontal scalability of the CockroachSQL database system is just one of the beneficial features that assist developers with efficiently storing and managing information. Cockroach is flexible too because you can run it on a cloud–either public or private, a web server, local machine, or use it as a business cluster for creating apps. Two more advantages of Cockroach are that it returns super fast responses to queries and offers low latency on a consistent basis. Experiment with it yourself. To begin, use this tutorial to learn how perform the Cockroach start local cluster steps in the fastest way.
Prerequisites
- CockroachDB – Download the appropriate version for your server or OS.
NOTE: Alternatively, use Docker containers. Run nodes of a cluster CockroachDB.
- Use the command below to verify your version of CockroachDB:
1 | cockroach version |
- You should receive a
Build Tag: v19.2.2
response or something similar to it. If you didn’t, continue to the following section to install CockroachDB.
Install CockroachDB
If for whatever reason, the command cockroach version
fails to return a version response, install the binary package so that you can continue this Cockroach start local cluster tutorial.
- For your Linux machine, use the command
wget
to get the binary:
1 | wget -qO- https://binaries.cockroachdb.com/cockroach-v19.2.2.src.tgz | tar xvz |
- When completed, use
cd
command to access the directory archive like this:
1 | cd cockroach-v19.2.2 |
- Finally, use the command
make
to finish the service CockroachDB binary source build process:
1 | make build |
Install CockroachDB on Mac OS X
- For your macOS X machine, use the v19 Cockroach repository in Homebrew. Input the
brew install
command from the terminal window in the macOS X:
1 | brew install cockroachdb/tap/cockroach |
- After the installation is complete, run a Cockroach start local cluster with the command
cockroach start --insecure
.
NOTE: If during your cluster starting attempt, you see a
failed to start server
error message, work around it with--host
or--advertise-host
. Pass the port and domain to either one of those options.
Another way to get the Cockroach start local cluster to run successfully is to do a binary download with cURL. Duplicate the binary by copying it to the directory
/usr/local/bin
after the download is done.Check it by attempting to use a few commands for
cockroach
. Acockroach: command not found
error message indicates that the service failed to install properly.
Initialize the CockroachDB cluster
- Enable the service for the Cockroach start local cluster to happen automatically by initializing it with the flag
--help
command:
1 | cockroach init --help |
Initialize an insecure CockroachDB cluster
- Here’s how to perform a CockroachDB multi-node initialization with the flag
--host
command:
1 | cockroach init --insecure --host localhost:26257 |
NOTE: Before you use your server to run the Cockroach cluster on it, confirm that your port is configured to be the same as what your settings state and that your IP address and host matches what they should be as well. Port
26257
is the CockroachDB default, but it may differ based on your specific configuration installation settings.
Create a bridge network for the CockroachDB nodes
Make a Docker bridge network so that you’ll be able to have many Docker containers for each node in Cockroach.
- The command
network create
constructs a Docker network that’s namedcluster_network
in this example:
1 | docker network create -driver bridge cluster_network |
NOTE: The code you used above includes the option for
--driver
(shortened to-d
) that identifies it as abridge
network.
Troubleshooting Cockroach start local cluster
You’ll need to have SSL security certificates for your Cockroach nodes; otherwise, an exception might be raised. Specifically, you might receive the ERROR: cannot load certificates
or cockroach ERROR: cannot dial server
error message.
Override the default CockroachDB hostname
Pass the port and domain explicitly to the flag --advertise-host
if you receive a --advertise-addr: lookup Macs-MacBook-Pro.local: no such host
exception.
- Fix the hostname error like this:
1 | cockroach start --insecure --advertise-host localhost:26257 |
Cockroach start local cluster
- Use the command
cockroach start
to begin the Cockroach start local cluster process on your OS localhost. The below example shows an insecure cluster being started:
1 | cockroach start --insecure --listen-addr=localhost |
- Here’s how to use the flag
--store
option to run a CockroachDB cluster for a particular node:
1 2 3 4 5 6 7 8 9 | cockroach START \ --insecure \ --listen-addr=localhost:26257 \ --store=node_1 \ --http-addr=localhost:8080 |
Let’s look at the details about the Cockroach start local cluster code you just entered above:
- It puts the cluster of Cockroach in the foreground of your machine’s terminal. But you can select the option
--background
to run the service in the background if you prefer.
- At a terminal window, you can stop the Cockroach cluster by depressing the CTRL+C keys.
CockroachDB start in secure mode
Check that you have your SSL security certificates to avoid raising the exception ERROR: cannot load certificates
when you want to run a secure cluster.
Cockroach start with join
Starting Cockroach with v19.2, the flag --join
is required to join more than one node on your CockroachDB cluster. Now, pass as parameters the addresses of every node you want to join to a cluster.
List the CockroachDB nodes
- Use this command to return a complete node listing when you run a CockroachDB cluster insecure instance:
1 | cockroach node ls --insecure |
CockroachDB CLI
- While the Cockroach start local cluster is actively running, get to the interface for the command line with
cockroach sql
like this:
1 | cockroach sql --insecure |
Use the flag --certs-dir
to Cockroach start local cluster from the command line interface (CLI) with a secure connection. Exit with the SQL q
command. It takes you back to the command prompt or window terminal of your OS.
Start CockroachDB in Docker
To begin a Cockroach start local cluster when using Docker containers with Cockroach nodes, input the command docker ps
. It will return a list so that you can get IDs of the containers you’re running and get to them that way.
WARNING: At this time, running a cluster of CockroachDB in Docker or in another similar containerized environment may result in an unstable combination. According to Cockroach Labs, there are still a lot of bugs that must be fixed for it to work seamlessly. If you’re an expert, have at it, but be aware of the issues that you may have to workaround.
Use Docker Exec to start a CockroachDB cluster
- Get into a Docker CockroachDB node container with this command
docker exec
:
1 | docker exec -it {NODE_CONTAINER_ID} /bin/bash |
For your UNIX-based OS, use the
/
(forward slash) key to run the file.Next, as long as the executable
cockroach
file and the cluster share directories, use this command to Cockroach start local cluster:
1 | ./cockroach start --insecure |
- If CockroachDB CLI is currently running, invoke the command
sql
like this:
1 | ./cockroach sql --insecure |
Initialize CockroachDB in Docker
- Use the command below to initialize the container from the outside of it:
1 | docker exec -it node1 ./cockroach init --insecure |
Troubleshooting CockroachDB in Docker
- To see more detailed error messages in the Cockroach log when you Cockroach start local cluster, use the option
--logtostderr
:
1 | ./cockroach start --logtostderr |
- Your result should look similar to this:
1 | logging to directory /cockroach/cockroach-data/logs |
- Alternatively, look within the directory for the
/logs
and read the logs for the node’s bind-mounted volume.
CockroachDB could not cleanup temporary directories
You might see the below exception:
1 2 3 | ERROR: could not cleanup temporary directories from record file: could not lock temporary directory |
Fix the above error by deleting the temporary directory.
*Use the command rm -rf
, and then put the directory path and temporary directory’s name:
1 | rm -rf /cockroach/cockroach-data/cockroach-temp1234 |
Conclusion
This concludes this tutorial about Cockroach start local cluster with or within a containerized environment. There are several ways to get the cluster to run. For example, you can start it in an insecure or secure mode. With secure mode, you’ll need to have your CockroachDB’s SSL security certificates. We also addressed how to tackle common troubleshooting error messages you may encounter. CockroachDB has several benefits for DBAs and developers. It’s flexibility in scaling and super-fast response times makes learning how to start a local cluster worthwhile.
Pilot the ObjectRocket Platform Free!
Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.
Get Started