Skip to content

Commit 0cf55c9

Browse files
peachdawnleachpeachdawnleach
committed
Added code snippets
Added code snippets to entire upgrade process
1 parent 62b74c5 commit 0cf55c9

8 files changed

+291
-23
lines changed

‎src/current/v24.3/physical-cluster-replication-overview.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,10 @@ Statement | Action
6969
[`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters.
7070
[`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster.
7171

72+
## Cluster versions and upgrades
73+
74+
To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}).
75+
7276
## Demo video
7377

7478
Learn how to use PCR to meet your RTO and RPO requirements with the following demo:

‎src/current/v24.3/upgrade-with-pcr.md‎

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,29 +23,92 @@ To upgrade your primary and standby clusters:
2323

2424
1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process.
2525

26-
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. Replace the binary on each node of the cluster and restart the node.
26+
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node.
2727

28-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC.
28+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC:
29+
30+
{% include_cached copy-clipboard.html %}
31+
~~~ shell
32+
cockroach sql --url \
33+
"postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
34+
--certs-dir "certs"
35+
~~~
36+
37+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC:
38+
39+
{% include_cached copy-clipboard.html %}
40+
~~~ sql
41+
SET CLUSTER SETTING version '{VERSION}';
42+
~~~
2943

3044
{{site.data.alerts.callout_info}}
3145
If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized.
3246
{{site.data.alerts.end}}
3347

34-
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. Replace the binary on each node of the cluster and restart the node.
48+
1. Confirm that finalization is complete on the standby cluster's system VC:
49+
50+
{% include_cached copy-clipboard.html %}
51+
~~~ sql
52+
> SHOW CLUSTER SETTING version;
53+
~~~
54+
55+
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node.
56+
57+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC:
58+
59+
{% include_cached copy-clipboard.html %}
60+
~~~ shell
61+
cockroach sql --url \
62+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
63+
--certs-dir "certs"
64+
~~~
3565

36-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC.
66+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC:
67+
68+
{% include_cached copy-clipboard.html %}
69+
~~~ sql
70+
SET CLUSTER SETTING version '{VERSION}';
71+
~~~
3772

3873
{{site.data.alerts.callout_info}}
3974
If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. Rolling back the upgrade on the primary cluster does not roll back the standby cluster.
4075
{{site.data.alerts.end}}
4176

42-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC.
77+
1. Confirm that finalization is complete on the primary cluster's system VC:
78+
79+
{% include_cached copy-clipboard.html %}
80+
~~~ sql
81+
> SHOW CLUSTER SETTING version;
82+
~~~
83+
84+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC:
85+
86+
{% include_cached copy-clipboard.html %}
87+
~~~ shell
88+
cockroach sql --url \
89+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \
90+
--certs-dir "certs"
91+
~~~
92+
93+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC:
94+
95+
{% include_cached copy-clipboard.html %}
96+
~~~ sql
97+
SET CLUSTER SETTING version '{VERSION}';
98+
~~~
4399

44100
Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary.
45101

102+
1. Confirm that finalization is complete on the primary cluster's app VC:
103+
104+
{% include_cached copy-clipboard.html %}
105+
~~~ sql
106+
> SHOW CLUSTER SETTING version;
107+
~~~
108+
46109
## Upgrade reader VC
47110
48-
If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC:
111+
If you have a _reader virtual cluster (ReaderVC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC:
49112
50113
1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed.
51114
1. On the standby cluster, stop the reader VC service:

‎src/current/v25.2/physical-cluster-replication-overview.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@ Statement | Action
6767
[`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters.
6868
[`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster.
6969

70+
## Cluster versions and upgrades
71+
72+
To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}).
73+
7074
## Demo video
7175

7276
Learn how to use PCR to meet your RTO and RPO requirements with the following demo:

‎src/current/v25.2/upgrade-with-pcr.md‎

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,29 +23,92 @@ To upgrade your primary and standby clusters:
2323

2424
1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process.
2525

26-
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. Replace the binary on each node of the cluster and restart the node.
26+
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node.
2727

28-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC.
28+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC:
29+
30+
{% include_cached copy-clipboard.html %}
31+
~~~ shell
32+
cockroach sql --url \
33+
"postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
34+
--certs-dir "certs"
35+
~~~
36+
37+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC:
38+
39+
{% include_cached copy-clipboard.html %}
40+
~~~ sql
41+
SET CLUSTER SETTING version '{VERSION}';
42+
~~~
2943

3044
{{site.data.alerts.callout_info}}
3145
If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized.
3246
{{site.data.alerts.end}}
3347

34-
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. Replace the binary on each node of the cluster and restart the node.
48+
1. Confirm that finalization is complete on the standby cluster's system VC:
49+
50+
{% include_cached copy-clipboard.html %}
51+
~~~ sql
52+
> SHOW CLUSTER SETTING version;
53+
~~~
54+
55+
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node.
56+
57+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC:
58+
59+
{% include_cached copy-clipboard.html %}
60+
~~~ shell
61+
cockroach sql --url \
62+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
63+
--certs-dir "certs"
64+
~~~
3565

36-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC.
66+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC:
67+
68+
{% include_cached copy-clipboard.html %}
69+
~~~ sql
70+
SET CLUSTER SETTING version '{VERSION}';
71+
~~~
3772

3873
{{site.data.alerts.callout_info}}
3974
If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. Rolling back the upgrade on the primary cluster does not roll back the standby cluster.
4075
{{site.data.alerts.end}}
4176

42-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC.
77+
1. Confirm that finalization is complete on the primary cluster's system VC:
78+
79+
{% include_cached copy-clipboard.html %}
80+
~~~ sql
81+
> SHOW CLUSTER SETTING version;
82+
~~~
83+
84+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC:
85+
86+
{% include_cached copy-clipboard.html %}
87+
~~~ shell
88+
cockroach sql --url \
89+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \
90+
--certs-dir "certs"
91+
~~~
92+
93+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC:
94+
95+
{% include_cached copy-clipboard.html %}
96+
~~~ sql
97+
SET CLUSTER SETTING version '{VERSION}';
98+
~~~
4399

44100
Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary.
45101

102+
1. Confirm that finalization is complete on the primary cluster's app VC:
103+
104+
{% include_cached copy-clipboard.html %}
105+
~~~ sql
106+
> SHOW CLUSTER SETTING version;
107+
~~~
108+
46109
## Upgrade reader VC
47110
48-
If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC:
111+
If you have a _reader virtual cluster (ReaderVC)_, you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC:
49112
50113
1. After upgrading the app VC on your primary cluster, wait for the replicated time to pass the time at which the upgrade completed.
51114
1. On the standby cluster, stop the reader VC service:

‎src/current/v25.3/physical-cluster-replication-overview.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@ Statement | Action
6767
[`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters.
6868
[`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster.
6969

70+
## Cluster versions and upgrades
71+
72+
To safely perform a major version upgrade on a cluster with PCR, you must upgrade the standby cluster before the primary cluster to avoid version incompatibility. If you are using a reader virtual cluster (reader VC), you must upgrade it separately from the primary and standby clusters. For information about the upgrade process, refer to [Upgrade a Cluster Running PCR]({% link {{ page.version.version }}/upgrade-with-pcr.md %}).
73+
7074
## Demo video
7175

7276
Learn how to use PCR to meet your RTO and RPO requirements with the following demo:

‎src/current/v25.3/upgrade-with-pcr.md‎

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Upgrade a Cluster Running PCR
2+
title: Upgrade with Physical Cluster Replication Enabled
33
summary: Upgrade your primary and standby clusters when using PCR.
44
toc: true
55
docs_area: manage
@@ -23,26 +23,89 @@ To upgrade your primary and standby clusters:
2323

2424
1. Ensure that the virtual clusters on both your primary cluster and your standby cluster are [finalized]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) on the current version before beginning the upgrade process.
2525

26-
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. Replace the binary on each node of the cluster and restart the node.
26+
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the standby cluster. On each node of the cluster, replace the binary and restart the node.
2727

28-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC.
28+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the standby cluster's system VC:
29+
30+
{% include_cached copy-clipboard.html %}
31+
~~~ shell
32+
cockroach sql --url \
33+
"postgresql://root@{standby node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
34+
--certs-dir "certs"
35+
~~~
36+
37+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby cluster's system VC:
38+
39+
{% include_cached copy-clipboard.html %}
40+
~~~ sql
41+
SET CLUSTER SETTING version '{VERSION}';
42+
~~~
2943

3044
{{site.data.alerts.callout_info}}
3145
If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized.
3246
{{site.data.alerts.end}}
3347

34-
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. Replace the binary on each node of the cluster and restart the node.
48+
1. Confirm that finalization is complete on the standby cluster's system VC:
49+
50+
{% include_cached copy-clipboard.html %}
51+
~~~ sql
52+
> SHOW CLUSTER SETTING version;
53+
~~~
54+
55+
1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary cluster. On each node of the cluster, replace the binary and restart the node.
56+
57+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's system VC:
58+
59+
{% include_cached copy-clipboard.html %}
60+
~~~ shell
61+
cockroach sql --url \
62+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
63+
--certs-dir "certs"
64+
~~~
3565

36-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC.
66+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's system VC:
67+
68+
{% include_cached copy-clipboard.html %}
69+
~~~ sql
70+
SET CLUSTER SETTING version '{VERSION}';
71+
~~~
3772

3873
{{site.data.alerts.callout_info}}
3974
If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. Rolling back the upgrade on the primary cluster does not roll back the standby cluster.
4075
{{site.data.alerts.end}}
4176

42-
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC.
77+
1. Confirm that finalization is complete on the primary cluster's system VC:
78+
79+
{% include_cached copy-clipboard.html %}
80+
~~~ sql
81+
> SHOW CLUSTER SETTING version;
82+
~~~
83+
84+
1. [Connect]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#connect-to-the-system-virtual-cluster) to the primary cluster's app VC:
85+
86+
{% include_cached copy-clipboard.html %}
87+
~~~ shell
88+
cockroach sql --url \
89+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \
90+
--certs-dir "certs"
91+
~~~
92+
93+
1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's app VC:
94+
95+
{% include_cached copy-clipboard.html %}
96+
~~~ sql
97+
SET CLUSTER SETTING version '{VERSION}';
98+
~~~
4399

44100
Upgrading the primary cluster's app VC also upgrades the standby cluster's app VC, since it replicates from the primary.
45101

102+
1. Confirm that finalization is complete on the primary cluster's app VC:
103+
104+
{% include_cached copy-clipboard.html %}
105+
~~~ sql
106+
> SHOW CLUSTER SETTING version;
107+
~~~
108+
46109
## Upgrade reader VC
47110
48111
If you have a [_reader virtual cluster (reader VC)_]({% link {{ page.version.version }}/read-from-standby.md %}), you must drop and recreate it to upgrade after completing the main upgrade process on the primary and standby clusters. Follow these steps to upgrade your reader VC:

0 commit comments

Comments
 (0)