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

# Read from Standby

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>

In addition to providing <InternalLink path="failover-replication">failover</InternalLink> capabilities for <InternalLink path="disaster-recovery-overview">disaster recovery</InternalLink>, <InternalLink path="physical-cluster-replication-overview">**physical cluster replication (PCR)**</InternalLink> allows you to direct read-only queries to your standby cluster. This process offloads ad-hoc analytics query traffic from the primary cluster.

Use this page to understand how the *read from standby* feature works and how to utilize it.

## How the read from standby feature works

PCR utilizes <InternalLink path="cluster-virtualization-overview">cluster virtualization</InternalLink> to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a *system virtual cluster (system VC)*, and at least one data plane, called an *application virtual cluster (app VC)*. The standby cluster's system VC manages the PCR job and other cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's app VC are identical to the primary cluster's app VC. The standby cluster's app VC itself remains offline during replication.

When using read from standby, applications can read from the standby cluster, but they do not connect directly to the standby cluster's app VC. Instead, PCR introduces a *reader virtual cluster (reader VC)*. The reader VC ensures a clean, isolated environment specifically for serving read queries without interfering with replication or system metadata. It reads continuously from the standby cluster's app VC using internal pointers, providing access to the replicated data while keeping the app VC offline. The reader VC itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space.

The standby cluster's reader VC has its own system tables and <InternalLink path="cluster-settings">cluster settings</InternalLink>. The reader VC replicates a subset of system tables, including **Users** and **Roles**, from the app VC, so that existing primary users can authenticate using the same <InternalLink path="security-reference/authorization">users and roles</InternalLink> as on the primary cluster's app VC. Other system tables and cluster settings are set to defaults in the reader VC. For more information, consult <InternalLink path="physical-cluster-replication-technical-overview">Physical Cluster Replication Technical Overview</InternalLink>.

In the event of failover, the reader VC is destroyed.

## Use the read from standby feature

The read from standby feature allows you to increase PCR standby cluster hardware utilization during replication. However, PCR's primary use case is disaster recovery, not workload isolation. If you need a workload isolation solution but do not need disaster recovery, deploy a single cluster and use <InternalLink path="follower-reads">follower reads</InternalLink> instead.

### Before you begin

Prior to setting up read from standby, ensure that:

* You have already configured PCR between a *primary* cluster and a *standby* cluster. For information on configuring PCR, refer to <InternalLink path="set-up-physical-cluster-replication">Set Up Physical Cluster Replication</InternalLink>.
* Your CockroachDB version is v24.3 or later. The `read from standby` option is not supported in earlier versions.

### Start a PCR stream with read from standby

To start a PCR stream that allows read access to the standby cluster, use the <InternalLink path="create-virtual-cluster">`CREATE VIRTUAL CLUSTER... REPLICATION`</InternalLink> statement with the `READ VIRTUAL CLUSTER` option:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE VIRTUAL CLUSTER main FROM REPLICATION OF main ON 'postgresql://{connection string to primary}' WITH READ VIRTUAL CLUSTER;
```

### Add read from standby to a PCR stream

To add read from standby capabilities to an existing PCR stream, use the <InternalLink path="alter-virtual-cluster">`ALTER VIRTUAL CLUSTER`</InternalLink> statement:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;
```

<Note>
  The standby cluster's app VC must have a status of `replicating` before you can create your reader VC. Use the <InternalLink path="show-virtual-cluster">`SHOW VIRTUAL CLUSTERS`</InternalLink> command to check the status of the app VC.
</Note>

### Check the status of your reader virtual cluster

To confirm that your reader virtual cluster is active:

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

The output shows a `standby-readonly` virtual cluster in addition to the system VC and app VC:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  id |       name       | data_state  | service_mode
-----+------------------+-------------+---------------
   1 | system           | ready       | shared
   3 | standby          | replicating | none
   4 | standby-readonly | ready       | shared
```

<Note>
  The reader VC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the reader VC's `service_mode` is `shared`, then wait about one minute before connecting to the reader VC.
</Note>

### Run read-only queries on the standby cluster

Once you have created a reader virtual cluster on the standby cluster, you can connect to it and run <InternalLink path="selection-queries">read (`SELECT`) queries</InternalLink>. For example:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SELECT COUNT(*) FROM customers;
SELECT region, SUM(amount) FROM orders GROUP BY region;
```

The results of queries on the standby cluster reflect the state of the primary cluster as of a historical time that approaches the <InternalLink path="show-virtual-cluster#show-replication-status">replicated time</InternalLink>.

Write operations are not permitted on the standby cluster.

## See also

* <InternalLink path="set-up-physical-cluster-replication">Set Up Physical Cluster Replication</InternalLink>
* <InternalLink path="failover-replication">Fail Over from a Primary Cluster to a Standby Cluster</InternalLink>
* <InternalLink path="physical-cluster-replication-technical-overview">Physical Cluster Replication Technical Overview</InternalLink>
* <InternalLink path="create-virtual-cluster">`CREATE VIRTUAL CLUSTER`</InternalLink>
* <InternalLink path="alter-virtual-cluster">`ALTER VIRTUAL CLUSTER`</InternalLink>
* <InternalLink path="show-virtual-cluster">`SHOW VIRTUAL CLUSTER`</InternalLink>