> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ALTER VIRTUAL CLUSTER

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

export const version = "v26.1";

<Note>
  **This feature is in <InternalLink path="cockroachdb-feature-availability">preview</InternalLink>** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
</Note>

The `ALTER VIRTUAL CLUSTER` statement initiates a [*failover*](#start-the-failover-process) or [*failback*](#start-the-failback-process) in a <InternalLink path="set-up-physical-cluster-replication">**physical cluster replication (PCR)** job</InternalLink> 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.
* The application virtual cluster manages the cluster’s data plane. Application virtual clusters contain user data and run application workloads.

For more detail, refer to the <InternalLink path="physical-cluster-replication-overview">Physical Cluster Replication Overview</InternalLink>.

## Required privileges

To run the `ALTER VIRTUAL CLUSTER` statement from the standby cluster, users require the `REPLICATIONDEST` system <InternalLink path="security-reference/authorization">privilege</InternalLink> **and** the `MANAGEVIRTUALCLUSTER` privilege.

Use the <InternalLink path="grant">`GRANT SYSTEM`</InternalLink> statement to grant the necessary privileges, for example:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SYSTEM MANAGEVIRTUALCLUSTER TO user;
```

## Synopsis

xml version="1.0" encoding="UTF-8"?

<img src="https://mintlify.s3.us-west-1.amazonaws.com/cockroachlabs/images/generated/docs/v26.1/alter-virtual-cluster/syntax-diagram-d7306dd8b92b.svg" alt="SQL syntax diagram" />

## 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: <br /><ul><li>`SYSTEM TIME` to specify a <InternalLink path="as-of-system-time">timestamp</InternalLink>. Refer to <InternalLink path="failover-replication#fail-over-to-a-point-in-time">Fail over to a point in time</InternalLink> for an example.</li><li>`LATEST` to specify the most recent replicated timestamp. Refer to <InternalLink path="failover-replication#fail-over-to-the-most-recent-replicated-time">Fail over to a point in time</InternalLink> for an example.</li></ul> |
| `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 <InternalLink path="failover-replication#failback">failback</InternalLink> process. This command fails if the virtual cluster was not originally replicated from the original primary cluster. Refer to [Options](#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 <InternalLink path="create-virtual-cluster#capabilities">capabilities</InternalLink>.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `REVOKE ALL CAPABILITIES`                                          | Revoke all <InternalLink path="create-virtual-cluster#capabilities">capabilities</InternalLink> from a virtual cluster.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GRANT CAPABILITY virtual\_cluster\_capability\_list`              | Specify a <InternalLink path="create-virtual-cluster#capabilities">capability</InternalLink> to grant to a virtual cluster.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `REVOKE CAPABILITY virtual\_cluster\_capability\_list`             | Revoke a <InternalLink path="create-virtual-cluster#capabilities">capability</InternalLink> 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 <InternalLink path="failover-replication#failback">failback process</InternalLink>.

| Option                 | Value | Description                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `READ VIRTUAL CLUSTER` | N/A   | (<InternalLink path="cockroachdb-feature-availability">**Preview**</InternalLink>) 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](#start-the-failback-process). |

## Examples

### Start the failover process

To start the <InternalLink path="failover-replication#failover">failover</InternalLink> process from the standby cluster, use `COMPLETE REPLICATION` and provide the timestamp to restore as of:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER VIRTUAL CLUSTER main COMPLETE REPLICATION TO {failover time specification};
```

You can use either:

* `SYSTEM TIME` to specify a <InternalLink path="as-of-system-time">timestamp</InternalLink>.
* `LATEST` to specify the most recent replicated timestamp.

<Note>
  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.
</Note>

When a virtual cluster is <InternalLink path="show-virtual-cluster#responses">`ready`</InternalLink> after initiating the failover process, you must start the service so that the virtual cluster is ready to accept SQL connections. On the standby cluster, run:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER VIRTUAL CLUSTER main START SERVICE SHARED;
```

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

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER VIRTUAL CLUSTER main STOP SERVICE;
```

### Start the failback process

To <InternalLink path="failover-replication#failback">fail back</InternalLink> to a cluster that was previously the primary cluster, use the `ALTER VIRTUAL CLUSTER` syntax:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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.

(<InternalLink path="cockroachdb-feature-availability">**Preview**</InternalLink>) 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.

<Note>
  If you started the original PCR stream on an existing cluster without virtualization enabled, refer to the <InternalLink path="failover-replication">Fail back after PCR from an existing cluster</InternalLink> section for instructions.
</Note>

## See also

* <InternalLink path="physical-cluster-replication-overview">Physical Cluster Replication Overview</InternalLink>
* <InternalLink path="create-virtual-cluster">`CREATE VIRTUAL CLUSTER`</InternalLink>
* <InternalLink path="drop-virtual-cluster">`DROP VIRTUAL CLUSTER`</InternalLink>
* <InternalLink path="show-virtual-cluster">`SHOW VIRTUAL CLUSTER`</InternalLink>