diff --git a/src/current/_includes/common/upgrade/disable-auto-finalization.md b/src/current/_includes/common/upgrade/disable-auto-finalization.md index 67e26aa4cec..ecccb958341 100644 --- a/src/current/_includes/common/upgrade/disable-auto-finalization.md +++ b/src/current/_includes/common/upgrade/disable-auto-finalization.md @@ -1,7 +1,7 @@ {% if page.path contains 'kubernetes' %}
-For clusters managed by the Operator, auto-finalization is disabled and cannot be enabled. A major version upgrade is not complete until it is manually [finalized](#finalize-a-major-version-upgrade). +For clusters managed by the Operator, auto-finalization is disabled and cannot be enabled. A major version upgrade is not complete until it is manually [finalized](#finalize-a-major-version-upgrade-manually).
@@ -21,7 +21,7 @@ To disable auto-finalization: 1. Set the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `cluster.preserve_downgrade_option` to the cluster's current major version. -Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade) or [roll it back]({#roll-back-a-major-version-upgrade). +Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade-manually) or [roll it back](#roll-back-a-major-version-upgrade). {{site.data.alerts.callout_info}} Previously, to disable automatic finalization and preserve the ability to roll back a major-version upgrade, it was required to set the cluster setting `cluster.preserve_downgrade_option` to the cluster's current major version before beginning the major-version upgrade. This cluster setting does not persist after finalization is complete, but must be set before each major-version upgrade. @@ -48,7 +48,7 @@ To disable auto-finalization: 1. Set the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `cluster.preserve_downgrade_option` to the cluster's current major version. -Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade) or [roll it back]({#roll-back-a-major-version-upgrade). +Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade-manually) or [roll it back]({#roll-back-a-major-version-upgrade). {{site.data.alerts.callout_info}} Previously, to disable automatic finalization and preserve the ability to roll back a major-version upgrade, it was required to set the cluster setting `cluster.preserve_downgrade_option` to the cluster's current major version before beginning the major-version upgrade. This cluster setting does not persist after finalization is complete, but must be set before each major-version upgrade. @@ -73,7 +73,7 @@ To disable auto-finalization: 1. Set the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `cluster.auto_upgrade.enabled` to `false`. -Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade) or [roll it back]({#roll-back-a-major-version-upgrade). +Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade-manually) or [roll it back]({#roll-back-a-major-version-upgrade). {{site.data.alerts.callout_info}} Previously, to disable automatic finalization and preserve the ability to roll back a major-version upgrade, it was required to set the cluster setting `cluster.preserve_downgrade_option` to the cluster's current major version before beginning the major-version upgrade. This cluster setting does not persist after finalization is complete, but must be set before each major-version upgrade. diff --git a/src/current/_includes/common/upgrade/major-version-upgrade-cloud.md b/src/current/_includes/common/upgrade/major-version-upgrade-cloud.md index d46cad338f3..8c755d140dc 100644 --- a/src/current/_includes/common/upgrade/major-version-upgrade-cloud.md +++ b/src/current/_includes/common/upgrade/major-version-upgrade-cloud.md @@ -18,4 +18,4 @@ This section shows how to perform a major-version upgrade for a cluster in Cockr 1. A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is upgraded. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are upgraded one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node {{ site.data.products.advanced }} cluster will be unavailable while the cluster is upgraded and restarted. If necessary, prepare for the upgrade by communicating ahead of time with your users, and plan to begin the upgrade during a time when the impact on the cluster's workload will be minimized. 1. To begin a major-version upgrade, go back to the dialog in the CockroachDB {{ site.data.products.cloud }} Console. If multiple upgrades are available, select the desired version. Review the details, then click **Start upgrade**. The dialog closes, and the **Version** columnin the **Cluster List** page changes to **Upgrading**. When the upgrade has finished but has not yet been finalized, the **Version** column reports that the new version is **pending**. -The upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade). After the upgrade is finalized, the cluster can no longer be [rolled back](#roll-back-a-major-version-upgrade) to its previous major version. If you take no action, finalization occurs automatically after approximately 72 hours. +The upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). After the upgrade is finalized, the cluster can no longer be [rolled back](#roll-back-a-major-version-upgrade) to its previous major version. If you take no action, finalization occurs automatically after approximately 72 hours. diff --git a/src/current/_includes/common/upgrade/major-version-upgrade-kubernetes.md b/src/current/_includes/common/upgrade/major-version-upgrade-kubernetes.md index d8cbeb4717e..7b61fbab657 100644 --- a/src/current/_includes/common/upgrade/major-version-upgrade-kubernetes.md +++ b/src/current/_includes/common/upgrade/major-version-upgrade-kubernetes.md @@ -29,7 +29,7 @@ To perform a major upgrade: You can also check the CockroachDB version of each node in the [DB Console]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}#node-details). -1. Before beginning a major-version upgrade, the Operator disables auto-finalization by setting the cluster setting `cluster.preserve_downgrade_option` to the cluster's current major version. Before finalizing an upgrade, follow your organization's testing procedures to decide whether to [finalize](#finalize-a-major-version-upgrade) or [roll back](#roll-back-a-major-version-upgrade) the upgrade. After finalization begins, you can no longer roll back to the cluster's previous major version. +1. Before beginning a major-version upgrade, the Operator disables auto-finalization by setting the cluster setting `cluster.preserve_downgrade_option` to the cluster's current major version. Before finalizing an upgrade, follow your organization's testing procedures to decide whether to [finalize](#finalize-a-major-version-upgrade-manually) or [roll back](#roll-back-a-major-version-upgrade) the upgrade. After finalization begins, you can no longer roll back to the cluster's previous major version.
@@ -124,7 +124,7 @@ To perform a major upgrade: ~~~ You can also check the CockroachDB version of each node in the [DB Console]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}#node-details). -1. If auto-finalization is disabled, the upgrade is not complete until you [finalize the upgrade](#finalize-a-major-version-upgrade). +1. If auto-finalization is disabled, the upgrade is not complete until you [finalize the upgrade](#finalize-a-major-version-upgrade-manually). @@ -259,6 +259,6 @@ To perform a major upgrade: You can also check the CockroachDB version of each node in the [DB Console]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}#node-details). -1. If auto-finalization is disabled, the upgrade is not complete until you [finalize the upgrade](#finalize-a-major-version-upgrade). +1. If auto-finalization is disabled, the upgrade is not complete until you [finalize the upgrade](#finalize-a-major-version-upgrade-manually). diff --git a/src/current/_includes/common/upgrade/major-version-upgrade-self-hosted.md b/src/current/_includes/common/upgrade/major-version-upgrade-self-hosted.md index a0914fcff62..0a592666068 100644 --- a/src/current/_includes/common/upgrade/major-version-upgrade-self-hosted.md +++ b/src/current/_includes/common/upgrade/major-version-upgrade-self-hosted.md @@ -12,4 +12,4 @@ To perform a major upgrade: cockroach sql -e 'select 1' ~~~ 1. If auto-finalization is enabled (the default), finalization begins as soon as the last node rejoins the cluster with the new binary. When finalization finishes, the upgrade is complete. -1. If auto-finalization is disabled, follow your organization's testing procedures to decide whether to [finalize the upgrade](#finalize-a-major-version-upgrade) or [roll back](#roll-back-a-major-version-upgrade) the upgrade. After finalization begins, you can no longer roll back to the cluster's previous major version. +1. If auto-finalization is disabled, follow your organization's testing procedures to decide whether to [finalize the upgrade](#finalize-a-major-version-upgrade-manually) or [roll back](#roll-back-a-major-version-upgrade) the upgrade. After finalization begins, you can no longer roll back to the cluster's previous major version. diff --git a/src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md b/src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md index 8cdd0ab402d..ccb74c90ac0 100644 --- a/src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md +++ b/src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md @@ -1,6 +1,6 @@ Before beginning a major-version upgrade: -1. **CockroachDB {{ site.data.products.advanced }}**: Verify the overall health of your cluster using the [DB Console]({% link cockroachcloud/tools-page#access-the-db-console.md %}): +1. **CockroachDB {{ site.data.products.advanced }}**: Verify the overall health of your cluster using the [DB Console]({% link cockroachcloud/tools-page.md %}#access-the-db-console): - Under **Node Status**, make sure all nodes that should be live are listed as such. If any nodes are unexpectedly listed as `SUSPECT` or `DEAD`, identify why the nodes are offline and either restart them or [decommission]({% link {{ site.current_cloud_version }}/node-shutdown.md %}?filters=decommission#remove-nodes) them before beginning your upgrade. If there are `DEAD` and non-decommissioned nodes in your cluster, the upgrade cannot be finalized. If any node is not fully decommissioned, try the following: diff --git a/src/current/_includes/common/upgrade/rollback-cloud.md b/src/current/_includes/common/upgrade/rollback-cloud.md index 5e612b9061c..470b69262cb 100644 --- a/src/current/_includes/common/upgrade/rollback-cloud.md +++ b/src/current/_includes/common/upgrade/rollback-cloud.md @@ -4,4 +4,4 @@ To roll back to the previous major version before the upgrade is finalized autom 1. At the top of the page, click **Roll back**. A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is rolled back. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB {{ site.data.products.advanced }} cluster will be unavailable while the cluster is rolled back and restarted. Like an upgrade, a rollback must be finalized. -1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-versino-upgrade). When the rollback is finalized, the rollback is complete. +1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-version-upgrade-manually). When the rollback is finalized, the rollback is complete. diff --git a/src/current/_includes/common/upgrade/rollback-kubernetes.md b/src/current/_includes/common/upgrade/rollback-kubernetes.md index 83efa02140c..9955b029030 100644 --- a/src/current/_includes/common/upgrade/rollback-kubernetes.md +++ b/src/current/_includes/common/upgrade/rollback-kubernetes.md @@ -27,4 +27,4 @@ To roll back to the previous major version before an upgrade is finalized: You can also check the CockroachDB version of each node in the [DB Console]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}#node-details). -1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-version-upgrade). When the rollback is finalized, the rollback is complete. +1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-version-upgrade-manually). When the rollback is finalized, the rollback is complete. diff --git a/src/current/_includes/common/upgrade/rollback-self-hosted.md b/src/current/_includes/common/upgrade/rollback-self-hosted.md index e754d8bd068..7049dd86fde 100644 --- a/src/current/_includes/common/upgrade/rollback-self-hosted.md +++ b/src/current/_includes/common/upgrade/rollback-self-hosted.md @@ -1,4 +1,4 @@ To roll back a major-version upgrade that has not been finalized: 1. Follow the steps to [perform a major-version upgrade](#perform-a-major-version-upgrade), replacing the `cockroach` binary on each node with binary for the previous major version. -1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-version-upgrade). When the rollback is finalized, the rollback is complete. +1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-version-upgrade-manually). When the rollback is finalized, the rollback is complete. diff --git a/src/current/_includes/common/upgrade/upgrade-high-level.md b/src/current/_includes/common/upgrade/upgrade-high-level.md index d6dfb480494..93abf11c210 100644 --- a/src/current/_includes/common/upgrade/upgrade-high-level.md +++ b/src/current/_includes/common/upgrade/upgrade-high-level.md @@ -5,4 +5,4 @@ At a high level, a cluster upgrade involves the following steps, which are detai 1. Restart the `cockroach` process and verify that the node has rejoined the cluster. 1. When all nodes have rejoined the cluster: 1. For a patch upgrade within the same major version, the upgrade is complete. - 1. For a major-version upgrade, the upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade). Auto-finalization is enabled by default, and begins as soon as all nodes have rejoined the cluster using the new binary. If you need the ability to [roll back a major-version upgrade](#roll-back-a-major-version-upgrade), you can disable auto-finalization and finalize the upgrade manually. Certain features and performance improvements, such as those that require changes to system schemas or objects, are not available until the upgrade is finalized. Refer to the {% if page.path contains 'cockroachcloud' %} [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ page.version.version }}.md %}) {% else %}[{{ page.version.version }} Release Notes]({% link releases/{{ page.version.version }}.md %}).{% endif %}. + 1. For a major-version upgrade, the upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). Auto-finalization is enabled by default, and begins as soon as all nodes have rejoined the cluster using the new binary. If you need the ability to [roll back a major-version upgrade](#roll-back-a-major-version-upgrade), you can disable auto-finalization and finalize the upgrade manually. Certain features and performance improvements, such as those that require changes to system schemas or objects, are not available until the upgrade is finalized. Refer to the {% if page.path contains 'cockroachcloud' %} [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %}){% else %}[{{ page.version.version }} Release Notes]({% link releases/{{ page.version.version }}.md %}).{% endif %}. diff --git a/src/current/_includes/releases/v24.3/upgrade-finalization.md b/src/current/_includes/releases/v24.3/upgrade-finalization.md index 0cdad527595..4cd49187ca0 100644 --- a/src/current/_includes/releases/v24.3/upgrade-finalization.md +++ b/src/current/_includes/releases/v24.3/upgrade-finalization.md @@ -1,4 +1,4 @@ During a major-version upgrade, certain features and performance improvements may not be available until the upgrade is finalized. -- A cluster must have an [Enterprise license]({% link {{ page.version.version }}/licensing-faqs.md %}#set-a-license) or a [trial license]({% link {{ page.version.version }}/licensing-faqs.md %}#obtain-a-license) set before an upgrade to {{ page.version.version }} can be finalized. -- New clusters that are initialized for the first time on {{ page.version.version }}, and clusters that are upgraded to {{ page.version.version }} will now have a [zone config]({% link {{ page.version.version }}/configure-zone.md %}) defined for the `timeseries` range if it does not already exist, which specifies the value for `gc.ttlseconds`, but inherits all other attributes from the zone config for the `default` range. +- A cluster must have an [Enterprise license]({% link v24.3/licensing-faqs.md %}#set-a-license) or a [trial license]({% link v24.3/licensing-faqs.md %}#obtain-a-license) set before an upgrade to v24.3 can be finalized. +- New clusters that are initialized for the first time on v24.3, and clusters that are upgraded to v24.3 will now have a [zone config]({% link v24.3/configure-replication-zones.md %}) defined for the `timeseries` range if it does not already exist, which specifies the value for `gc.ttlseconds`, but inherits all other attributes from the zone config for the `default` range. diff --git a/src/current/_includes/v24.2/backups/recommend-backups-for-upgrade.md b/src/current/_includes/v24.2/backups/recommend-backups-for-upgrade.md index 6cb563feab9..fe093883dad 100644 --- a/src/current/_includes/v24.2/backups/recommend-backups-for-upgrade.md +++ b/src/current/_includes/v24.2/backups/recommend-backups-for-upgrade.md @@ -1 +1,9 @@ -Because CockroachDB is designed with high fault tolerance, backups are primarily needed for [disaster recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}). However, taking regular backups of your data is an operational best practice. When upgrading to a major release, **we recommend [taking a backup]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) of your cluster**. \ No newline at end of file +{% if page.path contains "cockroachcloud" %} +[Managed backups]({% link cockroachcloud/managed-backups.md %}) are automated backups of CockroachDB {{ site.data.products.cloud }} clusters that are stored by Cockroach Labs in cloud storage. By default, Cockroach Labs takes and retains managed backups in all Cloud clusters. + +When upgrading to a major release, you can optionally [take a self-managed backup]({% link cockroachcloud/take-and-restore-self-managed-backups.md %}) of your cluster to your own cloud storage, as an extra layer of protection in case the upgrade leads to issues. +{% else %} +CockroachDB is designed with high fault tolerance. However, taking regular backups of your data is an operational best practice for [disaster recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) planning. + +When upgrading to a new major version, **we recommend [taking a self-managed backup]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) of your cluster** so that you can [restore the cluster to the previous version]({% link {{ page.version.version }}/restoring-backups-across-versions.md %}#support-for-restoring-backups-into-a-newer-version) if the upgrade leads to issues. +{% endif %} diff --git a/src/current/_includes/v24.2/upgrade_requirements.md b/src/current/_includes/v24.2/upgrade-requirements.md similarity index 100% rename from src/current/_includes/v24.2/upgrade_requirements.md rename to src/current/_includes/v24.2/upgrade-requirements.md diff --git a/src/current/cockroachcloud/upgrade-cockroach-version.md b/src/current/cockroachcloud/upgrade-cockroach-version.md index 483718bef3e..ff859c030c6 100644 --- a/src/current/cockroachcloud/upgrade-cockroach-version.md +++ b/src/current/cockroachcloud/upgrade-cockroach-version.md @@ -11,7 +11,7 @@ This page describes how major-version and patch upgrades work and shows how to u {% include common/upgrade/overview.md %} -{% include_cached {{ site.current_cloud_version }}/upgrade_requirements.md %} +{% include_cached {{ site.current_cloud_version }}/upgrade-requirements.md %} {% include common/upgrade/upgrade-high-level.md %} @@ -37,11 +37,11 @@ Refer to [Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). ### Finalize a major-version upgrade manually -{% include_cached finalize-cloud.md %} +{% include_cached common/upgrade/finalize-cloud.md %} ### Roll back a major-version upgrade -{% include_cached rollback-cloud.md %} +{% include_cached common/upgrade/rollback-cloud.md %} ## Troubleshooting @@ -49,4 +49,4 @@ Refer to [Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). ## See also -{% include see-also-cloud.md %} +{% include common/upgrade/see-also-cloud.md %} diff --git a/src/current/releases/v24.3.md b/src/current/releases/v24.3.md index 5090e6777e8..6830d5a321d 100644 --- a/src/current/releases/v24.3.md +++ b/src/current/releases/v24.3.md @@ -23,6 +23,16 @@ docs_area: releases {% include releases/whats-new-intro.md major_version=vers %} +{% comment %}Remove this block at GA and add the content to v24.3.0.md instead{% endcomment %} +

Backward-incompatible changes and deprecations

+ +Until v24.3 is Generally Available, review the backward-incompatible changes and deprecations listed in each testing release. + +{% comment %}Remove this block at GA and include the content in v24.3.0.md instead{% endcomment %} +

Features that require upgrade finalization

+ +{% include releases/v24.3/upgrade-finalization.md %} + {% for r in rel %} {% include releases/{{ page.major_version }}/{{ r.release_name }}.md release=r.release_name %} {% endfor %} diff --git a/src/current/v24.2/api-support-policy.md b/src/current/v24.2/api-support-policy.md index 81aca6fad8e..be770f94dfa 100644 --- a/src/current/v24.2/api-support-policy.md +++ b/src/current/v24.2/api-support-policy.md @@ -23,7 +23,7 @@ This page includes the following information: | Unstable | Supported for consumption by humans. Not supported for automation. | [Backward-incompatible changes](#backward-incompatible-changes) may be introduced in new major and patch versions. | | Reserved | Intended for use by CockroachDB developers. Not supported for public use. | N/A | -Backward-incompatible changes to **stable APIs** are highlighted in the [release notes]({% link releases/index.md %}#production-releases) for major CockroachDB versions. Users are asked to [consider backward-incompatible changes before upgrading]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#review-breaking-changes) to a new CockroachDB version. +Backward-incompatible changes to **stable APIs** are highlighted in the [release notes]({% link releases/index.md %}) for major CockroachDB versions. Users are asked to consider backward-incompatible changes before [upgrading]({% link releases/{{ page.version.version}}.md %}) to a new CockroachDB version. ### Backward-incompatible changes diff --git a/src/current/v24.3/api-support-policy.md b/src/current/v24.3/api-support-policy.md index 81aca6fad8e..be770f94dfa 100644 --- a/src/current/v24.3/api-support-policy.md +++ b/src/current/v24.3/api-support-policy.md @@ -23,7 +23,7 @@ This page includes the following information: | Unstable | Supported for consumption by humans. Not supported for automation. | [Backward-incompatible changes](#backward-incompatible-changes) may be introduced in new major and patch versions. | | Reserved | Intended for use by CockroachDB developers. Not supported for public use. | N/A | -Backward-incompatible changes to **stable APIs** are highlighted in the [release notes]({% link releases/index.md %}#production-releases) for major CockroachDB versions. Users are asked to [consider backward-incompatible changes before upgrading]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#review-breaking-changes) to a new CockroachDB version. +Backward-incompatible changes to **stable APIs** are highlighted in the [release notes]({% link releases/index.md %}) for major CockroachDB versions. Users are asked to consider backward-incompatible changes before [upgrading]({% link releases/{{ page.version.version}}.md %}) to a new CockroachDB version. ### Backward-incompatible changes diff --git a/src/current/v24.3/cluster-virtualization-overview.md b/src/current/v24.3/cluster-virtualization-overview.md index bf7a85c3c0f..681a3cc895e 100644 --- a/src/current/v24.3/cluster-virtualization-overview.md +++ b/src/current/v24.3/cluster-virtualization-overview.md @@ -48,7 +48,11 @@ To grant access to the system virtual cluster, you must connect to the system vi ### Upgrades -To upgrade to a new major version when cluster virtualization is enabled, you must first replace the binary on each node and restart the node, [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade on the system virtual cluster to upgrade it, then finalize the upgrade on a virtual cluster to upgrade it. This allows you to roll back an upgrade of the system virtual cluster without impacting schemas or data in virtual clusters. The system virtual cluster can be at most one major version ahead of virtual clusters. For example, a system virtual cluster on CockroachDB v24.1 can have virtual clusters on CockroachDB v23.2. +To upgrade to a new major version when cluster virtualization is enabled, you must: + +1. Replace the binary on each node and restart the node. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the system virtual cluster to upgrade it (if auto-finalization is disabled). +1. Finalize the upgrade on a virtual cluster to upgrade it (if auto-finalization is disabled). This allows you to roll back an upgrade of the system virtual cluster without impacting schemas or data in virtual clusters. The system virtual cluster can be at most one major version ahead of virtual clusters. For example, a system virtual cluster on CockroachDB v24.1 can have virtual clusters on CockroachDB v23.2. For details, refer to [Work with virtual clusters]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#upgrade-a-cluster). diff --git a/src/current/v24.3/install-cockroachdb-mac.md b/src/current/v24.3/install-cockroachdb-mac.md index 181fa386316..ef3894723cc 100644 --- a/src/current/v24.3/install-cockroachdb-mac.md +++ b/src/current/v24.3/install-cockroachdb-mac.md @@ -50,7 +50,7 @@ Use one of the options below to install CockroachDB. To upgrade an existing clus {{site.data.alerts.callout_success}} -If you previously installed CockroachDB via Homebrew, you can [upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}) the CockroachDB binary to the next major version or to a patch version using HomeBrew. After updating the binary on each node, restart the `cockroach` process on the node. When upgrading to a new major version, you must complete additional steps to [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade. If you need to upgrade through multiple major versions, you must complete each major-version upgrade separately, including finalizing the upgrade, before beginning the next one. +If you previously installed CockroachDB via Homebrew, you can [upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}) the CockroachDB binary to the next major version or to a patch version using HomeBrew. After updating the binary on each node, restart the `cockroach` process on the node. When upgrading to a new major version, you must complete additional steps to [finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade. If you need to upgrade through multiple major versions, you must complete each major-version upgrade separately, including finalizing the upgrade, before beginning the next one. Before starting the upgrade, review the [release notes]({% link releases/{{ page.version.version }}.md %}), including temporary limitations during the upgrade. diff --git a/src/current/v24.3/physical-cluster-replication-overview.md b/src/current/v24.3/physical-cluster-replication-overview.md index d710c58e959..5ca202bedf9 100644 --- a/src/current/v24.3/physical-cluster-replication-overview.md +++ b/src/current/v24.3/physical-cluster-replication-overview.md @@ -142,11 +142,11 @@ The standby cluster must be at the same version as, or one version ahead of, the When PCR is enabled, upgrade with the following procedure. This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster: -1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-4-perform-the-rolling-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade on the standby's system virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade on the primary's system virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade on the standby's virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade on the primary's virtual cluster. +1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's system virtual cluster if auto-finalization is disabled. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's system virtual cluster if auto-finalization is disabled. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's virtual cluster. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's virtual cluster. The standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster at the time of [cutover]({% link {{ page.version.version }}/cutover-replication.md %}). diff --git a/src/current/v24.3/restore.md b/src/current/v24.3/restore.md index e1d3ad489fb..a997bb47605 100644 --- a/src/current/v24.3/restore.md +++ b/src/current/v24.3/restore.md @@ -177,7 +177,7 @@ Also, consider that: - [Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}) will be restored to their original database during a full cluster restore. - The restore will drop the cluster's `defaultdb` and `postgres` [pre-loaded databases]({% link {{ page.version.version }}/show-databases.md %}#preloaded-databases) before the restore begins. You can only restore `defaultdb` and `postgres` if they are present in the original [backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}). - [Changefeed jobs]({% link {{ page.version.version }}/change-data-capture-overview.md %}) will not resume automatically on the new cluster. It is necessary to manually [create changefeeds]({% link {{ page.version.version }}/create-and-configure-changefeeds.md %}) after a full-cluster restore. -- When the cluster is in a mixed-version state during an [upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}), a full cluster restore will fail. To perform a full cluster restore, it is necessary to first [finalize the upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-3-decide-how-the-upgrade-will-be-finalized). +- When the cluster is in a mixed-version state during an [upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}), a full cluster restore will fail. To perform a full cluster restore, it is necessary to first [finalize the upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually). {{site.data.alerts.callout_info}} When you restore a full cluster with an {{ site.data.products.enterprise }} license, it will restore the [{{ site.data.products.enterprise }} license]({% link {{ page.version.version }}/licensing-faqs.md %}#types-of-licenses) of the cluster you are restoring from. If you want to use a different license in the new cluster, make sure to [update the license]({% link {{ page.version.version }}/licensing-faqs.md %}#set-a-license) **after** the restore is complete. diff --git a/src/current/v24.3/show-jobs.md b/src/current/v24.3/show-jobs.md index df220793598..35107a77636 100644 --- a/src/current/v24.3/show-jobs.md +++ b/src/current/v24.3/show-jobs.md @@ -61,7 +61,7 @@ The following fields are returned for each job: Field | Description ------|------------ `job_id` | A unique ID to identify each job. This value is used if you want to control jobs (i.e., [pause]({% link {{ page.version.version }}/pause-job.md %}), [resume]({% link {{ page.version.version }}/resume-job.md %}), or [cancel]({% link {{ page.version.version }}/cancel-job.md %}) it). -`job_type` | The type of job (e.g., [`SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`NEW SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer), [`KEY VISUALIZER`]({% link {{ page.version.version }}/ui-key-visualizer.md %}), [`MIGRATION`]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade), [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), [`IMPORT`]({% link {{ page.version.version }}/import-into.md %}), [`CHANGEFEED`](#show-changefeed-jobs), [`CREATE STATS`]({% link {{ page.version.version }}/create-statistics.md %}), [`ROW LEVEL TTL`]({% link {{ page.version.version }}/row-level-ttl.md %}), [`REPLICATION STREAM INGESTION`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}), or [`REPLICATION STREAM PRODUCER`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %})).

For job types of automatic jobs, see [Show automatic jobs](#show-automatic-jobs). +`job_type` | The type of job (e.g., [`SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`NEW SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer), [`KEY VISUALIZER`]({% link {{ page.version.version }}/ui-key-visualizer.md %}), [`MIGRATION`]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually), [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), [`IMPORT`]({% link {{ page.version.version }}/import-into.md %}), [`CHANGEFEED`](#show-changefeed-jobs), [`CREATE STATS`]({% link {{ page.version.version }}/create-statistics.md %}), [`ROW LEVEL TTL`]({% link {{ page.version.version }}/row-level-ttl.md %}), [`REPLICATION STREAM INGESTION`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}), or [`REPLICATION STREAM PRODUCER`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %})).

For job types of automatic jobs, see [Show automatic jobs](#show-automatic-jobs). `description` | The statement that started the job, or a textual description of the job. When you run `SHOW JOBS`, the `description` field is limited to 100 characters. To view the full description for a job, run `SHOW JOB {job ID}`. `statement` | When `description` is a textual description of the job, the statement that started the job is returned in this column. Currently, this field is populated only for the automatic table statistics jobs. `user_name` | The name of the [user]({% link {{ page.version.version }}/security-reference/authorization.md %}#create-and-manage-users) who started the job. diff --git a/src/current/v24.3/upgrade-cockroach-version.md b/src/current/v24.3/upgrade-cockroach-version.md index 2b906eb0e68..e455af59d80 100644 --- a/src/current/v24.3/upgrade-cockroach-version.md +++ b/src/current/v24.3/upgrade-cockroach-version.md @@ -11,7 +11,7 @@ This page describes how major-version and patch upgrades work and shows how to u {% include common/upgrade/overview.md %} -{% include_cached {{ page.version.version }}/upgrade_requirements.md %} +{% include_cached {{ page.version.version }}/upgrade-requirements.md %} CockroachDB's [multi-active availability]({% link {{ page.version.version }}/multi-active-availability.md %}) means that your cluster remains available while you upgrade one node at a time in a rolling fashion. While a node is being upgraded, its resources are not available to the cluster. @@ -33,13 +33,13 @@ CockroachDB's [multi-active availability]({% link {{ page.version.version }}/mul {% include_cached common/upgrade/major-version-upgrade-self-hosted.md %} -### Finalize a major-version upgrade +### Finalize a major-version upgrade manually -{% include finalize-self-hosted.md %} +{% include common/upgrade/finalize-self-hosted.md %} ### Roll back a major-version upgrade -{% include_cached rollback-self-hosted.md %} +{% include_cached common/upgrade/rollback-self-hosted.md %} ## Disable auto-finalization @@ -51,5 +51,4 @@ CockroachDB's [multi-active availability]({% link {{ page.version.version }}/mul ## See also -{% include see-also-self-hosted.md %} - +{% include common/upgrade/see-also-self-hosted.md %} diff --git a/src/current/v24.3/upgrade-cockroachdb-kubernetes.md b/src/current/v24.3/upgrade-cockroachdb-kubernetes.md index cac8b5bc5c4..6b4d702c1da 100644 --- a/src/current/v24.3/upgrade-cockroachdb-kubernetes.md +++ b/src/current/v24.3/upgrade-cockroachdb-kubernetes.md @@ -44,7 +44,7 @@ If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.versi {% include common/upgrade/major-version-upgrade-kubernetes.md %} -### Finalize a major-version upgrade +### Finalize a major-version upgrade manually {% include common/upgrade/finalize-kubernetes.md %} diff --git a/src/current/v24.3/work-with-virtual-clusters.md b/src/current/v24.3/work-with-virtual-clusters.md index b7c16035c0b..419cfc89931 100644 --- a/src/current/v24.3/work-with-virtual-clusters.md +++ b/src/current/v24.3/work-with-virtual-clusters.md @@ -166,11 +166,11 @@ For more details, including the scope of each cluster setting, refer to [Cluster ## Upgrade a cluster -To upgrade to a new major version when cluster virtualization is enabled , you must: +To upgrade to a new major version when cluster virtualization is enabled, you must: 1. Replace the binary on each node and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade) the upgrade on the system virtual cluster to upgrade it, or roll back the upgrade if you decide not to finalize it. Until it is finalized, the cluster still operates in compatibility with the previous major version, and virtual clusters cannot be upgraded. -1. After the system virtual cluster is finalized, finalize the upgrade on a virtual cluster to upgrade it, or roll back the upgrade if you decide not to finalize it. Until it is finalized, a virtual cluster still operates in compatibility with the previous major version, and some features may not be available on the virtual cluster. +1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the system virtual cluster to upgrade it (if auto-finalization is disabled) or roll back the upgrade if you decide not to finalize it. Until it is finalized, the cluster still operates in compatibility with the previous major version, and virtual clusters cannot be upgraded. +1. Finalize the upgrade on a virtual cluster to upgrade it, or roll back the upgrade if you decide not to finalize it. Until it is finalized, a virtual cluster still operates in compatibility with the previous major version, and some features may not be available on the virtual cluster. This allows you to roll back an upgrade of the system virtual cluster without impacting schemas or data in virtual clusters. The system virtual cluster can be at most one major version ahead of virtual clusters. For example, a system virtual cluster on CockroachDB v24.1 can have virtual clusters on CockroachDB v23.2.