ALTER VIRTUAL CLUSTER

This feature is in and subject to change. To share feedback and/or issues, contact Support.

The ALTER VIRTUAL CLUSTER statement initiates a failover or failback in a 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 .

Required privileges

ALTER VIRTUAL CLUSTER requires one of the following privileges:

• The admin role.
• The MANAGEVIRTUALCLUSTER allows the user to run all the related VIRTUAL CLUSTER SQL statements for PCR.

Use the statement:

GRANT SYSTEM MANAGEVIRTUALCLUSTER TO user;

Synopsis

<?xml version=“1.0” encoding=“UTF-8”?>

Parameters

Parameter	Description
virtual_cluster_spec	The virtual cluster’s name.
PAUSE REPLICATION	Pause the replication stream.
RESUME REPLICATION	Resume the replication stream.
COMPLETE REPLICATION TO	Set the time to complete the replication. Use: SYSTEM TIME to specify a . Refer to for an example. LATEST to specify the most recent replicated timestamp. Refer to for an example.
START REPLICATION OF virtual_cluster_spec ON physical_cluster	Reset a virtual cluster to the time when the virtual cluster on the promoted standby diverged from it. To reuse as much of the existing data on the original primary cluster as possible, you can run this statement as part of the process. This command fails if the virtual cluster was not originally replicated from the original primary cluster. Refer to Options for details on how you can configure a PCR stream initiated as a failback.
START SERVICE SHARED	Start a virtual cluster so it is ready to accept SQL connections after failover.
RENAME TO virtual_cluster_spec	Rename a virtual cluster.
STOP SERVICE	Stop the shared service for a virtual cluster. The virtual cluster’s data_state will still be ready so that the service can be restarted.
GRANT ALL CAPABILITIES	Grant a virtual cluster all .
REVOKE ALL CAPABILITIES	Revoke all from a virtual cluster.
GRANT CAPABILITY virtual_cluster_capability_list	Specify a to grant to a virtual cluster.
REVOKE CAPABILITY virtual_cluster_capability_list	Revoke a from a virtual cluster.

Options

You can use the following options with ALTER VIRTUAL CLUSTER {vc} START REPLICATION OF virtual_cluster_spec ON physical_cluster to initiate the .

Option	Value	Description
READ VIRTUAL CLUSTER	N/A	() Configure the PCR stream to allow reads from the standby cluster. Note: This only allows for reads on the standby’s virtual cluster. You cannot perform writes or schema changes to user tables while connected to the standby virtual cluster. For more details, refer to Start the failback process.

Examples

Start the failover process

To start the process, use COMPLETE REPLICATION and provide the timestamp to restore as of:

ALTER VIRTUAL CLUSTER main COMPLETE REPLICATION TO {failover time specification};

You can use either:

• SYSTEM TIME to specify a .
• LATEST to specify the most recent replicated timestamp.

If you started the PCR stream with the READ VIRTUAL CLUSTER option, failing over with SYSTEM TIME will destroy the readonly virtual cluster. If you fail over with LATEST, the readonly virtual cluster will remain on the original standby cluster, but will not update with new writes.

When a virtual cluster is after initiating the failover process, you must start the service so that the virtual cluster is ready to accept SQL connections:

ALTER VIRTUAL CLUSTER main START SERVICE SHARED;

To stop the shared service for a virtual cluster and prevent it from accepting SQL connections:

ALTER VIRTUAL CLUSTER main STOP SERVICE;

Start the failback process

To to a cluster that was previously the primary cluster, use the ALTER VIRTUAL CLUSTER syntax:

ALTER VIRTUAL CLUSTER {original_primary_vc} START REPLICATION OF {promoted_standby_vc} ON {connection_string_standby};

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 failover from the primary cluster.

() Use the READ VIRTUAL CLUSTER option with the ALTER VIRTUAL CLUSTER failback syntax to start a PCR stream that also creates a read-only virtual cluster on the standby cluster.

If you started the original PCR stream on an existing cluster without virtualization enabled, refer to the section for instructions.

See also