Skip to content

Commit 90bf4d9

Browse files
peachdawnleachpeachdawnleach
committed
Added new pages
Added new pages and added them to the TOC
1 parent 5a7f0a1 commit 90bf4d9

File tree

4 files changed

+212
-0
lines changed

4 files changed

+212
-0
lines changed

‎src/current/_includes/v25.3/sidebar-data/cross-cluster-replication.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,12 @@
5858
"/${VERSION}/physical-cluster-replication-monitoring.html"
5959
]
6060
},
61+
{
62+
"title": "Read From Standby",
63+
"urls": [
64+
"/${VERSION}/read-from-standby.html"
65+
]
66+
},
6167
{
6268
"title": "Technical Overview",
6369
"urls": [

‎src/current/_includes/v25.4/sidebar-data/cross-cluster-replication.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,12 @@
5858
"/${VERSION}/physical-cluster-replication-monitoring.html"
5959
]
6060
},
61+
{
62+
"title": "Read From Standby",
63+
"urls": [
64+
"/${VERSION}/read-from-standby.html"
65+
]
66+
},
6167
{
6268
"title": "Technical Overview",
6369
"urls": [

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Read from Standby
3+
summary: Direct read-only queries to your standby cluster.
4+
toc: true
5+
docs_area: manage
6+
---
7+
8+
In addition to providing [failover]({% link {{ page.version.version }}/failover-replication.md %}) capabilities for disaster recovery, CockroachDB **physical cluster replication (PCR)** allows you to direct read-only queries to your standby cluster. This process offloads traffic such as application reads, analytics queries, and ad-hoc reporting from the primary cluster.
9+
10+
Use this page to understand how the **read from standby** feature works and how to utilize it.
11+
12+
## How the read from standby feature works
13+
14+
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.
15+
16+
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 does not store any data itself, so it does not require extra disk space.
17+
18+
The standby cluster's ReaderVC has its own system tables and cluster settings. The ReaderVC replicates a subset of system tables, including **Users** and **Roles**, from the AppVC, so that existing primary users can authenticate. Other system tables and cluster settings are set to defaults in the ReaderVC.
19+
20+
In the event of failover, the ReaderVC's response depends on the type of failover. After failover to the latest timestamp, the ReaderVC continues pointing to the AppVC but stops receiving updates. After failover to a point-in-time timestamp, the ReaderVC is destroyed.
21+
22+
## Use the read from standby feature
23+
### Before you begin
24+
25+
Prior to setting up read from standby, ensure that:
26+
27+
- you have already configured PCR between a _primary_ cluster and a _standby_ cluster. For information on configuring PCR, refer to [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication %}).
28+
- your CockroachDB version is v24.3 or later. The `read from standby` option is not supported in earlier versions.
29+
30+
### Start a PCR stream with read from standby
31+
32+
To start a PCR stream that allows read access to the standby cluster, use the `CREATE VIRTUAL CLUSTER ... REPLICATION` statement with the `READ VIRTUAL CLUSTER` option:
33+
34+
{% include_cached copy-clipboard.html %}
35+
~~~ sql
36+
CREATE VIRTUAL CLUSTER main FROM REPLICATION OF main ON 'postgresql://{connection string to primary}' WITH READ VIRTUAL CLUSTER;
37+
~~~
38+
39+
### Add read from standby to a PCR stream
40+
41+
To add read from standby capabilities to an existing PCR stream, use the `ALTER VIRTUAL CLUSTER` statement:
42+
43+
{% include_cached copy-clipboard.html %}
44+
~~~ sql
45+
ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;
46+
~~~
47+
48+
### Check the status of your reader virtual cluster
49+
50+
To confirm that your reader virtual cluster is active:
51+
52+
{% include_cached copy-clipboard.html %}
53+
~~~ sql
54+
SHOW VIRTUAL CLUSTERS;
55+
~~~
56+
57+
The output shows a `standby-readonly` virtual cluster in addition to the primary and standby clusters:
58+
59+
~~~
60+
id | name | data_state | service_mode
61+
-----+------------------+-------------+---------------
62+
1 | system | ready | shared
63+
3 | standby | replicating | none
64+
4 | standby-readonly | ready | shared
65+
~~~
66+
67+
### Run read-only queries on the standby cluster
68+
69+
Once you have created a reader virtual cluster on the standby cluster, you can connect to it and run read (`SELECT`) queries. For example:
70+
71+
{% include_cached copy-clipboard.html %}
72+
~~~ sql
73+
SELECT COUNT(*) FROM customers;
74+
SELECT region, SUM(amount) FROM orders GROUP BY region;
75+
~~~
76+
77+
The results of queries on the standby cluster reflect the state of the primary cluster as of the replicated time.
78+
79+
{{ site.data.alerts.callout_info }}
80+
Write operations are not permitted on the standby cluster.
81+
{{ site.data.alerts.end }}
82+
83+
### Monitor replication lag
84+
85+
Reading from the standby cluster may return slightly stale data due to replication lag between the primary cluster and the standby cluster. You can monitor replication lag to understand how current the data in the standby cluster is. To check the standby cluster's replication status:
86+
87+
{% include_cached copy-clipboard.html %}
88+
~~~ sql
89+
SHOW VIRTUAL CLUSTER REPLICATION STATUS <standby_name>;
90+
~~~
91+
92+
The output provides the following information:
93+
- the replication status of the standby cluster
94+
- the timestamp of the most recently applied event on the standby cluster
95+
- any lag relative to the primary cluster
96+
97+
## See also
98+
- [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %})
99+
- [Fail Over from a Primary Cluster to a Standby Cluster]({% link {{ page.version.version }}/failover-replication.md %})
100+
- [`CREATE VIRTUAL CLUSTER`]({% link {{ page.version.version }}/create-virtual-cluster.md %})

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Read from Standby
3+
summary: Direct read-only queries to your standby cluster.
4+
toc: true
5+
docs_area: manage
6+
---
7+
8+
In addition to providing [failover]({% link {{ page.version.version }}/failover-replication.md %}) capabilities for disaster recovery, CockroachDB **physical cluster replication (PCR)** allows you to direct read-only queries to your standby cluster. This process offloads traffic such as application reads, analytics queries, and ad-hoc reporting from the primary cluster.
9+
10+
Use this page to understand how the **read from standby** feature works and how to utilize it.
11+
12+
## How the read from standby feature works
13+
14+
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.
15+
16+
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 does not store any data itself, so it does not require extra disk space.
17+
18+
The standby cluster's ReaderVC has its own system tables and cluster settings. The ReaderVC replicates a subset of system tables, including **Users** and **Roles**, from the AppVC, so that existing primary users can authenticate. Other system tables and cluster settings are set to defaults in the ReaderVC.
19+
20+
In the event of failover, the ReaderVC is destroyed.
21+
22+
## Use the read from standby feature
23+
### Before you begin
24+
25+
Prior to setting up read from standby, ensure that:
26+
27+
- you have already configured PCR between a _primary_ cluster and a _standby_ cluster. For information on configuring PCR, refer to [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication %}).
28+
- your CockroachDB version is v24.3 or later. The `read from standby` option is not supported in earlier versions.
29+
30+
### Start a PCR stream with read from standby
31+
32+
To start a PCR stream that allows read access to the standby cluster, use the `CREATE VIRTUAL CLUSTER ... REPLICATION` statement with the `READ VIRTUAL CLUSTER` option:
33+
34+
{% include_cached copy-clipboard.html %}
35+
~~~ sql
36+
CREATE VIRTUAL CLUSTER main FROM REPLICATION OF main ON 'postgresql://{connection string to primary}' WITH READ VIRTUAL CLUSTER;
37+
~~~
38+
39+
### Add read from standby to a PCR stream
40+
41+
To add read from standby capabilities to an existing PCR stream, use the `ALTER VIRTUAL CLUSTER` statement:
42+
43+
{% include_cached copy-clipboard.html %}
44+
~~~ sql
45+
ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;
46+
~~~
47+
48+
### Check the status of your reader virtual cluster
49+
50+
To confirm that your reader virtual cluster is active:
51+
52+
{% include_cached copy-clipboard.html %}
53+
~~~ sql
54+
SHOW VIRTUAL CLUSTERS;
55+
~~~
56+
57+
The output shows a `standby-readonly` virtual cluster in addition to the primary and standby clusters:
58+
59+
~~~
60+
id | name | data_state | service_mode
61+
-----+------------------+-------------+---------------
62+
1 | system | ready | shared
63+
3 | standby | replicating | none
64+
4 | standby-readonly | ready | shared
65+
~~~
66+
67+
### Run read-only queries on the standby cluster
68+
69+
Once you have created a reader virtual cluster on the standby cluster, you can connect to it and run read (`SELECT`) queries. For example:
70+
71+
{% include_cached copy-clipboard.html %}
72+
~~~ sql
73+
SELECT COUNT(*) FROM customers;
74+
SELECT region, SUM(amount) FROM orders GROUP BY region;
75+
~~~
76+
77+
The results of queries on the standby cluster reflect the state of the primary cluster as of the replicated time.
78+
79+
{{ site.data.alerts.callout_info }}
80+
Write operations are not permitted on the standby cluster.
81+
{{ site.data.alerts.end }}
82+
83+
### Monitor replication lag
84+
85+
Reading from the standby cluster may return slightly stale data due to replication lag between the primary cluster and the standby cluster. You can monitor replication lag to understand how current the data in the standby cluster is. To check the standby cluster's replication status:
86+
87+
{% include_cached copy-clipboard.html %}
88+
~~~ sql
89+
SHOW VIRTUAL CLUSTER REPLICATION STATUS <standby_name>;
90+
~~~
91+
92+
The output provides the following information:
93+
- the replication status of the standby cluster
94+
- the timestamp of the most recently applied event on the standby cluster
95+
- any lag relative to the primary cluster
96+
97+
## See also
98+
- [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %})
99+
- [Fail Over from a Primary Cluster to a Standby Cluster]({% link {{ page.version.version }}/failover-replication.md %})
100+
- [`CREATE VIRTUAL CLUSTER`]({% link {{ page.version.version }}/create-virtual-cluster.md %})

0 commit comments

Comments
 (0)