Skip to main content
This feature is in preview and subject to change. To share feedback and/or issues, contact Support.
The ALTER VIRTUAL CLUSTER statement initiates a cutover or cutback in a physical cluster replication (PCR) job and manages a virtual cluster. PCR happens between an active primary cluster and a passive standby cluster that accepts updates from the primary cluster. The unit of replication is a virtual cluster, which is part of the underlying infrastructure in the primary and standby clusters. The CockroachDB cluster has:
  • The system virtual cluster manages the cluster’s control plane and the replication of the cluster’s data. Admins connect to the system virtual cluster to configure and manage the underlying CockroachDB cluster, set up PCR, create and manage a virtual cluster, and observe metrics and logs for the CockroachDB cluster and each virtual cluster.
  • Each other virtual cluster manages its own data plane. Users connect to a virtual cluster by default, rather than the system virtual cluster. To connect to the system virtual cluster, the connection string must be modified. Virtual clusters contain user data and run application workloads. When PCR is enabled, the non-system virtual cluster on both primary and secondary clusters is named main.
For more detail, refer to the Physical Cluster Replication Overview.

​
Required privileges

ALTER VIRTUAL CLUSTER requires one of the following privileges:
  • The admin role.
  • The MANAGEVIRTUALCLUSTER system privilege allows the user to run all the related VIRTUAL CLUSTER SQL statements for PCR.
Use the GRANT SYSTEM statement:

​
Synopsis

alter_virtual_cluster syntax diagram

​
Parameters

​
Examples

​
Start the cutover process

To start the cutover process, use COMPLETE REPLICATION and provide the timestamp to restore as of:
You can use either:
  • SYSTEM TIME to specify a timestamp.
  • LATEST to specify the most recent replicated timestamp.
When a virtual cluster is ready after initiating the cutover process, you must start the service so that the virtual cluster is ready to accept SQL connections:
To stop the shared service for a virtual cluster and prevent it from accepting SQL connections:

​
Start the cutback process

To cut back to a cluster that was previously the primary cluster, use the ALTER VIRTUAL CLUSTER syntax:
The original primary virtual cluster may be almost up to date with the promoted standby’s virtual cluster. The difference in data between the two virtual clusters will include only the writes that have been applied to the promoted standby after cutover from the primary cluster.
If you started the original PCR stream on an existing cluster without virtualization enabled, refer to the Cut back after PCR from an existing cluster section for instructions.

​
See also