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 21481e212b7..7cf933c20c4 100644 --- a/src/current/_includes/common/upgrade/major-version-upgrade-cloud.md +++ b/src/current/_includes/common/upgrade/major-version-upgrade-cloud.md @@ -2,20 +2,20 @@ This section shows how to perform a major-version upgrade for a cluster in Cockr 1. Verify the cluster's current major version, and which versions it can be upgraded to: 1. Sign into [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud). - 1. From the **Clusters** page, find the cluster by name. If the cluster is in a folder, click the name of the folder to view its descendants. The cluster's major version and patch are shown in the **Version** column. + 1. From the **Clusters** page, find the cluster by name. If the cluster is in a folder, click the name of the folder to find the cluster. The cluster's major version and patch are shown in the **Version** column. 1. Check which upgrades are available to the cluster, if any. Beginning with v24.1, major versions alternate in type between Regular releases, which are required, and Innovation releases, which can be skipped. From a Regular release, you can upgrade to the next major release (an Innovation release) or the subsequent major release (another Regular release). From an Innovation release, you must upgrade to the next Regular release. - These releases also provide different support periods. + These releases also provide different support periods. For details on their support periods and which releases are Regular or Innovation releases, refer the [CockroachDB Cloud Support Policy]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy). - For details, refer the [CockroachDB Cloud Support Policy]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy). + To check whether major-version upgrades are available, click the three-dot **Actions** menu. If upgrades are available, **Upgrade major version** will be enabled. Click it. In the dialog, if only one newer major version upgrade is available, it is selected automatically. If multiple upgrades are available, the latest Regular release is selected by default. If you intend to upgrade the cluster, keep this dialog open while completing the next steps. Otherwise, close the dialog. - To check whether major-version upgrades are available, click the three-dot **Action** menu. If upgrades are available, **Upgrade major version** will be enabled. Click it. In the dialog, if only one newer major version upgrade is available, it is selected automatically. If multiple upgrades are available, the latest Regular release is selected by default. If you intend to upgrade the cluster, keep this dialog open while completing the next steps. Otherwise, close the dialog. + In CockroachDB {{ site.data.products.standard }}, if the cluster is set to upgrade major versions automatically, the Actions menu will not show the **Upgrade major version** option. To change this setting, refer to [Manage cluster upgrades]({% link cockroachcloud/cluster-management.md %}#manage-cluster-upgrades). 1. Before beginning a major-version upgrade, review its [Release notes]({% link releases/index.md %}), as well as the release notes for any skipped Innovation Releases. If any backward-incompatible changes or new features impact the cluster's workloads, you may need to make adjustments before beginning the upgrade. -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** column in 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**. +1. A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster always 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**. After several seconds, the dialog closes, and the **Version** column in the **Cluster List** page changes to **Upgrading**, indicating the version to which you are upgrading the cluster. When the upgrade has finished but has not yet been finalized, the **Version** column reports that the new version is **pending finalization**. -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. +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/overview.md b/src/current/_includes/common/upgrade/overview.md index d0748be0975..41759e79831 100644 --- a/src/current/_includes/common/upgrade/overview.md +++ b/src/current/_includes/common/upgrade/overview.md @@ -1,18 +1,60 @@ -CockroachDB offers the following types of upgrades: +### Types of upgrades -- **Major-version upgrades**: A [major-version upgrade]({% link releases/index.md %}#major-releases) moves a cluster from one major version of CockroachDB to another, such as from v24.2 to v24.3. A major-version upgrade may include new features, updates to cluster setting defaults, and backward-incompatible changes. Performing a major-version upgrade requires an additional step to finalize the upgrade. +- **Major-version upgrades**: A [major-version upgrade]({% link releases/index.md %}#major-releases), such as from v24.2 to v24.3, may include new features, updates to cluster setting defaults, and backward-incompatible changes. Performing a major-version upgrade requires an additional step to finalize the upgrade. {% if page.path contains "cockroachcloud" %} - As of 2024, every second major version is an [Innovation release]({% link cockroachcloud/upgrade-policy.md %}#innovation-releases). For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }}, innovation releases offer shorter support windows and can be skipped. Innovation releases are required for CockroachDB {{ site.data.products.basic }}, and are applied automatically. + As of 2024, there are four major versions per year, where every second release is an [innovation release]({% link cockroachcloud/upgrade-policy.md %}#innovation-releases). For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }}, innovation releases offer shorter [support windows]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy) and can be skipped. For CockroachDB {{ site.data.products.basic }}, all major version upgrades are applied automatically as they become available, including innovation releases. {% else %} As of 2024, every second major version is an [Innovation release]({% link releases/release-support-policy.md %}#innovation-releases). Innovation releases offer shorter support windows and can be skipped. {% endif %} -- **Patch upgrades**: A [patch upgrade]({% link releases/index.md %}#patch-releases) moves a cluster from one patch to another within a major version, such as from v24.2.3 to v24.2.4. Patch upgrades do not introduce backward-incompatible changes. +- **Patch upgrades**: A [patch upgrade]({% link releases/index.md %}#patch-releases) moves a cluster from one patch release to another within a major version, such as from v24.2.3 to v24.2.4. Patch upgrades do not introduce backward-incompatible changes. + + A major version of CockroachDB has two phases of patch releases: a series of **testing releases** (beta, alpha, and RC releases) followed by a series of **production releases** (vX.Y.0, vX.Y.1, and so on). A major version’s first production release (the .0 release) is also known as its GA release. {% if page.path contains "cockroachcloud" %} - Patch upgrades are automatically applied to CockroachDB {{ site.data.products.advanced }}, {{ site.data.products.standard }}, and {{ site.data.products.basic }} clusters. + For CockroachDB {{ site.data.products.advanced }}, {{ site.data.products.standard }}, and {{ site.data.products.basic }} clusters, all production patch releases for a major version are automatically applied, until the cluster is upgraded to a new major version. {% endif %} - A major version of CockroachDB has two phases of patch releases: a series of **testing releases** followed by a series of **production releases**. A major version’s initial production release is also known as its GA release. In the lead-up to a new major version's GA release, a series of Testing releases may be made available{% if page.path contains "cockroachcloud" %} to CockroachDB {{ site.data.products.advanced }} as Pre-Production Preview releases{% endif %} for testing and validation. Testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments. {% if page.path contains "cockroachcloud" %}If a cluster is upgraded to a Pre-Production Preview patch release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview releases, the initial GA release, and subsequent patch releases.{% else %}{{site.data.alerts.callout_info}}A cluster cannot be upgraded from an alpha binary of a prior release or from a binary built from the `master` branch of the CockroachDB source code.{{site.data.alerts.end}}{% endif %} + - In the lead-up to a new major version's GA, a series of beta and RC releases {% if page.path contains "cockroachcloud" %}may be made available to CockroachDB {{ site.data.products.advanced }} as Pre-Production Preview releases{% else %}are made available{% endif %} for testing and validation. Testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments. + + {% if page.path contains "cockroachcloud" %}If a cluster is upgraded to a Pre-Production Preview release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview testing releases, the GA release, and subsequent production patch releases.{% else %}{{site.data.alerts.callout_info}}A cluster cannot be upgraded from an alpha binary of a prior release or from a binary built from the `master` branch of the CockroachDB source code.{{site.data.alerts.end}}{% endif %} To learn more about CockroachDB major versions and patches, refer to the [Releases Overview]({% link releases/index.md %}#overview). + +{% if page.path contains "cockroachcloud" %} +### Upgrade differences across Cloud plans + +CockroachDB Cloud plan | Major version upgrades | Innovation releases +---------------------- | ---------------------- | ---------------------- +Basic | Automatic | Required +Standard | Automatic (default) or customer-initiated | Optional +Advanced | Customer-initiated | Optional + +For all Cloud plans: + +- All major versions that are Regular releases (as opposed to Innovation releases) are required upgrades during the period in which they are supported. +- Patch version upgrades occur automatically. +{% endif %} +### Compatible versions + +A cluster may always be upgraded to the next major release. Prior to v24.1, every major release is required. As of v24.1{% if page.path contains "cockroachcloud" %}, for CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }} clusters{% endif %}: + +- If a cluster is running a major version that is labeled a Regular release, it can be upgraded to either the subsequent major version (an Innovation release) or the one after (the next Regular release, once it is available—skipping the Innovation release). + +- If a cluster is running a major version that is labeled an Innovation release, it can be upgraded only to the next Regular release. + +```mermaid +graph LR + v241["v24.1
Regular"] --> v242["v24.2
Innovation"] + v241 --> v243["v24.3
Regular"] + v242 --> v243 + v243 --> v251["v25.1
Innovation"] + v243 --> v252["v25.2
Regular"] + v251 --> v252 + v252 --> v253["v25.3
Innovation"] + v252 --> v254["v25.4
Regular"] + v253 --> v254 + + %% Styling + classDef default fill:#fff,stroke:#333,stroke-width:2px +``` 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 e8a7d0ee480..becdd7a2a1f 100644 --- a/src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md +++ b/src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md @@ -2,4 +2,4 @@ Before beginning a major-version upgrade: 1. Review the cluster's [Metrics page]({% link cockroachcloud/metrics.md %}) to ensure that your cluster's compute and storage capacity is within acceptable values. The cluster must be able to tolerate some increase, in case the new version uses more resources for your workload. If any of these metrics is above healthy limits, consider increasing the cluster's resources before beginning your upgrade. 1. {% include {{ site.current_cloud_version }}/backups/recommend-backups-for-upgrade.md %} -1. Review the [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %}), as well as the release notes for any skipped major version. Pay careful attention to the sections for backward-incompatible changes, deprecations, changes to default cluster settings, and features that are not available until the upgrade is finalized. +1. Review the [Release Notes for the major version]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions) to which you plan to upgrade, as well as the release notes for any skipped major version. Pay careful attention to the sections for backward-incompatible changes, deprecations, changes to default cluster settings, and features that are not available until the upgrade is finalized. diff --git a/src/current/_includes/common/upgrade/see-also-cloud.md b/src/current/_includes/common/upgrade/see-also-cloud.md index de43e2b731a..feb6329b341 100644 --- a/src/current/_includes/common/upgrade/see-also-cloud.md +++ b/src/current/_includes/common/upgrade/see-also-cloud.md @@ -1,2 +1,3 @@ - [Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}) - [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %}) +- Release notes for [additional supported versions]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions) \ No newline at end of file diff --git a/src/current/_includes/common/upgrade/upgrade-high-level.md b/src/current/_includes/common/upgrade/upgrade-high-level.md index f67f16dd8ec..42a56f94847 100644 --- a/src/current/_includes/common/upgrade/upgrade-high-level.md +++ b/src/current/_includes/common/upgrade/upgrade-high-level.md @@ -5,8 +5,12 @@ A major-version upgrade involves the following high-level steps, which are descr {% endif %} 1. On one node at a time: - 1. Replace the previous `cockroach` binary or container image with the new binary. - 1. Restart the `cockroach` process and verify that the node has rejoined the cluster. + 1. {% if page.path contains "cockroachcloud" %}The previous `cockroach` binary is replaced.{% else %}Replace the previous `cockroach` binary or container image with the new binary.{% endif %} + 1. {% if page.path contains "cockroachcloud" %}The `cockroach` process is restarted and the node rejoins the cluster.{% else %}Restart the `cockroach` process and verify that the node has rejoined the cluster.{% endif %} 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-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 %}. + 1. For a major-version upgrade, the upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade-manually). Certain features and performance improvements, such as those requiring changes to system schemas or objects, are not available until the upgrade is finalized. Refer to the {% if page.path contains 'cockroachcloud' %} [Release Notes for the major version]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions){% else %}[{{ page.version.version }} Release Notes]({% link releases/{{ page.version.version }}.md %}){% endif %} for details. + + {% if page.path contains "cockroachcloud" %}In CockroachDB {{ site.data.products.cloud }}, the cluster is finalized automatically after approximately 72 hours. During this time, you can choose to roll back the upgrade or manually finalize the cluster.{% else %}For self-hosted CockroachDB, automatic 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.{% endif %} + + Once a major-version upgrade is finalized, the cluster cannot be rolled back to the prior major version. diff --git a/src/current/_includes/v24.3/upgrade-requirements.md b/src/current/_includes/v24.3/upgrade-requirements.md index d729ee9c6ee..9a8c738b936 100644 --- a/src/current/_includes/v24.3/upgrade-requirements.md +++ b/src/current/_includes/v24.3/upgrade-requirements.md @@ -3,4 +3,4 @@ CockroachDB v24.3 is a Regular release. To upgrade to it, you must be running ei - [v24.2]({% link v24.2/upgrade-cockroach-version.md %}), the previous Innovation release. - [v24.1]({% link v24.1/upgrade-cockroach-version.md %}), the previous Regular release. -Before continuing, upgrade to an appropriate version. +If your cluster is running an earlier version, upgrade to one of these versions before proceeding. \ No newline at end of file diff --git a/src/current/cockroachcloud/cluster-management.md b/src/current/cockroachcloud/cluster-management.md index 868eee11751..3442fb2027e 100644 --- a/src/current/cockroachcloud/cluster-management.md +++ b/src/current/cockroachcloud/cluster-management.md @@ -61,18 +61,30 @@ To learn more, refer to [Plan a CockroachDB {{ site.data.products.standard }} cl ## Manage cluster upgrades +### Set major-version upgrades to automatic or manual + By default, major-version and patch upgrades are automatically applied to CockroachDB {{ site.data.products.standard }} clusters. To control when a cluster is upgraded to a new major version, you can disable automatic major-version upgrades. Patch upgrades are always applied automatically. {{site.data.alerts.callout_danger}} -If you disable automatic major-version upgrades for a cluster, to maintain support for the cluster, you must manually upgrade it to a later major version before its current version reaches [End of Support (EOS)]({% link cockroachcloud/upgrade-policy.md %}). +If you disable automatic major-version upgrades for a cluster, to maintain support for the cluster, you must manually upgrade it to a later major version before its current version reaches [End of Support (EOS)]({% link cockroachcloud/upgrade-policy.md %}). If you have not upgraded a cluster's major version for more than one year, it will be upgraded automatically. {{site.data.alerts.end}} To disable automatic major-version upgrades for a CockroachDB {{ site.data.products.standard }} cluster: -1. On the [**Cluster Overview** page for the cluster](#view-cluster-overview), click **Action**, then select **Manual upgrade settings**. +1. On the [**Cluster Overview** page for the cluster](#view-cluster-overview), click **Actions**, then select **Manual upgrade settings**. 1. Read the information provided, then set **Manual upgrades** to **on**. 1. Click **Apply**. +For manual upgrades to a newer major version of CockroachDB, refer to [Upgrade a cluster in CockroachDB Cloud]({% link cockroachcloud/upgrade-cockroach-version.md %}). + +### Automatic major-version upgrades + +When Manual upgrades is set to Off, a CockroachDB {{ site.data.products.standard }} cluster will automatically upgrade to a new major version. The version will be a production patch release (likely vXX.Y.1) that is made available soon after the initial GA release (vXX.Y.0). + +Before an upgrade is set to occur, a banner displayed in the Console informing you of the version to which the cluster will be upgraded. + +When the upgrade occurs, your cluster status will be listed as `Available (Maintenance)` and will remain operational. When the upgrade is complete, the new version will be indicated in the CockroachDB Cloud Console and you will receive an email notification. + ## Restore data from a backup Refer to [Managed Backups]({% link cockroachcloud/managed-backups.md %}) for instructions to restore your cluster from an automatic cluster backup. diff --git a/src/current/cockroachcloud/upgrade-cockroach-version.md b/src/current/cockroachcloud/upgrade-cockroach-version.md index e329e5e7813..b56f566084f 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 %} +A list of [currently supported major versions]({% link cockroachcloud/upgrade-policy.md %}#currently-supported-versions) with links to their release notes is available in the CockroachDB Cloud [Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). {% include common/upgrade/upgrade-high-level.md %} @@ -23,7 +23,7 @@ For CockroachDB {{ site.data.products.advanced }}, nodes are upgraded one at a t ### Upgrades and maintenance windows -If you have [configured a maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}) for a CockroachDB {{ site.data.products.advanced }} cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades must be initiated manually. +If you have [configured a maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}) for a CockroachDB {{ site.data.products.advanced }} cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades are initiated manually. {{site.data.alerts.callout_info}} Maintenance operations that are critical for cluster security or stability may be applied outside of the maintenance window, and upgrades that begin in a maintenance window may not always be completed by the end of the window. diff --git a/src/current/cockroachcloud/upgrade-policy.md b/src/current/cockroachcloud/upgrade-policy.md index 7f479648d5f..9b45499cfc9 100644 --- a/src/current/cockroachcloud/upgrade-policy.md +++ b/src/current/cockroachcloud/upgrade-policy.md @@ -19,19 +19,21 @@ A cluster running an unsupported CockroachDB version is not eligible for Cockroa All CockroachDB {{ site.data.products.basic }} clusters, and CockroachDB {{ site.data.products.standard }} clusters by default, will automatically be upgraded to the next major version while the current one is still supported, to prevent the cluster from reaching EOS. -- If you [disable automatic major-version upgrades for CockroachDB {{ site.data.products.standard }}]({% link cockroachcloud/cluster-management.md %}#manage-cluster-upgrades), you are responsible for upgrading the cluster before its version reaches its EOS date to maintain uninterrupted support and SLA guarantees. +- If you [disable automatic major-version upgrades for CockroachDB {{ site.data.products.standard }}]({% link cockroachcloud/cluster-management.md %}#manage-cluster-upgrades), you are responsible for upgrading the cluster before its version reaches its EOS date to maintain uninterrupted support and SLA guarantees. Clusters that have not upgraded for one year will be upgraded automatically. - You are responsible for upgrading a CockroachDB {{ site.data.products.advanced }} cluster before its current version reaches its EOS date to maintain uninterrupted support and SLA guarantees. -When a CockroachDB {{ site.data.products.advanced }} cluster is nearing its EOS date, you will be reminded to upgrade the cluster at least 30 days before the EOS date to avoid losing support. {% capture who_can_upgrade %}A [Cluster Administrator]({% link cockroachcloud/authorization.md %}#cluster-administrator) can [upgrade a cluster]({% link cockroachcloud/upgrade-cockroach-version.md %}) directly from the CockroachDB Cloud Console. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) or [Folder Admin]({% link cockroachcloud/authorization.md %}#folder-admin) can grant the Cluster Administrator role.{% endcapture %}{{ who_can_upgrade }} +When a CockroachDB {{ site.data.products.advanced }} cluster is nearing its EOS date, you will be reminded to upgrade the cluster at least 30 days before the EOS date to avoid losing support. {% capture who_can_upgrade %}A user with the Cluster Administrator or Cluster Operator [role]({% link cockroachcloud/authorization.md %}) can [upgrade a cluster]({% link cockroachcloud/upgrade-cockroach-version.md %}) directly from the CockroachDB Cloud Console. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can grant these roles.{% endcapture %}{{ who_can_upgrade }} ### Currently supported versions Version | Release Type | Support period | Release date | EOS date :------:|:------------:|:--------------:|:------------:|:---------: -v23.2 | Regular | 12 months | 2024-02-05 | 2025-02-05 -v24.1 | Regular | 12 months | 2024-05-20 | 2025-05-20 -v24.2 | Innovation | 6 months | 2024-08-12 | 2025-02-12 -v24.3 | Regular | 12 months | 2024-11-18 | 2025-11-18 +[v23.2]({% link releases/v23.2.md %}#v23-2-0-feature-highlights) | Regular | 12 months | 2024-02-05 | 2025-02-05 +[v24.1]({% link releases/v24.1.md %}#v24-1-0-feature-highlights) | Regular | 12 months | 2024-05-20 | 2025-05-20 +[v24.2]({% link releases/v24.2.md %}#v24-2-0-feature-highlights) | Innovation | 6 months | 2024-08-12 | 2025-02-12 +[v24.3]({% link releases/v24.3.md %}#v24-3-0-feature-highlights) | Regular | 12 months | 2024-11-18 | 2025-11-18 + +To review a version's release notes, click its link in the Version column. For expected future versions, refer to [Upcoming releases]({% link releases/index.md %}#upcoming-releases). @@ -43,11 +45,11 @@ Version | Release Type | Support period | Release date | EOS date ## Patch version upgrades -Patch version [releases](https://www.cockroachlabs.com/docs/releases), or "maintenance" releases, contain stable, backward-compatible improvements to the major versions of CockroachDB. +Patch version [releases]({% link releases/index.md %}), or "maintenance" releases, contain stable, backward-compatible improvements to major versions of CockroachDB. -For CockroachDB {{ site.data.products.advanced }} clusters, [Org Administrators]({% link cockroachcloud/authorization.md %}#org-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) during which available maintenance and patch upgrades will be applied. During the window, your cluster may experience restarts, degraded performance, and downtime for single-node clusters. Upgrades may not always be completed by the end of the window, and maintenance that is critical for security or stability may occur outside the window. Patch upgrades can also be [deferred for 60 days]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, CockroachDB {{ site.data.products.advanced }} clusters will be automatically upgraded to the latest supported patch version as soon as it becomes available. +For CockroachDB {{ site.data.products.advanced }} clusters, [Org Administrators]({% link cockroachcloud/authorization.md %}#org-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) during which available maintenance and patch upgrades will be applied. During the window, your cluster may experience node restarts, reduced performance, and, for single-node clusters, downtime. Upgrades may not always be completed by the end of the window, and maintenance that is critical for security or stability may occur outside the window. Patch upgrades can also be [deferred for 60 days]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, CockroachDB {{ site.data.products.advanced }} clusters will be automatically upgraded to the latest supported patch version as soon as it becomes available. -CockroachDB {{ site.data.products.basic }} and {{ site.data.products.standard }} clusters are subject to automatic upgrades to the latest supported patch version. +CockroachDB {{ site.data.products.basic }} and {{ site.data.products.standard }} clusters receive automatic upgrades to the latest supported patch version of their current major version. {{site.data.alerts.callout_danger}} Single-node clusters will experience some downtime while the node is restarted during cluster maintenance, including patch version upgrades. @@ -59,9 +61,9 @@ CockroachDB {{ site.data.products.advanced }} clusters are automatically upgrade A [Cluster Administrator]({% link cockroachcloud/authorization.md %}#cluster-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) for a CockroachDB {{ site.data.products.advanced }} cluster. During the maintenance window, patch upgrades may be applied, and the cluster may experience restarts, degraded performance, and, for single-node clusters, downtime. Upgrades may not always be completed by the end of the window, and maintenance that is critical for security or stability may occur outside of the window. A patch upgrade can be [deferred for 60 days]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, a CockroachDB {{ site.data.products.advanced }} cluster will be upgraded automatically to the latest supported patch version soon after it becomes available. -### CockroachDB {{ site.data.products.standard }} and {{ site.data.products.basic }} automatic upgrades +### CockroachDB {{ site.data.products.standard }} and {{ site.data.products.basic }} automatic patch upgrades -CockroachDB {{ site.data.products.standard }} clusters default to automatic upgrades for both new patch versions and new major versions. If you [disable manual upgrades]({% link cockroachcloud/cluster-management.md %}#manage-cluster-upgrades), to maintain support for the cluster, you must manually upgrade it to a later major version before its current version reaches End of Support (EOS). +CockroachDB {{ site.data.products.standard }} clusters default to automatic upgrades for both new patch versions and new major versions. If you [disable automatic upgrades]({% link cockroachcloud/cluster-management.md %}#manage-cluster-upgrades), you must manually upgrade it to a later major version before its current version reaches End of Support (EOS). After one year, CockroachDB {{ site.data.products.standard }} clusters will be automatically upgraded to the next major version, even if set for manual upgrades. CockroachDB {{ site.data.products.basic }} clusters are automatically upgraded to new patch versions, as well as new major versions, to maintain support. @@ -72,8 +74,8 @@ Major version [releases]({% link releases/index.md %}) contain new functionality Major version upgrades are: - Automatic for CockroachDB {{ site.data.products.basic }}. -- Enabled by default on {{ site.data.products.standard }} clusters. -- Not enabled on CockroachDB {{ site.data.products.advanced }}. +- Automatic by default for {{ site.data.products.standard }}. +- Customer-initiated on CockroachDB {{ site.data.products.advanced }}. On CockroachDB {{ site.data.products.standard }} with manual upgrades, and on CockroachDB {{ site.data.products.advanced }}, a major-version upgrade can be initiated by an [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator). Major versions labeled Regular releases are required upgrades, and Innovation releases are optional. When a new major version is available, you can [start an upgrade]({% link cockroachcloud/upgrade-cockroach-version.md %}) from the CockroachDB {{ site.data.products.cloud }} Console. The cluster will be upgraded to the latest patch release within that major version. @@ -82,8 +84,8 @@ On CockroachDB {{ site.data.products.standard }} with manual upgrades, and on Co As of v24.2, Cockroach Labs releases a major version of CockroachDB once per quarter, alternating between releases classified as a [Regular release or an Innovation release]({% link releases/index.md %}#release-types). Regular releases provide a longer support period and a longer period between upgrades, while Innovation releases offer a shorter support period and faster access to new features. -- Regular releases are not optional; they must be applied to CockroachDB {{ site.data.products.advanced }} and CockroachDB {{ site.data.products.standard }} clusters. They are applied automatically to CockroachDB {{ site.data.products.basic }} and {{ site.data.products.standard }} clusters. Regular releases are produced twice a year, alternating with Innovation Releases. They are supported for one year. It is supported to upgrade CockroachDB {{ site.data.products.advanced }} directly from one regular release to the next regular release and skip the intervening Innovation release. -- Innovation releases are optional and can be skipped for CockroachDB {{ site.data.products.advanced }} and CockroachDB {{ site.data.products.standard }} clusters but are required for CockroachDB {{ site.data.products.basic }}. Innovation releases are produced twice a year, alternating with Regular releases. An Innovation release is supported for 6 months, at which time the cluster must be upgraded to the next Regular Release. At a given time, only one Innovation release is typically supported. Upgrading a cluster directly from one Innovation release to the next Innovation release is not supported. +- Regular releases are not optional; they must be applied to CockroachDB {{ site.data.products.advanced }} and CockroachDB {{ site.data.products.standard }} clusters within their support periods. They are applied automatically to CockroachDB {{ site.data.products.basic }} and {{ site.data.products.standard }} clusters that are configured for automatic upgrades. Regular releases are produced twice a year, alternating with Innovation Releases. They are supported for one year. It is supported to upgrade CockroachDB {{ site.data.products.advanced }} directly from one regular release to the next regular release and skip the intervening Innovation release. +- Innovation releases are optional and can be skipped for CockroachDB {{ site.data.products.advanced }} and CockroachDB {{ site.data.products.standard }} clusters, but are required for CockroachDB {{ site.data.products.basic }}. Innovation releases are produced twice a year, alternating with Regular releases. An Innovation release is supported for 6 months, at which time the cluster must be upgraded to the next Regular Release. At a given time, only one Innovation release is typically supported. Upgrading a cluster directly from one Innovation release to the next Innovation release is not supported. {{site.data.alerts.callout_info}} To opt out of Innovation releases entirely and hide them from your CockroachDB organization, contact Support. @@ -98,7 +100,7 @@ To summarize the available major-version upgrade paths for CockroachDB {{ site.d ### Pre-production preview upgrades -Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.cloud }} organizations can create new CockroachDB {{ site.data.products.advanced }} clusters on a Pre-Production Preview release or upgrade an existing cluster to a Pre-Production Preview. Pre-Production Preview releases are beta or release candidate (RC) builds that next major version of CockroachDB, and are provided for testing and experimentation. Upgrading to a Pre-Production Preview is a major-version upgrade. After a cluster is upgraded to a Pre-Production Preview release, it is automatically upgraded to all subsequent releases within the same major version—including additional beta and RC releases, the GA release, and subsequent production patch releases as [patch version upgrades](#patch-version-upgrades). Upgrading to a Pre-Production Preview follows the same procedure as updating to a Production release. To learn more, refer to [Upgrade to {{ site.current_cloud_version }}]({% link cockroachcloud/upgrade-cockroach-version.md %}). +Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.cloud }} organizations can create new CockroachDB {{ site.data.products.advanced }} clusters on a Pre-Production Preview release or upgrade an existing cluster to a Pre-Production Preview. Pre-Production Preview releases are beta or release candidate (RC) builds that next major version of CockroachDB, and are provided for testing and experimentation. Upgrading to a Pre-Production Preview is a major-version upgrade. After a cluster is upgraded to a Pre-Production Preview release, it is automatically upgraded to all subsequent releases within the same major version—including additional beta and RC releases, the GA release, and subsequent production patch releases as [patch version upgrades](#patch-version-upgrades). Upgrading to a Pre-Production Preview follows the same procedure as updating to a Production release. To learn more, refer to [Upgrade a cluster in CockroachDB Cloud]({% link cockroachcloud/upgrade-cockroach-version.md %}). ### Rollback support