Distributed SQLadvanced

CockroachDB Operations

Rolling upgrades, node replacement, backup and restore, schema changes and the metrics that matter.

2 min readAdvancedUpdated 31 Jul 2026Edit this page

Node lifecycle

# Remove a node gracefully: ranges are moved off before it leaves.
cockroach node decommission <node-id> --certs-dir=certs --host=…
 
cockroach node status --decommission --certs-dir=certs

Adding a node is the reverse: start it with the right locality flags and the cluster rebalances ranges onto it automatically.

Rolling upgrades

CockroachDB supports upgrading one node at a time within a supported version step:

Confirm the cluster is healthy and fully replicated.
Upgrade nodes one at a time, waiting for each to rejoin and for replication to settle.
Verify the cluster runs entirely on the new version.
Finalise the upgrade, which enables new-version features and makes downgrade impossible.

Backup and restore

BACKUP DATABASE shop INTO 's3://acme-backups/crdb?AWS_ACCESS_KEY_ID=…&AWS_SECRET_ACCESS_KEY=…'
  AS OF SYSTEM TIME '-10s';
 
-- Incremental into the same collection.
BACKUP DATABASE shop INTO LATEST IN 's3://acme-backups/crdb?…';
 
-- Scheduled.
CREATE SCHEDULE shop_backup FOR BACKUP DATABASE shop
  INTO 's3://acme-backups/crdb?…'
  RECURRING '@daily' FULL BACKUP '@weekly';
 
SHOW BACKUPS IN 's3://acme-backups/crdb?…';
RESTORE DATABASE shop FROM LATEST IN 's3://acme-backups/crdb?…';

AS OF SYSTEM TIME '-10s' takes the backup from a slightly stale timestamp, which avoids contending with in-flight transactions. Backups are cluster-consistent — a genuine advantage over per-shard snapshot systems.

Enterprise features gate some capabilities (incremental and scheduled backups have varied by licence); confirm what your licence includes before designing around them.

Schema changes

Schema changes run as background jobs and do not hold long locks. They are asynchronous, so "the statement returned" does not mean "the change is complete":

SHOW JOBS WHERE job_type = 'SCHEMA CHANGE';
CANCEL JOB <job-id>;

Adding a column with a default, creating an index and backfilling all happen in the background and consume cluster resources. Start them during low traffic and watch the job's progress.