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

# SHOW 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 = "v25.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>

The `SHOW VIRTUAL CLUSTER` statement lists all virtual clusters running in a CockroachDB cluster. `SHOW VIRTUAL CLUSTER` supports inspecting virtual cluster status only as part of the <InternalLink path="physical-cluster-replication-overview">**physical cluster replication (PCR)**</InternalLink> workflow.

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

`SHOW VIRTUAL CLUSTER` requires either:

* The `admin` role.
* The `MANAGEVIRTUALCLUSTER` <InternalLink path="security-reference/authorization#privileges">system privilege</InternalLink>.

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

<ShowVirtualCluster />

## Parameters

| Parameter                | Description                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `virtual\_cluster\_spec` | The name of the virtual cluster.                                                                                       |
| `REPLICATION STATUS`     | Display the details of a replication stream.                                                                           |
| `CAPABILITIES`           | Display the <InternalLink path="create-virtual-cluster#capabilities">capabilities</InternalLink> of a virtual cluster. |

## Responses

This table lists all possible responses from the different `SHOW VIRTUAL CLUSTER` statements:

| Field                  | Response                                                                                                                                                                                                                                                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | The ID of a virtual cluster.                                                                                                                                                                                                                                                                                    |
| `name`                 | The name of the standby (destination) virtual cluster.                                                                                                                                                                                                                                                          |
| `data\_state`          | The state of the data on a virtual cluster. This can show one of the following: `initializing replication`, `ready`, `replicating`, `replication paused`, `replication pending failover`, `replication failing over`, `replication error`. Refer to [Data state](#data-state) for more detail on each response. |
| `service\_mode`        | The service mode shows whether a virtual cluster is ready to accept SQL requests. This can show `none` or `shared`. When `shared`, a virtual cluster's SQL connections will be served by the same nodes that are serving the system virtual cluster.                                                            |
| `source\_tenant\_name` | The name of the primary (source) virtual cluster.                                                                                                                                                                                                                                                               |
| `source\_cluster\_uri` | The URI of the primary (source) cluster. The standby cluster connects to the primary cluster using this URI when <InternalLink path="set-up-physical-cluster-replication#step-4-start-replication">starting a replication stream</InternalLink>.                                                                |
| `replicated\_time`     | The latest timestamp at which the standby cluster has consistent data — that is, the latest time you can fail over to. This time advances automatically as long as the replication proceeds without error. `replicated\_time` is updated periodically (every `30s`).                                            |
| `retained\_time`       | The earliest timestamp at which the standby cluster has consistent data — that is, the earliest time you can fail over to.                                                                                                                                                                                      |
| `replication\_lag`     | The time between the most up-to-date replicated time and the actual time. Refer to the <InternalLink path="physical-cluster-replication-technical-overview">Technical Overview</InternalLink> for more detail.                                                                                                  |
| `failover\_time`       | The time at which the failover will begin. This can be in the past or the future. Refer to <InternalLink path="failover-replication#fail-over-to-a-point-in-time">Fail over to a point in time</InternalLink>.                                                                                                  |
| `status`               | The status of the replication stream. This can show one of the following: `initializing replication`, `ready`, `replicating`, `replication paused`, `replication pending failover`, `replication failing over`, `replication error`. Refer to [Data state](#data-state) for more detail on each response.       |
| `capability\_name`     | The <InternalLink path="create-virtual-cluster#capabilities">capability</InternalLink> name.                                                                                                                                                                                                                    |
| `capability\_value`    | Whether the <InternalLink path="create-virtual-cluster#capabilities">capability</InternalLink> is enabled for a virtual cluster.                                                                                                                                                                                |

<Tip>
  To find the job ID for the replication stream, use the <InternalLink path="show-jobs">`SHOW JOBS`</InternalLink> statement. For example:
</Tip>

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SELECT * FROM [SHOW JOBS] WHERE job_type = 'REPLICATION STREAM INGESTION';
```

### Data state

The `data_state` and `status` fields show the current state of a virtual cluster's data and progress of the replication stream job.

| State                          | Description                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add`                          | (<InternalLink version="releases" path="cockroachdb-feature-availability">**Preview**</InternalLink>) The <InternalLink path="create-virtual-cluster#start-a-pcr-stream-with-read-from-standby">`readonly` virtual cluster</InternalLink> is waiting for the PCR job's initial scan to complete, then `readonly` will be available for read queries. |
| `initializing replication`     | The replication job is completing the initial scan of data from the primary cluster before it starts replicating data in real time.                                                                                                                                                                                                                  |
| `ready`                        | A virtual cluster's data is ready for use. The `readonly` virtual cluster is ready to serve read queries.                                                                                                                                                                                                                                            |
| `replicating`                  | The replication job has started and is replicating data.                                                                                                                                                                                                                                                                                             |
| `replication paused`           | The replication job is paused due to an error or a manual request with <InternalLink path="alter-virtual-cluster">`ALTER VIRTUAL CLUSTER ... PAUSE REPLICATION`</InternalLink>.                                                                                                                                                                      |
| `replication pending failover` | The replication job is running and the failover time has been set. Once the the replication reaches the failover time, the failover will begin automatically.                                                                                                                                                                                        |
| `replication failing over`     | The job has started failing over. The failover time can no longer be changed. Once failover is complete, a virtual cluster will be available for use with <InternalLink path="alter-virtual-cluster">`ALTER VIRTUAL CLUSTER ... START SERVICE SHARED`</InternalLink>.                                                                                |
| `replication error`            | An error has occurred. You can find more detail in the error message and the <InternalLink path="configure-logs">logs</InternalLink>. **Note:** A PCR job will retry for 3 minutes before failing.                                                                                                                                                   |

## Examples

### Show all virtual clusters

List all virtual clusters:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SHOW VIRTUAL CLUSTERS;
```

### Show a virtual cluster

To show more details about the `main` virtual cluster:

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

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  id | name | data_state  | service_mode
-----+------+-------------+---------------
   3 | main | replicating | none
(1 row)
```

### Show replication status

To show the replication status of all virtual clusters:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SHOW VIRTUAL CLUSTERS WITH REPLICATION STATUS;
```

To show the replication status of the `main` virtual cluster:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SHOW VIRTUAL CLUSTER main WITH REPLICATION STATUS;
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  id | name | source_tenant_name |              source_cluster_uri               |         retained_time         |    replicated_time     | replication_lag | failover_time |   status
-----+------+--------------------+-----------------------------------------------+-------------------------------+------------------------+-----------------+--------------+--------------
   3 | main | main               | postgresql://user@hostname or IP:26257?redacted | 2024-04-18 10:07:45.000001+00 | 2024-04-18 14:07:45+00 | 00:00:19.602682 |         NULL | replicating
(1 row)
```

## See also

* <InternalLink path="physical-cluster-replication-monitoring">Physical Cluster Replication Monitoring</InternalLink>
* <InternalLink path="physical-cluster-replication-overview">Physical Cluster Replication Overview</InternalLink>
* <InternalLink path="set-up-physical-cluster-replication">Set Up Physical Cluster Replication</InternalLink>