Start a Node

On this page

This page explains the cockroach start command, which you use to start nodes as a new cluster or add nodes to an existing cluster. For a full walk-through of the cluster startup and initialization process, see one of the Manual Deployment tutorials.

Synopsis

# Start a single-node cluster:
$ cockroach start <flags, excluding --join>

# Start a multi-node cluster:
$ cockroach start <flags, including --join> &
$ cockroach init <flags>

# Add a node to a cluster:
$ cockroach start <flags, including --join>

# View help:
$ cockroach start --help

Flags Changed in v2.0

The start command supports the following general-use and logging flags. All flags must be specified each time the node is started, as they will not be remembered, with the exception of the --join flag. Nevertheless, we recommend specifying all flags every time, including the --join flag, as that will allow restarted nodes to join the cluster even if their data directory was destroyed.

General

Locality

The --locality flag accepts arbitrary key-value pairs that describe the location of the node. Locality might include country, region, datacenter, rack, etc. The key-value pairs should be ordered from most to least inclusive, and the keys and order of key-value pairs must be the same on all nodes. It's typically better to include more pairs than fewer.

• CockroachDB spreads the replicas of each piece of data across as diverse a set of localities as possible, with the order determining the priority. However, locality can also be used to influence the location of data replicas in various ways using replication zones.

• When there is high latency between nodes (e.g., cross-datacenter deployments), CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance, also known as "follow-the-workload". In a deployment across more than 3 datacenters, however, to ensure that all data benefits from "follow-the-workload", you must increase your replication factor to match the total number of datacenters.

• Locality is also a prerequisite for using the table partitioning and Node Map enterprise features.

Example

# Locality flag for nodes in US East datacenter:
--locality=region=us,datacenter=us-east

# Locality flag for nodes in US Central datacenter:
--locality=region=us,datacenter=us-central

# Locality flag for nodes in US West datacenter:
--locality=region=us,datacenter=us-west

Store

The --store flag supports the following fields. Note that commas are used to separate fields, and so are forbidden in all field values.

Logging

By default, cockroach start writes all messages to log files, and prints nothing to stderr. However, you can control the process's logging behavior with the following flags:

Defaults

cockroach start uses the equivalent values for these logging flags by default:

• --log-dir=<first store dir>/logs
• --logtostderr=NONE

This means, by default, CockroachDB writes all messages to log files, and never prints to stderr.

Standard Output

When you run cockroach start, some helpful details are printed to the standard output:

CockroachDB node starting at 
build:               CCL v2.0.7 @ 2018-12-10 00:00:00
admin:               http://ROACHs-MBP:8080
sql:                 postgresql://root@ROACHs-MBP:26257?sslmode=disable
logs:                node1/logs
temp dir:            /node1/cockroach-temp430873933
external I/O path:   /node1/extern
attrs:               ram:64gb
locality:            datacenter=us-east1
store[0]:            path=node1,attrs=ssd
status:              initialized new cluster
clusterID:           7b9329d0-580d-4035-8319-53ba8b74b213
nodeID:              1

Examples

Start a single-node cluster

To start a single-node cluster, run the cockroach start command without the --join flag:

$ cockroach start \
--certs-dir=certs \
--host=<node1 address> \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--insecure \
--host=<node1 address> \
--cache=.25 \
--max-sql-memory=.25

Start a multi-node cluster

To start a multi-node cluster, run the cockroach start command for each node, setting the --join flag to the addressess of 3-5 of the initial nodes:

$ cockroach start \
--certs-dir=certs \
--host=<node1 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--certs-dir=certs \
--host=<node2 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--certs-dir=certs \
--host=<node3 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--insecure \
--host=<node1 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--insecure \
--host=<node2 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--insecure \
--host=<node3 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

Then run the cockroach init command against any node to perform a one-time cluster initialization:

$ cockroach init \
--certs-dir=certs \
--host=<address of any node>

$ cockroach init \
--insecure \
--host=<address of any node>

Add a node to a cluster

To add a node to an existing cluster, run the cockroach start command, setting the --join flag to the addressess of 3-5 of the nodes already in the cluster:

$ cockroach start \
--certs-dir=certs \
--host=<node4 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

$ cockroach start \
--insecure \
--host=<node4 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

See Also

• Initialize a Cluster
• Manual Deployment
• Orchestrated Deployment
• Local Deployment
• Other Cockroach Commands

Was this helpful?