cockroach node

The cockroach node command provides tools for managing nodes in a CockroachDB cluster.

Synopsis

cockroach node [command] [flags]

Description

The node command supports several subcommands for cluster node management:

ls - List node IDs
status - Show detailed node status
decommission - Safely remove nodes from cluster
recommission - Cancel node decommissioning
drain - Prepare node for shutdown

Subcommands

node ls

List IDs of all active nodes in the cluster.

cockroach node ls [flags]

Example:

cockroach node ls --host=localhost:26257 --insecure

Output:

  id
------
   1
   2
   3

Only shows active (non-decommissioned) nodes. Use node status --decommission to see all nodes.

node status

Display detailed status information for one or all nodes.

cockroach node status [node-id] [flags]

Flags

--decommission

boolean

default:"false"

Include decommissioning and decommissioned nodes in output.

--ranges

boolean

default:"false"

Include range distribution information.

--stats

boolean

default:"false"

Include storage statistics.

--all

boolean

default:"false"

Include all information (ranges, stats, decommission status).

Examples

cockroach node status --insecure

Sample Output

  id |     address     |   sql_address   |  build  |         started_at         |         updated_at         | locality | attrs | is_available | is_live
-----+-----------------+-----------------+---------+----------------------------+----------------------------+----------+-------+--------------+----------
   1 | localhost:26257 | localhost:26257 | v23.1.0 | 2024-03-01 10:00:00+00:00 | 2024-03-01 12:30:00+00:00 |          |       |     true     |  true
   2 | localhost:26258 | localhost:26258 | v23.1.0 | 2024-03-01 10:00:30+00:00 | 2024-03-01 12:30:00+00:00 |          |       |     true     |  true
   3 | localhost:26259 | localhost:26259 | v23.1.0 | 2024-03-01 10:01:00+00:00 | 2024-03-01 12:30:00+00:00 |          |       |     true     |  true

node decommission

Safely remove one or more nodes from the cluster by transferring their range replicas to other nodes.

cockroach node decommission <node-id> [<node-id>...] [flags]
cockroach node decommission --self [flags]

Decommissioning is a permanent operation. Recommissioning is only possible if the decommissioning process hasn’t completed.

Flags

--self

boolean

default:"false"

Decommission the node you’re connected to.

--wait

string

default:"all"

How long to wait for decommissioning to complete.Options:

all - Wait until fully decommissioned (default)
none - Start decommissioning and return immediately

--checks

string

default:"skip"

Pre-decommission readiness checks.Options:

skip - No pre-checks (default)
enabled - Run checks, warn on issues
strict - Run checks, fail if issues detected

--dry-run

boolean

default:"false"

Show decommission status without actually decommissioning.

Examples

cockroach node decommission 4 --host=localhost:26257 --insecure

Decommissioning Process

The decommissioning process involves several stages:

Pre-checks (if enabled): Verify cluster can handle node removal
Replica transfer: Move range replicas to other nodes
Drain: Close SQL connections and reject new ones
Mark decommissioned: Finalize node removal

Progress Output

  id | is_live | replicas | is_decommissioning | membership | is_draining
-----+---------+----------+--------------------+------------+--------------
   4 |  true   |   156    |        true        |  active    |    false
.
  id | is_live | replicas | is_decommissioning | membership | is_draining
-----+---------+----------+--------------------+------------+--------------
   4 |  true   |    42    |        true        |  active    |    false
.
  id | is_live | replicas | is_decommissioning | membership | is_draining
-----+---------+----------+--------------------+------------+--------------
   4 |  true   |     0    |        true        |  active    |    true

No more data reported on target nodes. Please verify cluster health before removing the nodes.

Dots (.) indicate progress without status changes. The process completes when replica count reaches zero.

node recommission

Cancel decommissioning for nodes that haven’t fully decommissioned yet.

cockroach node recommission <node-id> [<node-id>...] [flags]
cockroach node recommission --self [flags]

Recommissioning only works if the node hasn’t fully decommissioned. Once decommissioning completes, the node cannot be recommissioned.

Examples

cockroach node recommission 4 --insecure

node drain

Prepare a node for shutdown by draining client connections and transferring range leases.

cockroach node drain [node-id] [flags]
cockroach node drain --self [flags]

Draining prepares for shutdown but doesn’t stop the process. Use your service manager or send SIGTERM to actually stop the node.

Flags

--self

boolean

default:"false"

Drain the node you’re connected to.

--shutdown

boolean

default:"false"

Shutdown the node after draining completes.

--drain-wait

duration

Maximum time to wait for drain to complete.

Examples

cockroach node drain 3 --insecure

What Draining Does

Stop accepting new SQL connections
Close existing SQL connections gracefully
Transfer range leases to other nodes
Wait for in-flight operations to complete

Output

drain ok

Or with --shutdown:

drain ok
shutdown ok

Connection Flags

All node subcommands support standard connection flags:

--host

string

default:"localhost:26257"

Node to connect to (can be any node in cluster).

--certs-dir

string

default:"${HOME}/.cockroach-certs"

Certificate directory for secure connections.

--insecure

boolean

default:"false"

Connect without encryption.

Best Practices

Decommissioning Best Practices:

Run --checks=strict before decommissioning production nodes
Monitor cluster health during decommissioning
Ensure sufficient capacity on remaining nodes
Decommission nodes one at a time for safety
Verify with node status --decommission after completion

Important Considerations:

Capacity: Ensure remaining nodes can handle additional replicas
Replication Factor: Maintain enough nodes for configured replication
Timing: Decommissioning can take hours for nodes with large datasets
Monitoring: Watch cluster metrics during the process

Troubleshooting

Decommissioning Stalled

If replica count stops decreasing:

Check cluster health: cockroach node status --all
Review logs for errors
Verify remaining nodes have capacity
Check network connectivity between nodes
Review range allocation with --ranges flag

Cannot Drain Node

Ensure node is still responsive
Check for long-running transactions
Verify cluster settings for drain timeouts
Review server logs for detailed errors

Recommission Failed

Verify node hasn’t fully decommissioned
Check node is still in cluster membership
Ensure node process is still running

Contributing

CLI Reference

Synopsis

Description

Subcommands

node ls

node status

Flags

Examples

Sample Output

node decommission

Flags

Examples

Decommissioning Process

Progress Output

node recommission

Examples

node drain

Flags

Examples

What Draining Does

Output

Connection Flags

Best Practices

Troubleshooting

Decommissioning Stalled

Cannot Drain Node

Recommission Failed

See Also

Build docs developers (and LLMs) love

Contributing

CLI Reference

​Synopsis

​Description

​Subcommands

​node ls

​node status

​Flags

​Examples

​Sample Output

​node decommission

​Flags

​Examples

​Decommissioning Process

​Progress Output

​node recommission

​Examples

​node drain

​Flags

​Examples

​What Draining Does

​Output

​Connection Flags

​Best Practices

​Troubleshooting

​Decommissioning Stalled

​Cannot Drain Node

​Recommission Failed

​See Also

Build docs developers (and LLMs) love

Synopsis

Description

Subcommands

node ls

node status

Flags

Examples

Sample Output

node decommission

Flags

Examples

Decommissioning Process

Progress Output

node recommission

Examples

node drain

Flags

Examples

What Draining Does

Output

Connection Flags

Best Practices

Troubleshooting

Decommissioning Stalled

Cannot Drain Node

Recommission Failed

See Also