Manage Physical Cluster Replication

Physical cluster replication (PCR) enables continuous replication of data from an active primary cluster to a passive standby cluster, supporting high availability and disaster recovery scenarios. This page describes:

• Connecting to and interacting with the system virtual cluser and virtual clusters on each physical cluster.
• Managing PCR using SQL statements.
• Upgrading CockroachDB on both the primary and standby clusters.

Connection reference

This table outlines the connection strings to connect to the primary and standby cluster's virtual clusters.

The table uses main as an example name for the virtual cluster that contains user table data in the primary and standby clusters.

Cluster	Virtual Cluster	Usage	URL and Parameters
Primary	System	Set up a replication user and view running virtual clusters. Connect with cockroach sql.	"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=system&sslmode=verify-full" options=-ccluster=system sslmode=verify-full Use the --certs-dir flag to specify the path to your certificate.
Primary	Main	Add and run a workload with cockroach workload.	"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main&sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.root.crt&sslkey=certs/client.root.key" The cockroach workload command does not support connection or security flags like other cockroach commands. Instead, you must use a connection string at the end of the command. As a result, for the example in this tutorial, you will need: options=-ccluster={virtual_cluster_name} sslmode=verify-full sslrootcert={path}/certs/ca.crt sslcert={path}/certs/client.root.crt sslkey={path}/certs/client.root.key
Standby	System	Manage the replication stream. Connect with cockroach sql.	"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=system&sslmode=verify-full" options=-ccluster=system sslmode=verify-full Use the --certs-dir flag to specify the path to your certificate.
Standby/Primary	System	Connect to the other cluster.	"postgresql://{replication user}:{password}@{node IP or hostname}:{26257}/defaultdb?options=-ccluster%3Dsystem&sslinline=true&sslmode=verify-full&sslrootcert=-----BEGIN+CERTIFICATE-----{encoded_cert}-----END+CERTIFICATE-----%0A" Generate the connection string with cockroach encode-uri. Use the generated connection string in: CREATE VIRTUAL CLUSTER statements to start the replication stream. ALTER VIRTUAL CLUSTER statements to fail back to the primary cluster.
Standby	Read only	Run read queries on the standby's replicating virtual cluster	"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main-readonly&sslmode=verify-full" options=-ccluster=main-readonly sslmode=verify-full Use the --certs-dir flag to specify the path to your certificate.

For additional detail on the standard CockroachDB connection parameters, refer to Client Connection Parameters.

Manage replication in the SQL shell

To start, manage, and observe PCR, you can use the following SQL statements:

Statement	Action
CREATE VIRTUAL CLUSTER ... FROM REPLICATION OF ...	Start a PCR stream and configure the stream's behavior.
ALTER VIRTUAL CLUSTER	Pause and resume PCR streams, initiate a failover, and configure a running stream's behavior.
SHOW VIRTUAL CLUSTER	Show all virtual clusters and PCR stream status in the physical cluster.
DROP VIRTUAL CLUSTER	Remove a virtual cluster.

Upgrade the cluster version on the primary and standby

To upgrade the primary and standby clusters in PCR, complete the following steps in order:

Step 1. Upgrade the binary on both clusters

Upgrade the binary on every node in both the primary and standby clusters:

1. Replace the cockroach binary on each node.
2. Restart CockroachDB each node.

You can find more details on upgrading the binary in Perform a major-version upgrade.

Step 2. Finalize the upgrade on each virtual cluster

You must finalize the upgrade on each virtual cluster in this order:

1. Standby system virtual cluster
   
2. Primary system virtual cluster
   
3. Standby application virtual cluster
   
4. Primary application virtual cluster
   

Repeat these steps for each virtual cluster in the specified order. To finalize a virtual cluster:

1. Connect to the virtual cluster using the SQL shell:

   cockroach sql "<connection string>"
   

   Use the Connection reference to find the correct connection strings.

2. Run the following command, replacing {VERSION} with the target major version (e.g., v25.1):

   SET CLUSTER SETTING version = '{VERSION}';
   

This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster.

For more details on finalizing or rolling back the upgrade, refer to Upgrade CockroachDB self-hosted page.