From a5046bfa78f36e52a1d2b38f1eba33ab307268d0 Mon Sep 17 00:00:00 2001 From: "Matt Linville (he/him)" Date: Wed, 15 Nov 2023 13:39:45 -0800 Subject: [PATCH] [DOC-9200] Document recommenadation to reset SQL statistics before upgrading to v23.1 (#18072) - Remove redundant 'Review Breaking Changes' sections from v23.1 and v23.2 upgrade topics - Move 'Review Breaking Changes' section in v22.2 upgrade topic earlier - Also add the advice to reset SQL statistcs in the CockroachDB Cloud 'Upgrade to v23.1' topic --- src/current/cockroachcloud/upgrade-to-v23.1.md | 9 +++++++++ src/current/v22.2/upgrade-cockroach-version.md | 12 ++++++------ src/current/v23.1/upgrade-cockroach-version.md | 9 ++++++--- src/current/v23.2/upgrade-cockroach-version.md | 6 ------ 4 files changed, 21 insertions(+), 15 deletions(-) diff --git a/src/current/cockroachcloud/upgrade-to-v23.1.md b/src/current/cockroachcloud/upgrade-to-v23.1.md index 20b314fa102..0139a40f7bb 100644 --- a/src/current/cockroachcloud/upgrade-to-v23.1.md +++ b/src/current/cockroachcloud/upgrade-to-v23.1.md @@ -60,6 +60,15 @@ The [**SQL Users**]({% link cockroachcloud/managing-access.md %}#create-a-sql-us Review the [backward-incompatible changes in {{ page.page_version }}](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}{% unless rd.release_date == "N/A" or rd.release_date > today %}#{{ page.page_version | replace: ".", "-" }}-0-backward-incompatible-changes{% endunless %}) and [deprecated features](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}#{% unless rd.release_date == "N/A" or rd.release_date > today %}{{ page.page_version | replace: ".", "-" }}-0-deprecations{% endunless %}). If any affect your applications, make the necessary changes before proceeding. +### Reset SQL statistics + +Before upgrading to CockroachDB v23.1, it is recommended to reset the cluster's SQL statistics. Otherwise, it may take longer for the upgrade to complete on a cluster with large statement or transaction statistics tables. This is due to the addition of a new column and a new index to these tables. To reset SQL statistics, issue the following SQL command: + +{% include_cached copy-clipboard.html %} +~~~ sql +SELECT crdb_internal.reset_sql_stats(); +~~~ + ## Step 5. Start the upgrade To start the upgrade process: diff --git a/src/current/v22.2/upgrade-cockroach-version.md b/src/current/v22.2/upgrade-cockroach-version.md index 4075ea92db0..6545c1c3049 100644 --- a/src/current/v22.2/upgrade-cockroach-version.md +++ b/src/current/v22.2/upgrade-cockroach-version.md @@ -63,6 +63,12 @@ When you are ready to upgrade to {{ latest.release_name }}, continue to [step 2] Before starting the upgrade, complete the following steps. +### Review breaking changes + +{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.version.version" | first %} + +Review the [backward-incompatible changes in {{ page.version.version }}](../releases/{{ page.version.version }}.html{% unless rd.release_date == "N/A" or rd.release_date > today %}#{{ page.version.version | replace: ".", "-" }}-0-backward-incompatible-changes{% endunless %}) and [deprecated features](../releases/{{ page.version.version }}.html#{% unless rd.release_date == "N/A" or rd.release_date > today %}{{ page.version.version | replace: ".", "-" }}-0-deprecations{% endunless %}). If any affect your deployment, make the necessary changes before starting the rolling upgrade to {{ page.version.version }}. + ### Check load balancing Make sure your cluster is behind a [load balancer](recommended-production-settings.html#load-balancing), or your clients are configured to talk to multiple nodes. If your application communicates with a single node, stopping that node to upgrade its CockroachDB binary will cause your application to fail. @@ -99,12 +105,6 @@ If your cluster contains partially-decommissioned nodes, they will block an upgr 1. First, reissue the [decommission command](node-shutdown.html?filters=decommission#decommission-the-node). The second command typically succeeds within a few minutes. 1. If the second decommission command does not succeed, [recommission](node-shutdown.html?filters=decommission#recommission-nodes) and then decommission it again. Before continuing the upgrade, the node must be marked as `decommissioned`. -### Review breaking changes - -{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.version.version" | first %} - -Review the [backward-incompatible changes in {{ page.version.version }}](../releases/{{ page.version.version }}.html{% unless rd.release_date == "N/A" or rd.release_date > today %}#{{ page.version.version | replace: ".", "-" }}-0-backward-incompatible-changes{% endunless %}) and [deprecated features](../releases/{{ page.version.version }}.html#{% unless rd.release_date == "N/A" or rd.release_date > today %}{{ page.version.version | replace: ".", "-" }}-0-deprecations{% endunless %}). If any affect your deployment, make the necessary changes before starting the rolling upgrade to {{ page.version.version }}. - ## Step 3. Decide how the upgrade will be finalized {{site.data.alerts.callout_info}} diff --git a/src/current/v23.1/upgrade-cockroach-version.md b/src/current/v23.1/upgrade-cockroach-version.md index d8210f378c8..81a2eb8f917 100644 --- a/src/current/v23.1/upgrade-cockroach-version.md +++ b/src/current/v23.1/upgrade-cockroach-version.md @@ -110,11 +110,14 @@ If your cluster contains partially-decommissioned nodes, they will block an upgr {% include {{page.version.version}}/backups/recommend-backups-for-upgrade.md%} See our [support policy for restoring backups across versions]({% link {{ page.version.version }}/restoring-backups-across-versions.md %}#support-for-restoring-backups-into-a-newer-version). -### Review breaking changes +### Reset SQL statistics -{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.version.version" | first %} +Before upgrading to CockroachDB v23.1, it is recommended to reset the cluster's SQL statistics. Otherwise, it may take longer for the upgrade to complete on a cluster with large statement or transaction statistics tables. This is due to the addition of a new column and a new index to these tables. To reset SQL statistics, issue the following SQL command: -Review the [backward-incompatible changes in {{ page.version.version }}](https://www.cockroachlabs.com/docs/releases/{{ page.version.version }}{% unless rd.release_date == "N/A" or rd.release_date > today %}#{{ page.version.version | replace: ".", "-" }}-0-backward-incompatible-changes{% endunless %}) and [deprecated features](https://www.cockroachlabs.com/docs/releases/{{ page.version.version }}#{% unless rd.release_date == "N/A" or rd.release_date > today %}{{ page.version.version | replace: ".", "-" }}-0-deprecations{% endunless %}). If any affect your deployment, make the necessary changes before starting the rolling upgrade to {{ page.version.version }}. +{% include_cached copy-clipboard.html %} +~~~ sql +SELECT crdb_internal.reset_sql_stats(); +~~~ ## Step 3. Decide how the upgrade will be finalized diff --git a/src/current/v23.2/upgrade-cockroach-version.md b/src/current/v23.2/upgrade-cockroach-version.md index 110abd6953f..2010daa0423 100644 --- a/src/current/v23.2/upgrade-cockroach-version.md +++ b/src/current/v23.2/upgrade-cockroach-version.md @@ -110,12 +110,6 @@ If your cluster contains partially-decommissioned nodes, they will block an upgr {% include {{page.version.version}}/backups/recommend-backups-for-upgrade.md%} See our [support policy for restoring backups across versions]({% link {{ page.version.version }}/restoring-backups-across-versions.md %}#support-for-restoring-backups-into-a-newer-version). -### Review breaking changes - -{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.version.version" | first %} - -Review the [backward-incompatible changes in {{ page.version.version }}](https://www.cockroachlabs.com/docs/releases/{{ page.version.version }}{% unless rd.release_date == "N/A" or rd.release_date > today %}#{{ page.version.version | replace: ".", "-" }}-0-backward-incompatible-changes{% endunless %}) and [deprecated features](https://www.cockroachlabs.com/docs/releases/{{ page.version.version }}#{% unless rd.release_date == "N/A" or rd.release_date > today %}{{ page.version.version | replace: ".", "-" }}-0-deprecations{% endunless %}). If any affect your deployment, make the necessary changes before starting the rolling upgrade to {{ page.version.version }}. - ## Step 3. Decide how the upgrade will be finalized {{site.data.alerts.callout_info}}