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

# ALTER VIRTUAL CLUSTER

export const InlineImage = ({src, alt = "", height = "1.6em"}) => {
  return <img noZoom src={src} alt={alt} style={{
    display: "inline",
    verticalAlign: "start",
    height: height,
    margin: "0"
  }} />;
};

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 = "v23.2";

<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>

<InlineImage alt="Megaphone" src="/images/common/icon-megaphone.png" /> New in v23.2: The `ALTER VIRTUAL CLUSTER` statement initiates a cutover 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.
* 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 `application`.

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

## Required privileges

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

* The `admin` role.
* The `MANAGEVIRTUALCLUSTER` <InternalLink path="security-reference/authorization#privileges">system privilege</InternalLink> allows the user to run all the related `VIRTUAL CLUSTER` SQL statements for PCR.

Use the <InternalLink path="grant">`GRANT SYSTEM`</InternalLink> statement:

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

## Synopsis

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

<AlterVirtualCluster />

## 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="cutover-replication#cut-over-to-a-point-in-time">Cut over to a point in time</InternalLink> for an example.</li><li>`LATEST` to specify the most recent replicated timestamp. Refer to <InternalLink path="cutover-replication#cut-over-to-the-most-recent-replicated-time">Cut over to a point in time</InternalLink> for an example.</li></ul> |
| `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.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `RENAME TO virtual\_cluster\_spec`                     | Rename a virtual cluster.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `START SERVICE SHARED`                                 | Start a virtual cluster. That is, start the standby's virtual cluster so it is ready to accept SQL connections after cutover.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `STOP SERVICE`                                         | Stop the `shared` service for a virtual cluster. Note that the virtual cluster's `data\_state` will remain as `ready` for the service to be started once again.                                                                                                                                                                                                                                                                                                                                                                        |

## Examples

### Start the cutover process

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

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER VIRTUAL CLUSTER application COMPLETE REPLICATION TO {cutover 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.

When a virtual cluster is <InternalLink path="show-virtual-cluster#responses">`ready`</InternalLink> 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 application 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 application STOP SERVICE;
```

## 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>