Add new section on read from standby feature #20502

peachdawnleach · 2025-10-06T17:26:03Z

Adding information about the new read from standby feature in pcr

Added new pages and added them to the TOC

netlify · 2025-10-06T17:26:23Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`fbe26de`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/68e81233f1b8260008aa1b0e

netlify · 2025-10-06T17:26:24Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`fbe26de`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/68e812338172b500086c9c2e

github-actions · 2025-10-06T17:26:30Z

Files changed:

src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json
src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json
src/current/v25.3/read-from-standby.md
src/current/v25.4/read-from-standby.md

netlify · 2025-10-06T17:36:43Z

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	`90bf4d9`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/68e3fbaee727ec0008f6e24a

netlify · 2025-10-06T17:46:02Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`fbe26de`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/68e812332f284600086ff480
😎 Deploy Preview	https://deploy-preview-20502--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Fixed broken links

…om:cockroachdb/docs into 2025-10-01-doc-13854-add-read-from-standby

Build was failing because summary was too short

peachdawnleach · 2025-10-06T18:22:14Z

Preview: https://deploy-preview-20502--cockroachdb-docs.netlify.app/docs/stable/read-from-standby

msbutler

nice start!

src/current/v25.4/read-from-standby.md

msbutler · 2025-10-07T15:52:43Z

src/current/v25.4/read-from-standby.md

+
+### Check the status of your reader virtual cluster
+
+To confirm that your reader virtual cluster is active:


nit: we should add some language around the fact that the reader VC will only can serve reads after PCR initial scan completes. After the initial scan completes, use show virtual clusters to wait until the service mode is "shared" for the readerVC.

Then, the user should wait a minute to open a sql connection to the reader vc (i know, horrible ux).

unresolving. i don't see updated language on this.

msbutler · 2025-10-07T15:57:22Z

src/current/v25.4/read-from-standby.md

+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 the replicated time.


nit: i think a more accurate way to say this is: "reads are always served at a historical time approaches the replicated time." (its not quite the replicated time currently)

Would it be accurate to word this as "The results of queries on the standby cluster reflect the state of the primary cluster as of a historical time that approaches the replicated time"?

@msbutler is this due to the lag between primary and standby AND readervc?

@peachdawnleach yeah i like that language.

@alicia-l2 the lag between the AOST the user provides and the AOST actually used is due to a very annoying technical bug i really want to address. It has to do with the fact that the reader tenant descriptors are updated after the replicated data comes in on the replicating tenant.

msbutler · 2025-10-07T15:58:22Z

src/current/v25.4/read-from-standby.md

+The output provides the following information:
+- the replication status of the standby cluster
+- the timestamp of the most recently applied event on the standby cluster
+- any lag relative to the primary cluster


to see the replicated time used by reader queries specifically, we could point users to the resolved time posted by the standby poller job on the reader vc. maybe that's a follow up item for this page cc @alicia-l2

resolved time posted by the standby poller job on the reader vc.

how does one get to this?

run SHOW JOBS on the reader tenant. Or view the job on the db console of the reader tenant.

alicia-l2

great start! one thing to note is that we probably also have to edit the sql syntax pages as well for ALTER VIRTUAL CLUSTERhttps://deploy-preview-20502--cockroachdb-docs.netlify.app/docs/v25.3/alter-virtual-cluster

src/current/v25.3/read-from-standby.md

alicia-l2 · 2025-10-07T15:58:35Z

src/current/v25.3/read-from-standby.md

+
+## How the read from standby feature works
+
+PCR utilizes cluster virtualization to separate clusters' control planes from their data planes. A cluster always has one control plane, called a _system virtual cluster (SystemVC)_, and at least one data plane, called an _App Virtual Cluster (AppVC)_. A cluster's SystemVC manages PCR jobs and cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's AppVC are identical to the primary cluster's AppVC. The standby cluster's AppVC itself remains offline during replication.


The standby cluster's AppVC itself remains offline during replication.

we should say the reason, @msbutler can you help here?

alicia-l2 · 2025-10-08T19:37:33Z

src/current/v25.3/read-from-standby.md

+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;


Can you add a blurb which says "you can only run this command after the standby appvc is replicating." aka like if you run SHOW VIRTUAL CLUSTERS you will see that the status for the appvc is "replicating." basically we can't add a readervc from an alter command if the standby appvc is not ready/replicating.

not sure why this comment was resolved. looks like we still need this.

Small changes based on tech review

msbutler · 2025-10-10T13:18:11Z

src/current/v25.3/read-from-standby.md

+
+PCR utilizes [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a _system virtual cluster (SystemVC)_, and at least one data plane, called an _App Virtual Cluster (AppVC)_. The standby cluster's SystemVC 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 AppVC are identical to the primary cluster's AppVC. The standby cluster's AppVC 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 AppVC. Instead, PCR introduces a _reader virtual cluster (ReaderVC)_. The ReaderVC 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 AppVC using internal pointers, providing access to the replicated data while keeping the AppVC offline. The ReaderVC itself only stores a few GB of metadata and no user data,  so it does not require much extra disk space.


nit: s/a few GB/ a bit/r

after thinking about this a bit more, i don't we should say exactly how much storage space is required for the reader tenant

msbutler · 2025-10-10T13:21:16Z

src/current/v25.3/read-from-standby.md

+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;


not sure why this comment was resolved. looks like we still need this.

msbutler · 2025-10-10T13:23:33Z

src/current/v25.4/read-from-standby.md

+
+### Check the status of your reader virtual cluster
+
+To confirm that your reader virtual cluster is active:


unresolving. i don't see updated language on this.

msbutler · 2025-10-10T13:25:11Z

src/current/v25.4/read-from-standby.md

+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 the replicated time.


@peachdawnleach yeah i like that language.

@alicia-l2 the lag between the AOST the user provides and the AOST actually used is due to a very annoying technical bug i really want to address. It has to do with the fact that the reader tenant descriptors are updated after the replicated data comes in on the replicating tenant.

msbutler · 2025-10-10T13:26:37Z

src/current/v25.4/read-from-standby.md

+The output provides the following information:
+- the replication status of the standby cluster
+- the timestamp of the most recently applied event on the standby cluster
+- any lag relative to the primary cluster


run SHOW JOBS on the reader tenant. Or view the job on the db console of the reader tenant.

Added new pages

90bf4d9

Added new pages and added them to the TOC

Merge branch 'main' into 2025-10-01-doc-13854-add-read-from-standby

bd04a1e

peachdawnleach added 3 commits October 6, 2025 13:46

Fixed broken links

1e90a6f

Fixed broken links

Merge branch '2025-10-01-doc-13854-add-read-from-standby' of github.c…

468ff96

…om:cockroachdb/docs into 2025-10-01-doc-13854-add-read-from-standby

Lengthened summary

1690300

Build was failing because summary was too short

peachdawnleach requested a review from alicia-l2 October 6, 2025 18:05

msbutler self-requested a review October 7, 2025 12:57

msbutler reviewed Oct 7, 2025

View reviewed changes

alicia-l2 reviewed Oct 7, 2025

View reviewed changes

alicia-l2 reviewed Oct 8, 2025

View reviewed changes

Changes from review

fbe26de

Small changes based on tech review

msbutler reviewed Oct 10, 2025

View reviewed changes


		### Check the status of your reader virtual cluster

		To confirm that your reader virtual cluster is active:


		## How the read from standby feature works

		PCR utilizes cluster virtualization to separate clusters' control planes from their data planes. A cluster always has one control plane, called a _system virtual cluster (SystemVC)_, and at least one data plane, called an _App Virtual Cluster (AppVC)_. A cluster's SystemVC manages PCR jobs and cluster metadata, and is not used for application queries. All data tables, system tables, and cluster settings in the standby cluster's AppVC are identical to the primary cluster's AppVC. The standby cluster's AppVC itself remains offline during replication.


		PCR utilizes [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) to separate a cluster's control plane from its data plane. A cluster always has one control plane, called a _system virtual cluster (SystemVC)_, and at least one data plane, called an _App Virtual Cluster (AppVC)_. The standby cluster's SystemVC 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 AppVC are identical to the primary cluster's AppVC. The standby cluster's AppVC 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 AppVC. Instead, PCR introduces a _reader virtual cluster (ReaderVC)_. The ReaderVC 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 AppVC using internal pointers, providing access to the replicated data while keeping the AppVC offline. The ReaderVC itself only stores a few GB of metadata and no user data, so it does not require much extra disk space.

Add new section on read from standby feature #20502

Are you sure you want to change the base?

Add new section on read from standby feature #20502

Uh oh!

Conversation

peachdawnleach commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

github-actions bot commented Oct 6, 2025

Files changed:

Uh oh!

netlify bot commented Oct 6, 2025

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Uh oh!

netlify bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

peachdawnleach commented Oct 6, 2025

Uh oh!

msbutler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

msbutler Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alicia-l2 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peachdawnleach commented Oct 6, 2025 •

edited

Loading

netlify bot commented Oct 6, 2025 •

edited

Loading

netlify bot commented Oct 6, 2025 •

edited

Loading

netlify bot commented Oct 6, 2025 •

edited

Loading

msbutler Oct 7, 2025 •

edited

Loading

alicia-l2 left a comment •

edited

Loading