Skip to content

Commit 422ff8e

Browse files
ebembi-crdbebembi-crdb
authored
Merge branch 'main' into add-prod-build-notify-workflow
2 parents cf2c9de + 886dfe2 commit 422ff8e

File tree

4 files changed

+206
-0
lines changed

4 files changed

+206
-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: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Read from Standby
3+
summary: Direct read-only queries to your standby cluster instead of your primary 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]({% link {{ page.version.version }}/disaster-recovery-overview.md %}), [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) 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]({% 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.
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 itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space.
17+
18+
The standby cluster's ReaderVC has its own system tables and [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}). The ReaderVC replicates a subset of system tables, including **Users** and **Roles**, from the AppVC, so that existing primary users can authenticate using the same [users and roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) as on the primary cluster's AppVC. Other system tables and cluster settings are set to defaults in the ReaderVC. For more information, consult [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}).
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.md %}).
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`]({% link {{ page.version.version }}/create-virtual-cluster.md %}) 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`]({% link {{ page.version.version }}/alter-virtual-cluster.md %}) statement:
42+
43+
{% include_cached copy-clipboard.html %}
44+
~~~ sql
45+
ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;
46+
~~~
47+
48+
{{site.data.alerts.callout_info}}
49+
The standby cluster's AppVC must have a status of `replicating` before you can create your ReaderVC. Use the [`SHOW VIRTUAL CLUSTERS`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) command to check the status of the AppVC.
50+
{{site.data.alerts.end}}
51+
52+
### Check the status of your reader virtual cluster
53+
54+
To confirm that your reader virtual cluster is active:
55+
56+
{% include_cached copy-clipboard.html %}
57+
~~~ sql
58+
SHOW VIRTUAL CLUSTERS;
59+
~~~
60+
61+
The output shows a `standby-readonly` virtual cluster in addition to the systemVC and AppVC:
62+
63+
~~~
64+
id | name | data_state | service_mode
65+
-----+------------------+-------------+---------------
66+
1 | system | ready | shared
67+
3 | standby | replicating | none
68+
4 | standby-readonly | ready | shared
69+
~~~
70+
71+
{{site.data.alerts.callout_info}}
72+
The ReaderVC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the ReaderVC's `service_mode` is `shared`, then wait about one minute before connecting to the ReaderVC.
73+
{{site.data.alerts.end}}
74+
75+
### Run read-only queries on the standby cluster
76+
77+
Once you have created a reader virtual cluster on the standby cluster, you can connect to it and run [read (`SELECT`) queries]({% link {{ page.version.version }}/selection-queries.md %}). For example:
78+
79+
{% include_cached copy-clipboard.html %}
80+
~~~ sql
81+
SELECT COUNT(*) FROM customers;
82+
SELECT region, SUM(amount) FROM orders GROUP BY region;
83+
~~~
84+
85+
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]({% link {{ page.version.version }}/show-virtual-cluster.md %}#show-replication-status).
86+
87+
{{ site.data.alerts.callout_info }}
88+
Write operations are not permitted on the standby cluster.
89+
{{ site.data.alerts.end }}
90+
91+
## See also
92+
- [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %})
93+
- [Fail Over from a Primary Cluster to a Standby Cluster]({% link {{ page.version.version }}/failover-replication.md %})
94+
- [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %})
95+
- [`CREATE VIRTUAL CLUSTER`]({% link {{ page.version.version }}/create-virtual-cluster.md %})
96+
- [`ALTER VIRTUAL CLUSTER`]({% link {{ page.version.version }}/alter-virtual-cluster.md %})
97+
- [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %})

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

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Read from Standby
3+
summary: Direct read-only queries to your standby cluster instead of your primary 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]({% link {{ page.version.version }}/disaster-recovery-overview.md %}), [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) 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]({% 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.
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 itself only stores a small amount of metadata and no user data, so it is not expected to take up additional storage space.
17+
18+
The standby cluster's ReaderVC has its own system tables and [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}). The ReaderVC replicates a subset of system tables, including **Users** and **Roles**, from the AppVC, so that existing primary users can authenticate using the same [users and roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) as on the primary cluster's AppVC. Other system tables and cluster settings are set to defaults in the ReaderVC. For more information, consult [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}).
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.md %}).
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`]({% link {{ page.version.version }}/create-virtual-cluster.md %}) 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`]({% link {{ page.version.version }}/alter-virtual-cluster.md %}) statement:
42+
43+
{% include_cached copy-clipboard.html %}
44+
~~~ sql
45+
ALTER VIRTUAL CLUSTER main SET REPLICATION READ VIRTUAL CLUSTER;
46+
~~~
47+
48+
{{site.data.alerts.callout_info}}
49+
The standby cluster's AppVC must have a status of `replicating` before you can create your ReaderVC. Use the [`SHOW VIRTUAL CLUSTERS`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) command to check the status of the AppVC.
50+
{{site.data.alerts.end}}
51+
52+
### Check the status of your reader virtual cluster
53+
54+
To confirm that your reader virtual cluster is active:
55+
56+
{% include_cached copy-clipboard.html %}
57+
~~~ sql
58+
SHOW VIRTUAL CLUSTERS;
59+
~~~
60+
61+
The output shows a `standby-readonly` virtual cluster in addition to the systemVC and AppVC:
62+
63+
~~~
64+
id | name | data_state | service_mode
65+
-----+------------------+-------------+---------------
66+
1 | system | ready | shared
67+
3 | standby | replicating | none
68+
4 | standby-readonly | ready | shared
69+
~~~
70+
71+
{{site.data.alerts.callout_info}}
72+
The ReaderVC cannot serve reads until after the PCR initial scan is complete. After completing the initial scan, wait until the ReaderVC's `service_mode` is `shared`, then wait about one minute before connecting to the ReaderVC.
73+
{{site.data.alerts.end}}
74+
75+
### Run read-only queries on the standby cluster
76+
77+
Once you have created a reader virtual cluster on the standby cluster, you can connect to it and run [read (`SELECT`) queries]({% link {{ page.version.version }}/selection-queries.md %}). For example:
78+
79+
{% include_cached copy-clipboard.html %}
80+
~~~ sql
81+
SELECT COUNT(*) FROM customers;
82+
SELECT region, SUM(amount) FROM orders GROUP BY region;
83+
~~~
84+
85+
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]({% link {{ page.version.version }}/show-virtual-cluster.md %}#show-replication-status).
86+
87+
{{ site.data.alerts.callout_info }}
88+
Write operations are not permitted on the standby cluster.
89+
{{ site.data.alerts.end }}
90+
91+
## See also
92+
- [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %})
93+
- [Fail Over from a Primary Cluster to a Standby Cluster]({% link {{ page.version.version }}/failover-replication.md %})
94+
- [Physical Cluster Replication Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %})
95+
- [`CREATE VIRTUAL CLUSTER`]({% link {{ page.version.version }}/create-virtual-cluster.md %})
96+
- [`ALTER VIRTUAL CLUSTER`]({% link {{ page.version.version }}/alter-virtual-cluster.md %})
97+
- [`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %})

0 commit comments

Comments
 (0)