CockroachDB Basics

Introduction

In this tutorial we’ll show you the basic operations you can perform on a cluster in CockroachDB. We’ll demonstrate the common operations of starting a cluster, adding nodes, monitoring the cluster, and stopping in our local development environment running on Mac OS X.

Prerequisites

• You should have CockroachDB installed. We have a “How to Install CockroachDB on Mac OS X” article that can help you if don’t already have it installed.
• We recommend you be familiar with the command line. It’s not required but the commands can be a little intimidating if you’re not.

Starting a Cluster

To create a cluster we start the first node. Let’s look at the command to do so first and then we’ll dissect what’s happening:

You should receive a response similar to ours:

This command starts a new node in insecure mode ( specified by the –insecure flag ) which leaves the communication unencrypted. This is for our development so insecure mode is fine.

The --lisen-addr=localhost specifies that the node should only listen on localhost (127.0.0.1) with the default port (26257). The Admin UI by default is available on localhost:8080.

If you look at the output of the command you can can view a lot of helpful information including where the node data is stored store[0]:            path=/Users/alexthompson/Downloads/cockroach-data.

Now that we have successfully started a node in our first cluster let’s move on to the next step of adding another node.

Adding a Node to the Cluster

In production environments you’ll typically have an odd number of three or mored nodes which allows for CockroachDB the ability to perform replication and fault tolerance to your cluster. We’ll demo this by adding two more nodes to our cluster.

Inside a new terminal tab or window you’ll execute the following command:

Now we add a third node so we have an odd number of node with a similar command:

Each new node is listening on a different localhost port. The first is listening on localhost:26257, the second on localhost:26258, and the third is on localhost:26259. Each Admin UI also listens on a different localhost port. The first is listening on localhost:8080, the second on localhost:8081, and the third is on localhost:8082.

Let’s explain a few of the differences from the command we used to create the first node. In these commands the --join flag is used to connect the nodes of the cluster. Since we’re running on a single machine we use the --store flag to put the nodes data in a subdirectory of the initial node.

Verify the Cluster is Working

To verify the cluster is working we will open the execute some SQL commands. To start the SQL client open the Terminal and execute the following command:

You should see a response similar to below letting you know that you’ve entered the cockroach SQL interface:

Now let’s make sure we can execute some commands. We’ll start with creating a database:

Then we’ll create a new table in that database:

And insert a row:

Now let’s verify the data has been stored:

Response:

To exit the SQL shell type in `q’ and then hit enter and you’ll be returned to your normal bash.

We just connected to the first node on port 26257 but let’s try connecting to the second node:

And then you can execute the same query to get the data we inserted on node 1:

So we can get the same data from each node in our cluster. Again type \q and hit enter to exit the SQL client.

Visit the Admin UI to Monitor your Cluster

Now you can monitor your cluster from the included Admin UI. Open up your preferred browser to http://localhost:8080 which is the port our first node is listeing for http requests on.

You should see something similar to this:

You can find tons of useful information from the this page including a list of your databases, a list of your tables, a history of events, and the number of nodes replicating your data.

Stopping the Cluster

You can stop the cluster by going to the Terminal where your first node is running and pressing CTRL-C. Doing this will exhibit some of the properties of CockroachDB because although you have taken one node offline, the cluster still works because 2 out of 3 ( a majority ) of the nodes are still running. You can verify this by logging into the SQL client through nodes 2 or 3 which are still running and testing the SELECT query from earlier.

Now to stop the node completely go to each terminal that is still running a cockroachDB node and stopping it CTRL-C.

To remove the data created by this test you can remove the directories with the following remove recursively command:

Conclusion

We showed some of the basics of running a CockroachDB cluster including creating a new cluster, adding nodes, creating databases, creating tables, monitoring the Admin UI, and stopping the cluster. We hope you’ll use these basics as a foundation to get more experience with this new technology for creating distributed SQL systems.

If you have any questions about CockroachDB, NewSQL, or distributed SQL systems don’t hesitate to reach out to us.