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

# ALTER VIRTUAL CLUSTER

> [!NOTE]
>
> **This feature is in [preview](https://docs.cockroachlabs.com/docs/releases/cockroachdb-feature-availability.md)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).

The `ALTER VIRTUAL CLUSTER` statement initiates a [*cutover*](#start-the-cutover-process) or [*cutback*](#start-the-cutback-process) in a [**physical cluster replication (PCR)** job](https://docs.cockroachlabs.com/docs/v24.2/set-up-physical-cluster-replication) 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](https://docs.cockroachlabs.com/docs/v24.2/physical-cluster-replication-overview).

## Required privileges

`ALTER VIRTUAL CLUSTER` requires one of the following privileges:

* The `admin` role.
* The `MANAGEVIRTUALCLUSTER` [system privilege](https://docs.cockroachlabs.com/docs/v24.2/security-reference/authorization#privileges) allows the user to run all the related `VIRTUAL CLUSTER` SQL statements for PCR.

Use the [`GRANT SYSTEM`](https://docs.cockroachlabs.com/docs/v24.2/grant) statement:

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

## Synopsis

![alter\_virtual\_cluster syntax diagram](https://mintcdn.com/cockroachlabs/dDCrgWEBNNTyyvfp/images/sql-diagrams/v24.2/alter_virtual_cluster.svg?fit=max\&auto=format\&n=dDCrgWEBNNTyyvfp\&q=85\&s=6e5d79fccca8766e1835c19842f4da1a)

## 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: <ul><li>`SYSTEM TIME` to specify a [timestamp](https://docs.cockroachlabs.com/docs/v24.2/as-of-system-time). Refer to [Cut over to a point in time](https://docs.cockroachlabs.com/docs/v24.2/cutover-replication#cut-over-to-a-point-in-time) for an example.</li><li>`LATEST` to specify the most recent replicated timestamp. Refer to [Cut over to a point in time](https://docs.cockroachlabs.com/docs/v24.2/cutover-replication#cut-over-to-the-most-recent-replicated-time) 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 [cutback](https://docs.cockroachlabs.com/docs/v24.2/cutover-replication#cutback) process. This command fails if the virtual cluster was not originally replicated from the original primary cluster. |
| `START SERVICE SHARED` | Start a virtual cluster so it is ready to accept SQL connections after cutover. |
| `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 [capabilities](https://docs.cockroachlabs.com/docs/v24.2/create-virtual-cluster#capabilities). |
| `REVOKE ALL CAPABILITIES` | Revoke all [capabilities](https://docs.cockroachlabs.com/docs/v24.2/create-virtual-cluster#capabilities) from a virtual cluster. |
| `GRANT CAPABILITY virtual_cluster_capability_list` | Specify a [capability](https://docs.cockroachlabs.com/docs/v24.2/create-virtual-cluster#capabilities) to grant to a virtual cluster. |
| `REVOKE CAPABILITY virtual_cluster_capability_list` | Revoke a [capability](https://docs.cockroachlabs.com/docs/v24.2/create-virtual-cluster#capabilities) from a virtual cluster. |

## Examples

### Start the cutover process

To start the [cutover](https://docs.cockroachlabs.com/docs/v24.2/cutover-replication) process, 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 {cutover time specification};
```

You can use either:

* `SYSTEM TIME` to specify a [timestamp](https://docs.cockroachlabs.com/docs/v24.2/as-of-system-time).
* `LATEST` to specify the most recent replicated timestamp.

When a virtual cluster is [`ready`](https://docs.cockroachlabs.com/docs/v24.2/show-virtual-cluster#responses) after initiating the cutover process, you must start the service so that the virtual cluster is ready to accept SQL connections:

```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 cutback process

To [cut back](https://docs.cockroachlabs.com/docs/v24.2/cutover-replication#cutback) 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 cutover from the primary cluster.

> [!NOTE]
>
> 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](https://docs.cockroachlabs.com/docs/v24.2/cutover-replication) section for instructions.

## See also

* [Physical Cluster Replication Overview](https://docs.cockroachlabs.com/docs/v24.2/physical-cluster-replication-overview)
* [`CREATE VIRTUAL CLUSTER`](https://docs.cockroachlabs.com/docs/v24.2/create-virtual-cluster)
* [`DROP VIRTUAL CLUSTER`](https://docs.cockroachlabs.com/docs/v24.2/drop-virtual-cluster)
* [`SHOW VIRTUAL CLUSTER`](https://docs.cockroachlabs.com/docs/v24.2/show-virtual-cluster)