cockroach start-single-node

​

Synopsis

$ cockroach start-single-node <flags>

$ cockroach start-single-node --help

​

Flags

​

General

​

Networking

​

Security

​

Store

​

Logging

​

Defaults

​

Docker-specific features of single-node clusters

​

Standard output

CockroachDB node starting at
build:               CCL v25.4.6 @ 2026-03-09 go1.25.5
webui:               http://localhost:8080
sql:                 postgresql://root@localhost:26257?sslmode=disable
sql (JDBC):          jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable&user=root
RPC client flags:    cockroach <client cmd> --host=localhost:26257 --insecure
logs:                /Users/<username/node1/logs
temp dir:            /Users/<username/node1/cockroach-temp242232154
external I/O path:   /Users/<username/node1/extern
store[0]:            path=/Users/<username/node1
status:              initialized new cluster
clusterID:           8a681a16-9623-4fc1-a537-77e9255daafd
nodeID:              1

​

Examples

​

Start a single-node cluster

1. Create two directories for certificates:
   $ mkdir certs my-safe-directory
   

2. Create the CA (Certificate Authority) certificate and key pair:
   $ cockroach cert create-ca \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   
3. Create the certificate and key pair for the node:
   $ cockroach cert create-node \
   localhost \
   $(hostname) \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   
4. Create a client certificate and key pair for the root user:
   $ cockroach cert create-client \
   root \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   
5. Start the single-node cluster:
   $ cockroach start-single-node \
   --certs-dir=certs \
   --listen-addr=localhost:26257 \
   --http-addr=localhost:8080
   

$ cockroach start-single-node \
--insecure \
--listen-addr=localhost:26257 \
--http-addr=localhost:8080

​

Scale to multiple nodes

1. Stop the single-node cluster: Get the process ID of the node:
   ps -ef | grep cockroach | grep -v grep
   
     501 19584     1   0  6:13PM ttys001    0:01.27 cockroach start-single-node --certs-dir=certs --listen-addr=localhost:26257 --http-addr=localhost:8080
   
   Gracefully shut down the node, specifying its process ID:
   kill -TERM 19584
   
   initiating graceful shutdown of server
   server drained and shutdown completed
   
2. Restart the node with the command:
   $ cockroach start \
   --certs-dir=certs \
   --listen-addr=localhost:26257 \
   --http-addr=localhost:8080 \
   --join=localhost:26257,localhost:26258,localhost:26259
   
   The new flag to note is --join, which specifies the addresses and ports of the nodes that will initially comprise your cluster. You’ll use this exact --join flag when starting other nodes as well. For a cluster in a single region, set 3-5 --join addresses. Each starting node will attempt to contact one of the join hosts. In case a join host cannot be reached, the node will try another address on the list until it can join the gossip network.
3. In new terminal windows, add two more nodes:
   $ cockroach start \
   --certs-dir=certs \
   --store=node2 \
   --listen-addr=localhost:26258 \
   --http-addr=localhost:8081 \
   --join=localhost:26257,localhost:26258,localhost:26259
   
   $ cockroach start \
   --certs-dir=certs \
   --store=node3 \
   --listen-addr=localhost:26259 \
   --http-addr=localhost:8082 \
   --join=localhost:26257,localhost:26258,localhost:26259
   
   These commands are the same as before but with unique --store, --listen-addr, and --http-addr flags, since this all nodes are running on the same machine. Also, since all nodes use the same hostname (localhost), you can use the first node’s certificate. Note that this is different than running a production cluster, where you would need to generate a certificate and key for each node, issued to all common names and IP addresses you might use to refer to the node as well as to any load balancer instances.
4. Open the :
   $ cockroach sql --certs-dir=certs --host=localhost:26257
   
5. Update preconfigured to replicate user data 3 times and import internal data 5 times:
   ALTER RANGE default CONFIGURE ZONE USING num_replicas = 3;
   ALTER DATABASE system CONFIGURE ZONE USING num_replicas = 5;
   ALTER RANGE meta CONFIGURE ZONE USING num_replicas = 5;
   ALTER RANGE system CONFIGURE ZONE USING num_replicas = 5;
   ALTER RANGE liveness CONFIGURE ZONE USING num_replicas = 5;
   ALTER TABLE system.public.replication_constraint_stats CONFIGURE ZONE DISCARD;
   ALTER TABLE system.public.replication_constraint_stats CONFIGURE ZONE USING gc.ttlseconds = 600, constraints = '[]', lease_preferences = '[]';
   ALTER TABLE system.public.replication_stats CONFIGURE ZONE DISCARD;
   ALTER TABLE system.public.replication_stats CONFIGURE ZONE USING gc.ttlseconds = 600, constraints = '[]', lease_preferences = '[]';
   
6. Stop the single-node cluster: Get the process ID of the node:
   ps -ef | grep cockroach | grep -v grep
   
     501 19584     1   0  6:13PM ttys001    0:01.27 cockroach start-single-node --insecure --listen-addr=localhost:26257 --http-addr=localhost:8080
   
   Gracefully shut down the node, specifying its process ID:
   kill -TERM 19584
   
   initiating graceful shutdown of server
   server drained and shutdown completed
   
7. Restart the node with the command:
   $ cockroach start \
   --insecure \
   --listen-addr=localhost:26257 \
   --http-addr=localhost:8080 \
   --join=localhost:26257,localhost:26258,localhost:26259
   
   The new flag to note is --join, which specifies the addresses and ports of the nodes that will comprise your cluster. You’ll use this exact --join flag when starting other nodes as well.
8. In new terminal windows, add two more nodes:
   $ cockroach start \
   --insecure \
   --store=node2 \
   --listen-addr=localhost:26258 \
   --http-addr=localhost:8081 \
   --join=localhost:26257,localhost:26258,localhost:26259
   
   $ cockroach start \
   --insecure \
   --store=node3 \
   --listen-addr=localhost:26259 \
   --http-addr=localhost:8082 \
   --join=localhost:26257,localhost:26258,localhost:26259
   
   These commands are the same as before but with unique --store, --listen-addr, and --http-addr flags, since this all nodes are running on the same machine.
9. Open the :
   $ cockroach sql --insecure --host=localhost:26257
   
10. Update preconfigured to replicate user data 3 times and import internal data 5 times:
    ALTER RANGE default CONFIGURE ZONE USING num_replicas = 3;
    ALTER DATABASE system CONFIGURE ZONE USING num_replicas = 5;
    ALTER RANGE meta CONFIGURE ZONE USING num_replicas = 5;
    ALTER RANGE system CONFIGURE ZONE USING num_replicas = 5;
    ALTER RANGE liveness CONFIGURE ZONE USING num_replicas = 5;
    ALTER TABLE system.public.replication_constraint_stats CONFIGURE ZONE DISCARD;
    ALTER TABLE system.public.replication_constraint_stats CONFIGURE ZONE USING gc.ttlseconds = 600, constraints = '[]', lease_preferences = '[]';
    ALTER TABLE system.public.replication_stats CONFIGURE ZONE DISCARD;
    ALTER TABLE system.public.replication_stats CONFIGURE ZONE USING gc.ttlseconds = 600, constraints = '[]', lease_preferences = '[]';
    ALTER TABLE system.public.tenant_usage CONFIGURE ZONE DISCARD;
    ALTER TABLE system.public.tenant_usage CONFIGURE ZONE USING gc.ttlseconds = 7200, constraints = '[]', lease_preferences = '[]';
    

​

See also

• Running a local multi-node cluster:
• Running a distributed multi-node cluster: