Setup CockroachDB in 5 Minutes on OSX

Introduction

This tutorial will provide a straightforward example of how to install the CockroachDB on a Mac OSX in five minutes. Before beginning, a Mac machine running Apple’s OS X is required and a cursory working knowledge of terminal commands is highly recommended in order to setup CockroachDB in 5 minutes on OSX.

Prerequisites

  • A Mac computer running Apple’s OS X
  • While most of the commands in this tutorial can be copied and pasted, having at least a cursory working knowledge of the terminal commands is highly recommended.

Using the Binary Version of CockroachDB

As there may be issues when trying to use the Homebrew application, the binary version of CockroachDB for Mac is highly recommended.

Begin by executing the following command from the terminal:

curl https://binaries.cockroachdb.com/cockroach-v19.1.1.darwin-10.9-amd64.tgz | tar -xJ

The results should resemble something that looks like the following:

$
$ curl https://binaries.cockroachdb.com/cockroach-v19.1.1.darwin-10.9-amd64.tgz | tar -xJ
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 29.6M 100 29.6M 0 0 2733k 0 0:00:11 0:00:11 --:--:-- 2728k
$
  • The previous command downloaded the binary version of Cockroach to the current directory, however, the program will not run in this location.
  • Execute the cp (copy) command, as shown below, to copy the binary file from the current directory from where it was downloaded /usr/local/bin. This will allow for the CockroachDB commands to be executed form any directory.
$ sudo cp -i cockroach-v19.1.1.darwin-10.9-amd64/cockroach /usr/local/bin

Verify the Installation by Starting a Cluster

Now that the binary file is in the proper location, start a cluster to confirm the program is properly installed.

The CockroachDB demo provides two different options for starting a Secure or Insecure cluster. The easiest way is to start an Insecure cluster as this is simply a developmental environment that is used only for testing purposes. Execute the following command to start a cluster:

$ cockroach start --insecure --listen-addr=localhost

Because the developmental environment was opened intentionally, disregard the warning, displayed below, about running in an Insecure mode.

*
* WARNING: RUNNING IN INSECURE MODE!
*
* - Your cluster is open for any client that can access localhost.
* - Any user, even root, can log in without providing a password.
* - Any user, connecting as root, can read or write any data in your cluster.
* - There is no network encryption nor authentication, and thus no confidentiality.
*
* Check out how to secure your cluster: https://www.cockroachlabs.com/docs/v19.1/secure-a-cluster.html
*

The information that confirms the cluster has been started follows the warning, as shown here:

CockroachDB node starting at 2019-05-20 20:01:20.894162 +0000 UTC (took 0.3s)
build: CCL v19.1.1 @ 2019/05/15 20:21:46 (go1.11.6)
webui: http://localhost:8080
sql: postgresql://root@localhost:26257?sslmode=disable
client flags: cockroach <client cmd="cmd"> --host=localhost:26257 --insecure
logs: /Users/alexthompson/Google Drive/(OR01) Object Rocket - MASTER/Interviews/cockroach-data/logs
temp dir: /Users/alexthompson/Google Drive/(OR01) Object Rocket - MASTER/Interviews/cockroach-data/cockroach-temp985196623
external I/O path: /Users/alexthompson/Google Drive/(OR01) Object Rocket - MASTER/Interviews/cockroach-data/extern
store[0]: path=/Users/alexthompson/Google Drive/(OR01) Object Rocket - MASTER/Interviews/cockroach-data
status: initialized new cluster
clusterID: 23f26560-c2cd-42a0-acda-497d5bdada03
nodeID: 1

This was the final step in verifying that the CockroachDB was successfully setup.

Conclusion

This tutorial demonstrated how quick and easy it is to setup the CockroachDB in 5 minutes on OSX on a local development environment. Remember to download the binary version of the CockroachDB for Mac as there may be issues with the Homebrew application. Once the CockroachDB is downloaded it will need to be moved from the current directory with a simple cp (copy) command. Bear in mind, when starting an Insecure cluster to verify the CockroachDB installation, a warning will be displayed.

As with most systems, configuration and administration become increasingly more complex when moving into a production environment. If you are thinking about using CockroachDB for managing your data, Object Rocket is here to assist you with both the setup and migration of your data from an existing system. Please don’t hesitate to reach out to us at Object Rocket to discuss setting up the CockroachDB or with any other database-management issue.

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.