Start a Local Cluster (Insecure)

Once you’ve installed CockroachDB, it’s simple to start an insecure multi-node cluster locally.

Note:

Running multiple nodes on a single host is useful for testing out CockroachDB, but it's not recommended for production deployments. To run a physically distributed cluster in production, see Manual Deployment or Orchestrated Deployment. Also be sure to review the Production Checklist.

Before you begin

Make sure you have already installed CockroachDB.

Step 1. Start the first node

  1. $ cockroach start --insecure --listen-addr=localhost
  1. CockroachDB node starting at 2018-09-13 01:25:57.878119479 +0000 UTC (took 0.3s)
  2. build:               CCL v19.1.0 @ 2019/04/30 14:48:26 (go1.11.6)
  3. webui:               http://localhost:8080
  4. sql:                 postgresql://root@localhost:26257?sslmode=disable
  5. client flags:        cockroach <client cmd> --host=localhost:26257 --insecure
  6. logs:                cockroach/cockroach-data/logs
  7. temp dir:            cockroach-data/cockroach-temp998550693
  8. external I/O path:   cockroach-data/extern
  9. store[0]:            path=cockroach-data
  10. status:              initialized new cluster
  11. clusterID:           2711b3fa-43b3-4353-9a23-20c9fb3372aa
  12. nodeID:              1

This command starts a node in insecure mode, accepting most cockroach start defaults.

  • The —insecure flag makes communication unencrypted.
  • Since this is a purely local cluster, —listen-addr=localhost tells the node to listen only on localhost, with default ports used for internal and client traffic (26257) and for HTTP requests from the Admin UI (8080).
  • Node data is stored in the cockroach-data directory.
  • The standard output gives you helpful details such as the CockroachDB version, the URL for the Admin UI, and the SQL URL for clients.

Step 2. Add nodes to the cluster

At this point, your cluster is live and operational. With just one node, you can already connect a SQL client and start building out your database. In real deployments, however, you'll always want 3 or more nodes to take advantage of CockroachDB's automatic replication, rebalancing, and fault tolerance capabilities. This step helps you simulate a real deployment locally.

In a new terminal, add the second node:

  1. $ cockroach start \
  2. --insecure \
  3. --store=node2 \
  4. --listen-addr=localhost:26258 \
  5. --http-addr=localhost:8081 \
  6. --join=localhost:26257

In a new terminal, add the third node:

  1. $ cockroach start \
  2. --insecure \
  3. --store=node3 \
  4. --listen-addr=localhost:26259 \
  5. --http-addr=localhost:8082 \
  6. --join=localhost:26257

The main difference in these commands is that you use the —join flag to connect the new nodes to the cluster, specifying the address and port of the first node, in this case localhost:26257. Since you're running all nodes on the same machine, you also set the —store, —listen-addr, and —http-addr flags to locations and ports not used by other nodes, but in a real deployment, with each node on a different machine, the defaults would suffice.

Step 3. Test the cluster

Now that you've scaled to 3 nodes, you can use any node as a SQL gateway to the cluster. To demonstrate this, open a new terminal and connect the built-in SQL client to node 1:

Note:

The SQL client is built into the cockroach binary, so nothing extra is needed.

  1. $ cockroach sql --insecure --host=localhost:26257

Run some basic CockroachDB SQL statements:

  1. > CREATE DATABASE bank;
  1. > CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);
  1. > INSERT INTO bank.accounts VALUES (1, 1000.50);
  1. > SELECT * FROM bank.accounts;
  1. +----+---------+
  2. | id | balance |
  3. +----+---------+
  4. |  1 |  1000.5 |
  5. +----+---------+
  6. (1 row)

Exit the SQL shell on node 1:

  1. > \q

Then connect the SQL shell to node 2, this time specifying the node's non-default port:

  1. $ cockroach sql --insecure --host=localhost:26258

Note:

In a real deployment, all nodes would likely use the default port 26257, and so you wouldn't need to set the port portion of —host.

Now run the same SELECT query:

  1. > SELECT * FROM bank.accounts;
  1. +----+---------+
  2. | id | balance |
  3. +----+---------+
  4. |  1 |  1000.5 |
  5. +----+---------+
  6. (1 row)

As you can see, node 1 and node 2 behaved identically as SQL gateways.

Exit the SQL shell on node 2:

  1. > \q

Step 4. Monitor the cluster

Access the Admin UI for your cluster by pointing a browser to http://localhost:8080, or to the address in the admin field in the standard output of any node on startup. Then click Metrics on the left-hand navigation bar.

CockroachDB Admin UI

As mentioned earlier, CockroachDB automatically replicates your data behind-the-scenes. To verify that data written in the previous step was replicated successfully, scroll down to the Replicas per Node graph and hover over the line:

CockroachDB Admin UI

The replica count on each node is identical, indicating that all data in the cluster was replicated 3 times (the default).

Note:

Capacity metrics can be incorrect when running multiple nodes on a single machine. For more details, see this limitation.

Tip:

For more insight into how CockroachDB automatically replicates and rebalances data, and tolerates and recovers from failures, see our replication, rebalancing, fault tolerance demos.

Step 5. Stop the cluster

Once you're done with your test cluster, switch to the terminal running the first node and press CTRL-C to stop the node.

At this point, with 2 nodes still online, the cluster remains operational because a majority of replicas are available. To verify that the cluster has tolerated this "failure", connect the built-in SQL shell to nodes 2 or 3. You can do this in the same terminal or in a new terminal.

  1. $ cockroach sql --insecure --host=localhost:26258
  1. > SELECT * FROM bank.accounts;
  1. +----+---------+
  2. | id | balance |
  3. +----+---------+
  4. |  1 |  1000.5 |
  5. +----+---------+
  6. (1 row)

Exit the SQL shell:

  1. > \q

Now stop nodes 2 and 3 by switching to their terminals and pressing CTRL-C.

Tip:

For node 3, the shutdown process will take longer (about a minute) and will eventually force kill the node. This is because, with only 1 of 3 nodes left, a majority of replicas are not available, and so the cluster is no longer operational. To speed up the process, press CTRL-C a second time.

If you do not plan to restart the cluster, you may want to remove the nodes' data stores:

  1. $ rm -rf cockroach-data node2 node3

Step 6. Restart the cluster

If you decide to use the cluster for further testing, you'll need to restart at least 2 of your 3 nodes from the directories containing the nodes' data stores.

Restart the first node from the parent directory of cockroach-data/:

  1. $ cockroach start \
  2. --insecure \
  3. --listen-addr=localhost

Note:

With only 1 node back online, the cluster will not yet be operational, so you will not see a response to the above command until after you restart the second node.

In a new terminal, restart the second node from the parent directory of node2/:

  1. $ cockroach start \
  2. --insecure \
  3. --store=node2 \
  4. --listen-addr=localhost:26258 \
  5. --http-addr=localhost:8081 \
  6. --join=localhost:26257

In a new terminal, restart the third node from the parent directory of node3/:

  1. $ cockroach start \
  2. --insecure \
  3. --store=node3 \
  4. --listen-addr=localhost:26259 \
  5. --http-addr=localhost:8082 \
  6. --join=localhost:26257

What's next?

Was this page helpful?
YesNo