diff --git a/src/current/_config_cockroachdb.yml b/src/current/_config_cockroachdb.yml index c2533e5a626..f1eae8a8873 100644 --- a/src/current/_config_cockroachdb.yml +++ b/src/current/_config_cockroachdb.yml @@ -1,5 +1,5 @@ baseurl: /docs -current_cloud_version: v24.1 +current_cloud_version: v24.2 destination: _site/docs homepage_title: CockroachDB Docs versions: diff --git a/src/current/_includes/latest-release-details.md b/src/current/_includes/latest-release-details.md new file mode 100644 index 00000000000..2e75e28de80 --- /dev/null +++ b/src/current/_includes/latest-release-details.md @@ -0,0 +1,31 @@ +{% comment %} + This is included by v24.2+ install-cockroachdb-*.md upgrade-cockroach-version.md +{% endcomment %} + +{% assign DEBUG = false %} + +{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.version.version" | first %} +{% assign latest = site.data.releases | where_exp: "latest", "latest.major_version == page.version.version" | sort: "release_date" | last %} + +{% assign released = false %} +{% assign skippable = false %} +{% if rd.release_date != "N/A" and rd.maint_supp_exp_date != "N/A" %} + {% assign released = true %} + {% if rd.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + {% endif %} +{% endif %} + +{% if DEBUG == true %} +version: {{ rd }}

+latest release: {{ latest }}

+page version: {{ page.version }}

+released: {{ released }}
+skippable: {{ skippable }}
+{% endif %} + +CockroachDB {{ latest.major_version }} is the latest supported supported production release.{% if skippable == true %} It is an [Innovation release]({% link releases/release-support-policy.md %}#support-types) that is optional for CockroachDB {{ site.data.products.dedicated }} and CockroachDB {{ site.data.products.core }} but required for CockroachDB {{ site.data.products.serverless }}.{% else %} It is a required [Regular release]({% link releases/release-support-policy.md %}#support-types).{% endif %} To learn more, refer to [CockroachDB {{ latest.major_version }} Release Notes](https://cockroachlabs.com/docs/releases/{{ latest.major_version }}.html). + +{% if page.version.version != blank and page.version.version != latest.major_version %} +**This page refers to CockroachDB {{ page.version.version }}, not {{ latest.major_version }}.** +{% endif %} diff --git a/src/current/_includes/releases/v20.1/v20.1.0.md b/src/current/_includes/releases/v20.1/v20.1.0.md index 23e625c2ea7..f2bdcefba92 100644 --- a/src/current/_includes/releases/v20.1/v20.1.0.md +++ b/src/current/_includes/releases/v20.1/v20.1.0.md @@ -130,4 +130,4 @@ Docs | **"Hello World" Repos** | Added several language-specific [GitHub repos]( Docs | **Multi-Region Sample App and Tutorial** | Added a full-stack, multi-region sample application ([GitHub repo](https://github.com/cockroachlabs/movr-flask)) with an [accompanying tutorial](https://www.cockroachlabs.com/docs/v20.1/multi-region-overview) on building a multi-region application on a multi-region CockroachCloud cluster. Also added a [video demonstration](https://www.youtube.com/playlist?list=PL_QaflmEF2e8o2heLyIt5iDUTgJE3EPkp) as a YouTube playlist. Docs | **Streaming Changefeeds to Snowflake Tutorial** | Added an [end-to-end tutorial](https://www.cockroachlabs.com/docs/cockroachcloud/stream-changefeed-to-snowflake-aws) on how to use an Enterprise changefeed to stream row-level changes from CockroachCloud to Snowflake, an online analytical processing (OLAP) database. Docs | **Improved Backup/Restore Docs** | Updated the backup/restore docs to better separate [broadly applicable guidance and best practices](https://www.cockroachlabs.com/docs/v20.1/backup-and-restore) from more advanced topics. -Docs | **Release Support Policy** | Added a page explaining Cockroach Labs' [policy for supporting major releases of CockroachDB]({% link releases/release-support-policy.md %}), including the phases of support that each major release moves through, the currently supported releases, and an explanation of the [naming scheme]({% link releases/index.md %}#release-naming) used for CockroachDB. +Docs | **Release Support Policy** | Added a page explaining Cockroach Labs' [policy for supporting major releases of CockroachDB]({% link releases/release-support-policy.md %}), including the phases of support that each major release moves through, the currently supported releases, and an explanation of the [naming scheme]({% link releases/index.md %}#overview) used for CockroachDB. diff --git a/src/current/_includes/releases/whats-new-intro.md b/src/current/_includes/releases/whats-new-intro.md index e084ace9f01..0c7a15cb38e 100644 --- a/src/current/_includes/releases/whats-new-intro.md +++ b/src/current/_includes/releases/whats-new-intro.md @@ -1,9 +1,15 @@ -{% comment %}Early in development, a new major-version directory may not - yet exist. Adapt some links in this situation.{% endcomment %} +{% assign DEBUG = false %} {% assign branched = false %} -{% assign ancient = false %} +{% assign old = false %} +{% assign no_highlights = false %} +{% assign skippable = false %} +{% assign will_never_have_lts = false %} +{% assign lts = false %} {% assign install_links = '' %} +{% comment %}Early in development, a new major-version directory may not + yet exist. Adapt some links in this situation.{% endcomment %} + {% for file in site.pages %} {% unless branched == true %} {% capture fpath %}{{ file.dir | remove:'/' }}{% endcapture %} @@ -13,14 +19,28 @@ {% endunless %} {% endfor %} -{% comment %}Some old pages need different links to install and upgrade pages{% endcomment %} -{% if page.major_version == 'v1.0' or page.major_version == 'v1.1' or page.major_version == 'v2.0' or page.major_version == 'v2.1' or page.major_version == 'v21.1' %} +{% comment %}Some old pages don't have feature highlights and won't get LTS{% endcomment %} +{% if page.major_version == 'v1.0' or + page.major_version == 'v1.1' or + page.major_version == 'v2.0' or + page.major_version == 'v2.1' or + page.major_version == 'v19.1' or + page.major_version == 'v19.2' or + page.major_version == 'v20.1' or + page.major_version == 'v20.2' or + page.major_version == 'v21.1' or + page.major_version == 'v21.2' or + page.major_version == 'v22.1' or + page.major_version == 'v22.2' %} {% assign branched = true %} - {% assign ancient = true %} + {% assign no_highlights = true %} + {% assign will_never_have_lts = true %} +{% endif %} + +{% if page.major_version == 'v1.0' or page.major_version == 'v1.1' or page.major_version == 'v2.0' or page.major_version == 'v2.1' or page.major_version == 'v21.1' %} {% capture install_link %}[install CockroachDB](https://cockroachlabs.com/docs/{{ page.major_version}}/install-cockroachdb.html){% endcapture %} {% capture install_sentence %}After downloading a supported CockroachDB binary, learn how to {{ install_link }}.{% endcapture %} {% elsif page.major_version == 'v19.1' or page.major_version == 'v19.2' or page.major_version == 'v20.1' or page.major_version == 'v20.2' %} - {% assign branched = true %} {% capture install_link %}[install CockroachDB](https://cockroachlabs.com/docs/{{ page.major_version}}/install-cockroachdb.html){% endcapture %} {% capture upgrade_link %}[upgrade your cluster](https://cockroachlabs.com/docs/{{ page.major_version }}/upgrade-cockroach-version.html){% endcapture %} {% capture install_sentence %}After downloading a supported CockroachDB binary, learn how to {{ install_link }} or {{ upgrade_link }}.{% endcapture %} @@ -35,7 +55,36 @@ {% capture install_sentence %}After downloading a supported CockroachDB binary, learn how to {{ install_link }} or {{ upgrade_link }}.{% endcapture %} {% endif %} -On this page, you can read about changes and find downloads for all production and testing releases of CockroachDB {{ page.major_version }}. +{% comment %}Is it skippable or LTS?{% endcomment %} + +{% if include.major_version.release_date != "N/A" %} + {% if include.major_version.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + {% elsif include.major_version.initial_lts_patch != "N/A" %} + {% assign lts = true %} + {% endif %} +{% endif %} + +{% if DEBUG == true %} +include.major_version: {{ include.major_version }}
+page.major_version: {{ page.major_version }}
+branched: {{ branched }}
+will_never_have_lts: {{ will_never_have_lts }}
+lts: {{ lts }}
+skippable: {{ skippable }}
+no_highlights: {{ no_highlights }}
+
+{% endif %} + +{% if skippable == true %} +CockroachDB {{ page.major_version }} is an [Innovation Release]({% link releases/release-support-policy.md %}#support-types), which is optional for CockroachDB {{ site.data.products.dedicated }} and CockroachDB {{ site.data.products.core }} clusters but is required for CockroachDB {{ site.data.products.serverless }}. +{% else %} +CockroachDB {{ page.major_version }}{% if lts == true %} [(LTS)]({% link releases/release-support-policy.md %}#support-phases){% endif %} is a required [Regular Release]({% link releases/release-support-policy.md %}#support-types). +{% endif %} + +Refer to [Major release types]({% link releases/release-support-policy.md %}#support-types) before installing or upgrading for release timing and support details.{% if no_highlights == false %} To learn what’s new in this release, refer to its [Feature Highlights](#feature-highlights).{% endif %} + +On this page, you can read about changes and find downloads for all production and testing releases of CockroachDB {{ page.major_version }}{% if lts == true %} [(LTS)]({% link releases/release-support-policy.md %}#support-phases){% endif %} {% comment %}v1.0 has no #v1-0-0 anchor, and before GA other releases also do not.{% endcomment %} - For key feature enhancements in {{ page.major_version }} and other upgrade considerations, refer to the notes for {% if include.major_version.release_date != 'N/A' and page.major_version != 'v1.0' %}[{{ page.major_version }}.0](#{{ page.major_version | replace: '.', '-' }}-0){% else %}{{ page.major_version }} on this page{% endif %}. @@ -43,7 +92,7 @@ On this page, you can read about changes and find downloads for all production a - Be sure to also review the [Release Support Policy]({% link releases/release-support-policy.md %}). - {{ install_sentence | strip_newlines }} -{% comment %}The strip_newlines is needed here because otherwise Jekyll inserts

tags around the install and ugrade links{% endcomment %} +{% comment %}The strip_newlines is needed here because otherwise Jekyll inserts

tags around the install and upgrade links{% endcomment %} Get future release notes emailed to you: {% include_cached marketo.html formId=1083 %} diff --git a/src/current/_includes/unsupported-version.md b/src/current/_includes/unsupported-version.md index f5bd3de9c61..07965b76e5b 100644 --- a/src/current/_includes/unsupported-version.md +++ b/src/current/_includes/unsupported-version.md @@ -1,14 +1,15 @@ +{% comment %}Set to true to enable debug output on the page{% endcomment %} {% assign DEBUG=false %} + {% unless include.major_version %} Missing include.major_version. Usage: {% raw %}{% include unsupported-version.md major_version=page.major_version %}{% endraw %} {% break %} {% endunless %} -{% if DEBUG %}Major version: {{ include.major_version }}
{% endif %} {% comment %}To test, comment this line and uncomment the today and actual_today variables below{% endcomment %} {% assign today = "today" | date: "%s" %}{% comment %} Simulate future date and format it in seconds. {% endcomment %} -{% comment %} Some dates to test: +{% comment %} Some LTS dates to test: 2025-11-14: 23.1 LTS EOL (LTS EOL message) 2025-11-13: 23.1 LTS Assistance (LTS Assistance message) 2024-11-13: 23.1 LTS Maintenance (LTS Assistance message) @@ -20,8 +21,8 @@ The date logic in this file can be confusing. Read it like this: {% endcomment %} {% comment %}Uncomment the following two lines and comment the third to test a specific date{% endcomment %} -{% comment %}{% assign today = '2024-11-13' | date: "%s" %}{% endcomment %} -{% comment %}{% assign actual_today = "today" | date: "%s" %}{% endcomment %} +{% comment %}{% assign today = '2025-08-13' | date: "%s" %} +{% assign actual_today = "today" | date: "%s" %}{% endcomment %} {% if DEBUG %} {% if actual_today %}Actual today: {{ actual_today }}
{% endif %} @@ -37,130 +38,146 @@ Today date: {{ today | date: "%Y-%m-%d" }}
{% if DEBUG %}Major version object: {{ x }}
{% endif %} {% assign production = false %} + {% assign skippable = false %} {% assign lts = false %} - {% if DEBUG %}GA Maintenance support date: {{ x.maint_supp_exp_date }}
GA Assistance support date: {{ x.asst_supp_exp_date }}
{% endif %} {% comment %}Is it GA?{% endcomment %} - {% if x.asst_supp_exp_date != "N/A" and x.asst_supp_exp_date != "N/A" %} + {% if x.release_date != "N/A" and x.maint_supp_exp_date != "N/A" %} {% assign production = true %} {% assign m = x.maint_supp_exp_date | date: "%s" %} {% comment %} Format m_raw in seconds. {% endcomment %} - {% assign a = x.asst_supp_exp_date | date: "%s" %} {% comment %} Format a_raw in seconds. {% endcomment %} + + {% comment %}Is it skippable?{% endcomment %} + {% comment %}Skippable releases have no assistance period{% endcomment %} + {% if x.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + + {% else %} + {% assign a = x.asst_supp_exp_date | date: "%s" %} {% comment %} Format a_raw in seconds. {% endcomment %} + {% comment %} GA date validation will stop processing the include early {% endcomment %} + {% if a <= m %} + Error: Assistance date must be after Maintenance date. Check _data/versions.csv. Giving up. + {% break %} + {% endif %} + {% if x.asst_supp_exp_date == "N/A" %} + Required production releases must have asst_supp_exp_date set to a date. Giving up. Check versions.csv. + {% break %} + {% endif %} + {% endif %} {% endif %} - {% if production == true %} - {% comment %}Is it an LTS?{% endcomment %} - {% if x.initial_lts_patch != "N/A" %} - {% assign lts = true %} - {% assign lm = x.lts_maint_supp_exp_date | date: "%s" %} {% comment %} Format m_raw in seconds. {% endcomment %} - {% assign la = x.lts_asst_supp_exp_date | date: "%s" %} {% comment %} Format a_raw in seconds. {% endcomment %} + {% comment %}Required production releases may be LTS{% endcomment %} + {% if production == true and + x.lts_maint_supp_exp_date != "N/A" and + x.lts_asst_supp_exp_date != "N/A" and + x.initial_lts_release_date != "N/A" and + x.initial_lts_patch != "N/A" and + skippable == false %} + {% assign lts = true %} + {% assign lm = x.lts_maint_supp_exp_date | date: "%s" %} {% comment %} Format m_raw in seconds. {% endcomment %} + {% assign la = x.lts_asst_supp_exp_date | date: "%s" %} {% comment %} Format a_raw in seconds. {% endcomment %} + + {% comment %} LTS date validation will stop processing the include early {% endcomment %} + {% if la <= lm %} + Error: LTS assistance date must be after LTS maintenance date. Giving up. + {% break %} + {% endif %} + {% if la <= a or la <= m %} + Error: LTS assistance date must be after GA assistance and maintenance dates. Giving up. + {% break %} {% endif %} {% endif %} - {% if DEBUG %}LTS maintenance support date: {{ x.lts_maint_supp_exp_date }}
LTS assistance support date: {{ x.lts_asst_supp_exp_date }}
+ {% if DEBUG %} + include.major_version: {{ include.major_version }}
+ Production: {{ production }}
+ Maintenance support date: {{ x.maint_supp_exp_date }}
+ m: {{ m }}
+ skippable: {{ skippable }}
+ {% if skippable == false %}Assistance support date: {{ x.asst_supp_exp_date }}
+ a: {{ a }}
{% endif %} + LTS: {{ lts }}
+ {% if lts == true %}LTS maintenance support date: {{ x.lts_maint_supp_exp_date }}
+ LTS assistance support date: {{ x.lts_asst_supp_exp_date }}
la: {{ la }}
lm: {{ lm }}
{% endif %} {% endif %} -{% comment %}Save the admonitions into variables - The logic wrappers here make the variable empty - if the condition is false. The logic where these variables are used chooses which one of these variables to show, if any. - {% endcomment %} -{% capture lts_eol_message %} - {% if today > la %} - {{site.data.alerts.callout_danger}} - As of {{ x.lts_asst_supp_exp_date | date: "%B %e, %Y"}}, CockroachDB {{ include.major_version }} is no longer supported. For more details, refer to the Release Support Policy. - {{site.data.alerts.end}} - {% endif %} -{% endcapture %} + {% comment %}LTS releases starting with v23.1{% endcomment %} -{% capture lts_assistance_message %} - {% if today > lm %} - {{site.data.alerts.callout_danger}} - Maintenance Support for {{ include.major_version }} LTS releases ended on {{ x.lts_maint_supp_exp_date | date: "%B %e, %Y" }}{% if today >= a %}, and GA releases prior to {{ x.initial_lts_patch }} are no longer supported{% endif %}. Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} LTS on {{ x.lts_asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy. - {{site.data.alerts.end}} - {% endif %} -{% endcapture %} + {% if production == true %} + {% if lts == true %} + {% if today > la %} {% comment %}LTS assistance has passed, EOL{% endcomment %} -{% capture lts_maintenance_message %} - {% if today >= lm %} - {{site.data.alerts.callout_version}} - As of {{ x.lts_maint_supp_exp_date | date: "%B %e, %Y" }}, LTS releases of CockroachDB {{ x.major_version }} are in Maintenance Support{% if today > a %} and GA releases prior to {{ x.initial_lts_patch }} are no longer supported.{% endif %}. Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} LTS on {{ x.lts_asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy - {{site.data.alerts.end}} - {% endif %} -{% endcapture %} + {{site.data.alerts.callout_danger}} + As of {{ x.lts_asst_supp_exp_date | date: "%B %e, %Y"}}, CockroachDB {{ include.major_version }} is no longer supported. For more details, refer to the Release Support Policy. + {{site.data.alerts.end}} -{% capture ga_eol_message %} - {% if today > a %} - {{site.data.alerts.callout_danger}} - As of {{ x.asst_supp_exp_date | date: "%B %e, %Y"}}, CockroachDB {{ include.major_version }} is no longer supported. For more details, refer to the Release Support Policy. - {{site.data.alerts.end}} - {% endif %} -{% endcapture %} + {% elsif today > lm %} {% comment %}After LTS maintenance{% endcomment %} + + {{site.data.alerts.callout_danger}} + Maintenance Support for {{ include.major_version }} LTS releases ended on {{ x.lts_maint_supp_exp_date | date: "%B %e, %Y" }}{% if today >= a %}, and GA releases prior to {{ x.initial_lts_patch }} are no longer supported{% endif %}. Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} LTS on {{ x.lts_asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy. + {{site.data.alerts.end}} + + {% elsif today <= lm %}{% comment %}In LTS maintenance. Check for GA assistance is in the admonition {% endcomment %} + + {{site.data.alerts.callout_danger}} + As of {{ x.lts_maint_supp_exp_date | date: "%B %e, %Y" }}, LTS releases of CockroachDB {{ include.major_version }} releases are in Maintenance Support{% if today > a %} and GA releases of CockroachDB {{ include.major_version }} are no longer supported{% endif %}. Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} LTS on {{ x.lts_asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy + {{site.data.alerts.end}} + + {% endif %}{% comment %}If GA maintenance hasn't passed, show nothing{% endcomment %} + + {% comment %}Innovation releases starting from v24.2{% endcomment %} + {% elsif lts == false and skippable == true %} + + {% if DEBUG %}today: {{ today }}
m: {{ m }}
{% endif %} -{% capture ga_assistance_message %} {% if today > m %} - {{site.data.alerts.callout_danger}} - As of {{ x.maint_supp_exp_date | date: "%B %e, %Y" }}, Maintenance support for {{ include.major_version }} has ended, and Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} on {{ x.asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy. - {{site.data.alerts.end}} + {{site.data.alerts.callout_danger}} + As of {{ x.maint_supp_exp_date | date: "%B %e, %Y"}}, CockroachDB {{ include.major_version }} is no longer supported. Optional innovation releases are not eligible for Assistance Support. For more details, refer to the Release Support Policy. + {{site.data.alerts.end}} {% endif %} -{% endcapture %} -{% capture ga_maintenance_message %} - {% if today <= m and today > a %} - {{site.data.alerts.callout_version}} - As of {{ x.maint_supp_exp_date | date: "%B %e, %Y" }}, {{ include.major_version }} releases are in Maintenance Support. Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} on {{ x.asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy. - {{site.data.alerts.end}} - {% endif %} -{% endcapture %} + {% comment %}Non-LTS non-skippable, prior to v23.1{% endcomment %} + {% elsif lts == false and skippable == false %} - {% comment %}Show unsupported admonitions only for production releases {% endcomment %} - {% if production == true %} - {% comment %}Show LTS admonitions only for versions with LTS releases {% endcomment %} - {% if lts == true %} + {% comment %}Show Assistance message from the start of maintance until EOL{% endcomment %} + {% if today > a %} {% comment %}assistance has passed, EOL{% endcomment %} - {% if DEBUG %}lts: {{ lts }}
production: {{ production }}
lm: {{ lm }}
la: {{ la }}
m: {{ m }}
a: {{ a }}
{% endif %} + {{site.data.alerts.callout_danger}} + As of {{ x.asst_supp_exp_date | date: "%B %e, %Y"}}, CockroachDB {{ include.major_version }} is no longer supported. For more details, refer to the Release Support Policy. + {{site.data.alerts.end}} - {% comment %} LTS date validation will stop processing the include early {% endcomment %} - {% if la <= lm %} - Error: LTS assistance date must be after LTS maintenance date. Giving up. - {% break %} - {% endif %} - {% if la <= a or la <= m %} - Error: LTS assistance date must be after GA assistance and maintenance dates. Giving up. - {% break %} - {% endif %} + {% elsif today > m and today <= a %} {% comment %}maintenance has ended{% endcomment %} - {% comment %}Show LTS Maintenance message from the start of LTS maintance until LTS Assistance, - then show the LTS assistance message until EOL{% endcomment %} - {% if today > la %} {% comment %}LTS assistance has passed, EOL{% endcomment %} - {{ lts_eol_message }} - {% else %}{% comment %}LTS assistance has not passed {% endcomment %} - {% if today > lm %} {% comment %}After LTS maintenance{% endcomment %} - {{ lts_assistance_message }} - {% elsif today > m and today <= lm %}{% comment %}GA maintenance has passed, in LTS maintenance{% endcomment %} - {{ lts_maintenance_message }} - {% endif %}{% comment %}If GA maintenance hasn't passed, show nothing{% endcomment %} - {% endif %} + {{site.data.alerts.callout_danger}} + As of {{ x.maint_supp_exp_date | date: "%B %e, %Y" }}, Maintenance support for {{ include.major_version }} has ended, and Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} on {{ x.asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy. + {{site.data.alerts.end}} - {% comment %}Show non-LTS admonitions only releases without LTS {% endcomment %} - {% else %} + {% elsif today <= m %} - {% comment %} GA date validation will stop processing the include early {% endcomment %} - {% if a <= m %} - Error: Assistance date must be after Maintenance date. Check _data/versions.csv. Giving up. - {% break %} + {{site.data.alerts.callout_danger}} + As of {{ x.maint_supp_exp_date | date: "%B %e, %Y" }}, {{ include.major_version }} releases are in Maintenance Support and Cockroach Labs will stop providing Assistance Support for {{ include.major_version }} on {{ x.asst_supp_exp_date | date: "%B %e, %Y" }}. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy. + {{site.data.alerts.end}} {% endif %} - {% if DEBUG %}production: {{ production }}
m: {{ m }}
a: {{ a }}
{% endif %} - {% comment %}Show Assistance message from the start of maintance until EOL{% endcomment %} - {% if today > a %} {% comment %}assistance has passed, EOL{% endcomment %} - {{ ga_eol_message }} - {% else %} - {% if today > m %} {% comment %}maintenance has ended{% endcomment %} - {{ ga_assistance_message }} - {% elsif today <= m %} - {{ ga_maintenance_message }} - {% endif %} + {% else %} + Error: We should never hit this condition. Report this issue to #docs.
+ {% if DEBUG %} + Production: {{ production }}
+ Maintenance support date: {{ x.maint_supp_exp_date }}
+ m: {{ m }}
+ Skippable: {{ skippable }}
+ Assistance support date: {{ x.asst_supp_exp_date }}
+ a: {{ a }}
+ LTS: {{ lts }}
+ LTS maintenance support date: {{ x.lts_maint_supp_exp_date }}
+ LTS assistance support date: {{ x.lts_asst_supp_exp_date }}
+ la: {{ la }}
+ lm: {{ lm }}
{% endif %} + {% break %} {% endif %} + {% endif %}{% comment %}end production=true branch{% endcomment %} - {% endif %} -{% endif %} +{% else %} +Error: Could not find version details for {{ include.major_version }}. Check versions.csv. Giving up. + {% break %} +{% endif %}{% comment %}End branch to process x object{% endcomment %} diff --git a/src/current/_includes/v24.2/sidebar-data/cloud-deployments.json b/src/current/_includes/v24.2/sidebar-data/cloud-deployments.json index e91fec82150..d2049267f66 100644 --- a/src/current/_includes/v24.2/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v24.2/sidebar-data/cloud-deployments.json @@ -437,6 +437,12 @@ "/cockroachcloud/upgrade-policy.html" ] }, + { + "title": "Upgrade to v24.2", + "urls": [ + "/cockroachcloud/upgrade-to-v24.2.html" + ] + }, { "title": "Upgrade to v24.1", "urls": [ diff --git a/src/current/_includes/windows_warning.md b/src/current/_includes/windows_warning.md index 4b43e8e336c..5217edd8b71 100644 --- a/src/current/_includes/windows_warning.md +++ b/src/current/_includes/windows_warning.md @@ -1,3 +1,3 @@ {{site.data.alerts.callout_danger}} -The CockroachDB executable for Windows is experimental and not suitable for production deployments. Windows 8 or higher is required. +CockroachDB executable for Windows is experimental and not suitable for production deployments. Windows 8 or higher is required. {{site.data.alerts.end}} diff --git a/src/current/cockroachcloud/authorization.md b/src/current/cockroachcloud/authorization.md index a491f32487a..0ae5620a451 100644 --- a/src/current/cockroachcloud/authorization.md +++ b/src/current/cockroachcloud/authorization.md @@ -82,7 +82,7 @@ Cluster Operators can perform a variety of cluster functions: - View a cluster's Jobs from the [Jobs page]({% link cockroachcloud/jobs-page.md %}). - View a cluster's Metrics from the [Metrics page]({% link cockroachcloud/metrics-page.md %}). - View a cluster's Insights from the [Insights page]({% link cockroachcloud/insights-page.md %}). - - [Upgrade]({% link cockroachcloud/upgrade-to-v23.1.md %}#step-5-start-the-upgrade) a cluster's CRDB version. + - [Upgrade]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}) a cluster's CockroachDB version. - View a cluster's [PCI-readiness status (Dedicated Advanced clusters only)]({% link cockroachcloud/cluster-overview-page.md %}?filters=dedicated#pci-ready-dedicated-advanced). - Send a test alert from the [Alerts Page]({% link cockroachcloud/alerts-page.md %}). - Configure single sign-on (SSO) enforcement. diff --git a/src/current/cockroachcloud/create-a-serverless-cluster.md b/src/current/cockroachcloud/create-a-serverless-cluster.md index 8a64174aab3..bec9cbfd707 100644 --- a/src/current/cockroachcloud/create-a-serverless-cluster.md +++ b/src/current/cockroachcloud/create-a-serverless-cluster.md @@ -10,6 +10,8 @@ cloud: true This page guides you through the process of creating a cluster using CockroachDB {{ site.data.products.serverless }}. Only [CockroachDB {{ site.data.products.cloud }} Org Administrators]({% link cockroachcloud/authorization.md %}#org-administrator) or users with Cluster Creator / Cluster Admin roles assigned at organization scope can create clusters. If you need to create a cluster and do not have one of the required roles, contact your CockroachDB {{ site.data.products.cloud }} Administrator. +New CockroachDB {{ site.data.products.serverless }} clusters always use the latest stable version of CockroachDB, and are automatically [upgraded]({% link cockroachcloud/upgrade-to-{{ site.current_cloud_version }}.md %}) to new patch versions, as well as new major versions, to maintain uninterrupted support and SLA guarantees. For more details, refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). + ## Before you begin If you haven't already, sign up for a CockroachDB {{ site.data.products.cloud }} account. diff --git a/src/current/cockroachcloud/create-your-cluster.md b/src/current/cockroachcloud/create-your-cluster.md index 015d3408e68..82b320be9bc 100644 --- a/src/current/cockroachcloud/create-your-cluster.md +++ b/src/current/cockroachcloud/create-your-cluster.md @@ -157,11 +157,8 @@ When you create a new CockroachDB {{ site.data.products.dedicated }} cluster, it - **No label**: The latest patch of a Regular [Production release]({% link cockroachcloud/upgrade-policy.md %}) that is not the latest. A Regular release has full support for one year from the release date, at which a cluster must be [upgraded]({% link cockroachcloud/upgrade-policy.md %}) to maintain support. - **Latest**: The latest patch of the latest regular [Production release]({% link cockroachcloud/upgrade-policy.md %}). This is the default version for new clusters. -- **Pre-Production Version**: A [Pre-Production Preview]({% link cockroachcloud/upgrade-policy.md %}#pre-production-preview-upgrades). Leading up to a new CockroachDB Regular [Production release]({% link cockroachcloud/upgrade-policy.md %}), a series of Beta and Release Candidate (RC) patches may be made available for CockroachDB {{ site.data.products.dedicated }} as Pre-Production Preview releases. Pre-Production Preview releases are not suitable for production environments. They are no longer available in CockroachDB {{ site.data.products.cloud }} for new clusters or upgrades after the new version is GA. When the GA release is available, a cluster running a Pre-Production Preview is automatically upgraded to the GA release and subsequent patches and is eligible for support. - - {{site.data.alerts.callout_danger}} - Testing releases, including Pre-Production Preview releases, are provided for testing and experimentation only, and are not qualified for production environments and not eligible for support or uptime SLA commitments. - {{site.data.alerts.end}} +- **Innovation Release**: The latest patch of an [Innovation release]({% link cockroachcloud/upgrade-policy.md %}). Innovation releases are optional releases that provide earlier access to new features, and are released between regular releases. An Innovation release has full support for six months from the release date, at which time a cluster must be [upgraded]({% link cockroachcloud/upgrade-policy.md %}) to the next Regular release to maintain support. +- **Pre-Production Preview**: A [Pre-Production Preview]({% link cockroachcloud/upgrade-policy.md %}#pre-production-preview-upgrades). Leading up to a new CockroachDB Regular [Production release]({% link cockroachcloud/upgrade-policy.md %}), a series of Beta and Release Candidate (RC) patches may be made available for CockroachDB {{ site.data.products.dedicated }} as Pre-Production Preview releases. Pre-Production Preview releases are not suitable for production environments. They are no longer available in CockroachDB {{ site.data.products.cloud }} for new clusters or upgrades after the new version is GA. When the GA release is available, a cluster running a Pre-Production Preview is automatically upgraded to the GA release and subsequent patches and is eligible for support. 1. To choose a version for your cluster, select the cluster version from the **Cluster version** list. diff --git a/src/current/cockroachcloud/upgrade-policy.md b/src/current/cockroachcloud/upgrade-policy.md index 3ac7718365d..b4f5431f8b6 100644 --- a/src/current/cockroachcloud/upgrade-policy.md +++ b/src/current/cockroachcloud/upgrade-policy.md @@ -5,64 +5,99 @@ toc: true docs_area: manage --- -This page describes the support and upgrade policy for clusters deployed in CockroachDB {{ site.data.products.cloud }}. For CockroachDB Self-Hosted, refer to the CockroachDB [Release Support Policy](https://www.cockroachlabs.com/docs/releases/release-support-policy). +This page describes the support and upgrade policy for clusters deployed in CockroachDB {{ site.data.products.cloud }}. For CockroachDB {{ site.data.products.core }}, refer to the CockroachDB [Release Support Policy]({% link releases/release-support-policy.md %}). -Cockroach Labs uses a three-component calendar versioning scheme to name CockroachDB [releases](https://cockroachlabs.com/docs/releases/index#production-releases). The format is `YY.R.PP`, where `YY` indicates the year, `R` indicates the release (historically “1” or “2”, representing a biannual cycle), and `PP` indicates the patch release version. For example: Version 23.1.0 (abbreviated v23.1.0). Leading up to a new major version's initial GA (Generally Available) release, multiple testing builds are produced, moving from Alpha to Beta to Release Candidate. CockroachDB began using this versioning scheme with v19.1. For more details, refer to [Release Naming](https://cockroachlabs.com/docs/releases/index#release-naming). +## CockroachDB Cloud Support Policy -CockroachDB {{ site.data.products.cloud }} provides support for the latest major version of CockroachDB and the major version immediately preceding it. +[Major versions]({% link releases/index.md %}) of CockroachDB are labeled either [Regular releases]({% link releases/index.md %}#major-releases) or [Innovation releases]({% link releases/index.md %}). +- **Regular releases** are supported for 12 months from their initial production release date. +- **Innovation releases** are supported for 6 months from their initial production release date. -CockroachDB Dedicated clusters are automatically upgraded to the latest patch of the cluster’s current major version of CockroachDB, but an account administrator must initiate an upgrade to a new major version. +For each release type, the end date of this period is called End of Support (EOS). -CockroachDB Serverless clusters are upgraded to the latest major version and each patch automatically. +A cluster running an unsupported CockroachDB version is not eligible for Cockroach Labs’ [availability SLA](https://www.cockroachlabs.com/cloud-terms-and-conditions/cockroachcloud-technical-service-level-agreement/). -{{site.data.alerts.callout_success}} -Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.dedicated }} clusters can optionally be upgraded to a [Pre-Production Preview](#pre-production-preview-upgrades) release—a beta or release candidate (RC) testing release for testing and validation of that next major version. To learn more, refer to [Upgrade to v24.1 Pre-Production Preview]({% link cockroachcloud/upgrade-to-v24.1.md %}). -{{site.data.alerts.end}} +CockroachDB {{ site.data.products.serverless }} clusters will automatically be upgraded to the next major version while the current one is still supported, to prevent a Serverless cluster from reaching EOS. -## Patch version upgrades +A CockroachDB {{ site.data.products.dedicated }} cluster must be upgraded prior to its EOS date to maintain uninterrupted support and SLA guarantees. + +When a CockroachDB {{ site.data.products.dedicated }} 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-to-{{site.current_cloud_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 }} + +### 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 + +For expected future versions, refer to [Upcoming releases]({% link releases/index.md %}#upcoming-releases). -Patch version [releases](https://www.cockroachlabs.com/docs/releases), or "maintenance" releases, contain stable, backward-compatible improvements to the major versions of CockroachDB (for example, v23.1.12 and v23.1.13). +### EOS versions -For CockroachDB {{ site.data.products.dedicated }} clusters, [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window) during which available patch upgrades will be applied. During the window, your 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 the window. Patch upgrades can also be [deferred for 60 days]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, CockroachDB {{ site.data.products.dedicated }} clusters will be automatically upgraded to the latest supported patch version as soon as it becomes available. +Version | Release Type | Support period | Release date | EOS date +:------:|:------------:|:--------------:|:------------:|:--------: +|v23.1 | Regular | 12 months | 2023-05-15 | 2024-05-15 -CockroachDB {{ site.data.products.serverless }} clusters are subject to automatic upgrades to the latest supported patch version. +## Patch version upgrades + +A patch version [release]({% link releases/index.md %}), or "maintenance" releases, contains stable, backward-compatible improvements to a major version of CockroachDB. For example, {{site.current_cloud_version}} is a patch release. {{site.data.alerts.callout_danger}} -Single-node clusters will experience some downtime during cluster maintenance. +Single-node clusters will experience some downtime while the node is restarted during cluster maintenance, including patch version upgrades. {{site.data.alerts.end}} + +## CockroachDB {{ site.data.products.dedicated }} patch upgrades and maintenance windows + +CockroachDB {{ site.data.products.dedicated }} clusters are automatically upgraded to the latest patch version release of the cluster’s current CockroachDB major version, but a major-version upgrade must be initiated by an Org Administrator. + +A [Cluster Administrator]({% link cockroachcloud/authorization.md %}#cluster-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window) for a CockroachDB {{ site.data.products.dedicated }} 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/cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, a CockroachDB {{ site.data.products.dedicated }} cluster will be upgraded automatically to the latest supported patch version soon after it becomes available. + +### CockroachDB {{ site.data.products.serverless }} automatic upgrades + +CockroachDB {{ site.data.products.serverless }} clusters are automatically upgraded to new patch versions, as well as new major versions. + ## Major version upgrades -Major version [releases](https://www.cockroachlabs.com/docs/releases) (for example, v23.1.0 and v23.2.0) contain new functionality and may include backward-incompatible changes to CockroachDB. +Major version [releases](https://www.cockroachlabs.com/docs/releases) (for example, {{ site.current_cloud_version }}) contain new functionality and may include backward-incompatible changes to CockroachDB. -Major version upgrades are automatic for CockroachDB {{ site.data.products.serverless }} clusters and opt-in for CockroachDB {{ site.data.products.dedicated }} clusters. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) must initiate major version upgrades for CockroachDB {{ site.data.products.dedicated }} clusters. When a new major version is available, Admins will be able to [start an upgrade]({% link cockroachcloud/upgrade-to-v23.1.md %}) from the CockroachDB {{ site.data.products.cloud }} Console for clusters using CockroachDB {{ site.data.products.dedicated }}. When a major version upgrade is initiated for a cluster, it will upgrade to the latest patch version as well. +Major version upgrades are automatic for CockroachDB {{ site.data.products.serverless }} clusters and must be initiated by an [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) for CockroachDB {{ site.data.products.dedicated }} clusters. In CockroachDB {{ site.data.products.dedicated }}, major versions labeled Regular releases are all required upgrades, while Innovation releases are optional. Once a new major version is available, you can [start an upgrade]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}) from the CockroachDB Cloud Console. The cluster will be upgraded to the latest patch release within that major version. -### Pre-production preview upgrades + +### Innovation releases -Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.cloud }} organizations can create new {{ site.data.products.dedicated }} clusters or upgrade existing clusters to a Pre-Production Preview release for testing and experimentation using a beta or release candidate (RC) of that next major version. 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 patch releases after GA, as [patch version upgrades](#patch-version-upgrades). To learn more, refer to [Upgrade to v23.2 Pre-Production Preview](https://cockroachlabs.com/docs/cockroachcloud/upgrade-to-v24.1). +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. -### Rollback support +- Regular releases are not optional; they must be applied to CockroachDB {{ site.data.products.dedicated }} clusters and they are applied automatically to CockroachDB {{ site.data.products.serverless }} clusters. Regular releases are produced twice a year, alternating with Innovation Releases. They are supported for one year. Upgrading CockroachDB {{ site.data.products.dedicated }} directly from one regular release to the next regular release, skipping the intervening Innovation release, is supported. +- Innovation releases are optional and can be skipped for CockroachDB {{ site.data.products.dedicated }} clusters but are required for CockroachDB {{ site.data.products.serverless }}. Innovation releases are produced twice a year, alternating with Regular releases. An innovation release is supported for 6 months, at which time a Dedicated cluster must be upgraded to the next Regular Release. At a given time, only one Innovation release is typically supported. Upgrading CockroachDB {{ site.data.products.dedicated }} directly from one Innovation release to the next Innovation release is not supported. -When upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version, once all nodes are running the new version, you have approximately 72 hours before the upgrade is automatically finalized. During this window, if you see unexpected behavior, you can trigger a rollback to the previous major version from the CockroachDB {{ site.data.products.cloud }} Console. +{{site.data.alerts.callout_info}} +To opt out of Innovation releases entirely and hide them from your CockroachDB organization, contact Support.{{site.data.alerts.end}} -To stop the upgrade and roll back to the latest patch release of the previous major version, click **Roll back** in the banner at the top of the CockroachDB Cloud Console, and then click **Roll back upgrade**. +To summarize the available major-version upgrade paths for CockroachDB {{ site.data.products.dedicated }}: -{{site.data.alerts.callout_danger}} -If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of the previous major version, which may differ from the patch release you were running before you initiated the upgrade. -{{site.data.alerts.end}} +- When your cluster is running a Regular release, you can select which of the next two major versions to upgrade to: + - The next version, an Innovation release. + - The Regular release that follows that Innovation release, when it is available. +- When your cluster is running an Innovation release, you can upgrade only to the subsequent Regular release, not directly to the newer Innovation release, if it is available. + +### Pre-production preview upgrades -During rollback, nodes are reverted to that prior major version's latest patch one at a time, without interrupting the cluster's health and availability. +Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.cloud }} organizations can create new Dedicated clusters or upgrade existing clusters to a Pre-Production Preview release for testing and experimentation using a beta or release candidate (RC) of that next major version. 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-to-{{ site.current_cloud_version }}.md %}). -If you notice problems after a major version upgrade has been finalized, it will not be possible to roll back via the CockroachDB {{ site.data.products.cloud }} Console. For assistance, [contact support](https://support.cockroachlabs.com/hc/requests/new). +### Rollback support -### End of Support for CockroachDB versions +When upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version, once all nodes are running the new version, the upgrade is finalized automatically in approximately 72 hours. During this window, if you see unexpected behavior, you can [trigger a rollback]({% link cockroachcloud/upgrade-to-{{ site.current_cloud_version }}.md %}#roll-back-the-upgrade) to the previous major version from the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud). -As CockroachDB releases new major versions, older versions reach their End of Support (EOS) on CockroachDB {{ site.data.products.cloud }}. A CockroachDB version reaches EOS when it is two major versions behind the latest version. For example, when CockroachDB v21.2 was released, CockroachDB v20.2 reached EOS. +{{site.data.alerts.callout_info}} +If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of the previous major version, which may differ from the patch release you were running before you initiated the upgrade. +{{site.data.alerts.end}} -Clusters running unsupported CockroachDB versions are not eligible for our [availability SLA](https://www.cockroachlabs.com/cloud-terms-and-conditions/). Further downgrades in support may occur as per the [CockroachDB Release Support Policy](https://www.cockroachlabs.com/docs/releases/release-support-policy). +During rollback, nodes are reverted one at a time to reduce the impact of the operation on the cluster's health and availability. -If you are running a CockroachDB version nearing EOS, you will be reminded at minimum one month before that version’s EOS that your clusters must be upgraded by the EOS date to avoid losing support. A Org Administrator can [upgrade your cluster]({% link cockroachcloud/upgrade-to-v23.2.md %}) directly from the CockroachDB {{ site.data.products.cloud }} Console. +If you notice problems after a major version upgrade has been finalized, it will not be possible to roll back via the CockroachDB {{ site.data.products.cloud }} Console. For assistance, [contact Support](https://support.cockroachlabs.com/hc/requests/new). ## Additional information -For more details about the upgrade and finalization process, see [Upgrade to the Latest CockroachDB Version](https://cockroachlabs.com/docs/cockroachcloud/upgrade-to-v23.1). +For more details about the upgrade and finalization process in CockroachDB, refer to the instructions on [upgrading to the latest CockroachDB version]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}). diff --git a/src/current/cockroachcloud/upgrade-to-v23.2.md b/src/current/cockroachcloud/upgrade-to-v23.2.md index c12bf0aed67..e3f6e2dfa0f 100644 --- a/src/current/cockroachcloud/upgrade-to-v23.2.md +++ b/src/current/cockroachcloud/upgrade-to-v23.2.md @@ -16,7 +16,7 @@ pre_production_preview_version: v23.2.0-rc.2 [CockroachDB {{ page.pre_production_preview_version }}](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}#{{ page.pre_production_preview_version | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade for testing and experimentation. {{site.data.alerts.callout_danger}} -[Testing releases]({% link releases/index.md %}#release-naming) are not qualified for production environments and not eligible for support or uptime SLA commitments. +[Testing releases]({% link releases/index.md %}#overview) are not qualified for production environments and not eligible for support or uptime SLA commitments. {{site.data.alerts.end}} An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page guides you through the process of upgrading. diff --git a/src/current/cockroachcloud/upgrade-to-v24.1.md b/src/current/cockroachcloud/upgrade-to-v24.1.md index 9116975078c..306b8fb17ea 100644 --- a/src/current/cockroachcloud/upgrade-to-v24.1.md +++ b/src/current/cockroachcloud/upgrade-to-v24.1.md @@ -15,7 +15,8 @@ pre_production_preview_version: v24.1.0-rc.1 {% if page.pre_production_preview == true %} [CockroachDB {{ page.pre_production_preview_version }}](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}#{{ page.pre_production_preview_version | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade for testing and experimentation. -{{site.data.alerts.callout_danger}} [Testing releases]({% link releases/index.md %}#release-naming) are not qualified for production environments and not eligible for support or uptime SLA commitments. +{{site.data.alerts.callout_danger}} +[Testing releases]({% link releases/index.md %}#overview) are not qualified for production environments and not eligible for support or uptime SLA commitments. {{site.data.alerts.end}} An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page shows how to upgrade a CockroachDB {{ site.data.products.dedicated }} cluster to {{ page.pre_production_preview_version }} for testing and experimentation. diff --git a/src/current/cockroachcloud/upgrade-to-v24.2.md b/src/current/cockroachcloud/upgrade-to-v24.2.md new file mode 100644 index 00000000000..c93e0b56e67 --- /dev/null +++ b/src/current/cockroachcloud/upgrade-to-v24.2.md @@ -0,0 +1,285 @@ +--- +title: Upgrade to CockroachDB v24.2 +summary: Learn how to upgrade a cluster in CockroachDB Cloud to v24.2 +toc: true +docs_area: manage +page_version: v24.2 +pre_production_preview: false +--- +{% assign DEBUG = false %} + +{% comment %}Determine Cloud support{% endcomment %} + +{% comment %}Date to compare support dates against. To test, replace today with YYYY-MM-DD.{% endcomment %} +{% assign today = "today" | date: "%s" | plus: 0 %} + +{% comment %}Get the major version object{% endcomment %} +{% assign x = site.data.versions | where_exp: "m", "m.major_version == page.page_version" | first %} + +{% comment %}Is it Production?{% endcomment %} +{% assign released = false %} +{% if x.release_date == "N/A" and x.maint_supp_exp_date == "N/A" %} + {% comment %}Get the object for the latest Testing release in the major version{% endcomment %} + {% assign latest_patch = site.data.releases | where_exp: "releases", "releases.major_version == page.page_version" | where_exp: "releases", "release_type == Testing" | sort: "release_date" | reverse | first %} +{% else %} + {% comment %}Get the object for the latest Production release in the major version{% endcomment %} + {% assign released = true %} + {% assign latest_patch = site.data.releases | where_exp: "releases", "releases.major_version == page.page_version" | where_exp: "releases", "release_type == Production" | sort: "release_date" | reverse | first %} +{% endif %} + +{% if DEBUG == true %} +x: {{ x }}

+x.major_version: {{ x.major_version }}
+x.release_date: {{ x.release_date }}
+x.maint_supp_exp_date: {{ x.maint_supp_exp_date }}
+x.previous_version: {{ x.previous_version }}
+released: {{ released }}

+latest_patch: {{ latest_patch }}

+{% endif %} + +{% if released == true %} + {% assign release_date_seconds = x.release_date | date: "%s" %} + {% if x.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + {% endif %} +{% endif %} + +{% assign supported = false %} + +{% if released == true %} + + {% if skippable == true %} + {% assign eos_date_seconds = x.release_date | date: "%s" | plus: 15638400 %}{% comment %}6 months{% endcomment %} + {% assign purple_date = eos_date_seconds | minus: 5097600 %}{% comment %}2 months in seconds{% endcomment %} + {% assign red_date = eos_date_seconds | minus: 2678400 %}{% comment %}1 month in seconds{% endcomment %} + {% else %} + {% assign eos_date_seconds = 31536000 %}{% comment %}1 year{% endcomment %} + {% assign purple_date = eos_date_seconds | minus: 10368000 %}{% comment %}4 months in seconds{% endcomment %} + {% assign red_date = eos_date_seconds | minus: 5097600 %}{% comment %}2 months in seconds{% endcomment %} + {% endif %} + + {% if DEBUG == true %} + today: {{ today }}
+ x.asst_supp_exp_date: {{ x.asst_supp_exp_date }}
+ release_date_seconds: {{ release_date_seconds }}
+ eos_date_seconds: {{ eos_date_seconds }}
+ skippable: {{ skippable }}
+ purple_date: {{ purple_date }}
+ red_date: {{ red_date }}

+ {% endif %} + + {% assign eos = eos_date_seconds | date: '%B %d, %Y' %} + {% if today <= eos_date_seconds %} + {% assign supported = true %} + {% endif %} +{% endif %} + +{% if DEBUG == true %} +supported: {{ supported }}
+eos: {{ eos }}
+{% endif %} + +{% comment %}Detect EOS status and show admonitions accordingly{% endcomment %} +{% if released == true and supported == true %} + + {% if today >= red_date %} +{{site.data.alerts.callout_danger}} +Support for CockroachDB {{ x.major_version }} will end on **{{ eos}}** at the end of its Maintenance Support phase.{% if skippable == true %} Optional innovation releases are not eligible for Assistance Support.{% endif %} Prior to that date, upgrade to a newer version. For more details, refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). +{{site.data.alerts.end}} + + {% elsif today >= purple_date %} +{{site.data.alerts.callout_version}} +Support for CockroachDB {{ x.major_version }} will end on **{{ eos}}** at the end of its Maintenance Support phase.{% if skippable == true %} Optional innovation releases are not eligible for Assistance Support.{% endif %} Prior to that date, upgrade to a newer version. For more details, refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). +{{site.data.alerts.end}} + + {% endif %} + +{% elsif released == true and supported == false %} +{{site.data.alerts.callout_danger}} +As of **{{ eos }}**, CockroachDB {{ x.major_version }} is no longer supported.{% if skippable == true %} Optional innovation releases are not eligible for Assistance Support. {% endif %}For more details, refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). +{{site.data.alerts.end}} + +{% elsif released == false and supported == false %} +{{site.data.alerts.callout_info}} +CockroachDB {{ x.major_version }} is a testing release{% if page.pre_production_preview == false %} and is not yet available in CockroachDB {{ site.data.products.cloud }}{% endif %}. [Testing releases]({% link releases/index.md %}#release-naming) are not qualified for production environments and not eligible for support or uptime SLA commitments. This page is provided for reference only and is subject to change. For more details, refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). +{{site.data.alerts.end}} +{% endif %} + +{% comment %}Adapt the intro based on release and support status{% endcomment %} +{% if released == false and page.pre_production_preview == true %} +[CockroachDB {{ latest_patch.major_version }} Pre-Production Preview](https://www.cockroachlabs.com/docs/releases/{{ x.major_version }}#{{ latest_patch.release_name | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade for testing and experimentation. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page shows how to upgrade a CockroachDB {{ site.data.products.dedicated }} cluster to {{ latest_release.release_name }} Pre-Production Preview. + +{{site.data.alerts.callout_success}} +Upgrading from {{ x.previous_version }} to {{ x.major_version }} Pre-Production Preview is a major-version upgrade. Upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version is opt-in. Before proceeding, review the [CockroachDB Cloud Upgrade Policy](https://cockroachlabs.com/docs/cockroachcloud/upgrade-policy#pre-production-preview). 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 patch releases after GA, as patch version upgrades. To learn more, refer to [Patch Version Upgrades]({% link cockroachcloud/upgrade-policy.md %}#patch-version-upgrades). +{{site.data.alerts.end}} + +{% elsif released == true and supported == true %} +[CockroachDB {{ latest_patch.major_version }}](https://www.cockroachlabs.com/docs/releases/{{ x.major_version }}#{{ latest_patch.release_name | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page shows how to upgrade a CockroachDB {{ site.data.products.dedicated }} cluster to {{ latest_release.release_name }}. This page shows how to upgrade a CockroachDB {{ site.data.products.dedicated }} cluster to {{ latest_release.release_name }} Pre-Production Preview. + +{{site.data.alerts.callout_success}} +Upgrading from {{ x.previous_version }} to {{ x.major_version }} is a major-version upgrade. Upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version is opt-in. Before proceeding, review the [CockroachDB Cloud Upgrade Policy](https://cockroachlabs.com/docs/cockroachcloud/upgrade-policy#pre-production-preview). After a cluster is upgraded, it is automatically upgraded to all subsequent releases within the same major version as patch version upgrades. To learn more, refer to [Patch Version Upgrades]({% link cockroachcloud/upgrade-policy.md %}#patch-version-upgrades). +{{site.data.alerts.end}} + +{% elsif released == true and supported == false %} +[CockroachDB {{ latest_patch.major_version }}](https://www.cockroachlabs.com/docs/releases/{{ x.major_version }}#{{ latest_patch.release_name | replace: ".","-"}}) is no longer supported for new clusters or upgrades in CockroachDB {{ site.data.products.cloud }}. This page is provided for reference only. For details about currently-supported releases, refer to [CockroachDB Cloud Release Notes]({% link releases/cloud.md %}). +{% endif %} + +{% capture previous_version_numeric %}{{ x.major_version | remove_first: 'v' }}{% endcapture %} +{% capture major_version_numeric %}{{ x.previous_version | remove_first: 'v' }}{% endcapture %} + +{% if DEBUG == true %} +previous_version_numeric: {{ previous_version_numeric }}
+major_version_numeric: {{ major_version_numeric }}
+{% endif %} + +{% if released == true %} +CockroachDB {{ site.data.products.serverless }} clusters are upgraded automatically to new patch versions, as well as new major versions, to maintain uninterrupted support and SLA guarantees. +{% endif %} + +{% comment %}An unreleased version can't yet be skippable{% endcomment %} +{% if released == true %} +CockroachDB {{ x.major_version }} {% if supported == false %}was a{% else %}is a{% endif %}{% if skippable == true %}n [Innovation release]({% link cockroachcloud/upgrade-policy.md %}#major-version-upgrades), which {% if supported == false %}was{% else %}is{% endif %} optional for CockroachDB {{ site.data.products.dedicated }} clusters{% if supported == true %} but required for CockroachDB {{ site.data.products.serverless }}{% endif %}{% else %} [Regular release]({% link cockroachcloud/upgrade-policy.md %}#major-version-upgrades), which is a required upgrade for both CockroachDB {{ site.data.products.dedicated }} and CockroachDB {{ site.data.products.serverless }}.{% endif %} +{% endif %} + +Refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}) before installing or upgrading for release timing and support details. + +## Step 1. Verify that you can upgrade + +To upgrade to CockroachDB {{ x.major_version }}, you must be running {{ x.previous_version }}. If you are not running {{ x.previous_version }}, first [upgrade to {{ x.previous_version }}]({% link cockroachcloud/upgrade-to-{{ x.previous_version }}.md %}). Then return to this page and continue to [Step 2](#step-2-select-your-cluster-size). + +## Step 2. Select your cluster size + +The upgrade process depends on the number of nodes in your cluster. Select whether your cluster has multiple nodes or a single node: + +

+  +  +
+ +## Step 3. Understand the upgrade process + +
+In a multi-node cluster, the upgrade does not interrupt the cluster's overall health and availability. CockroachDB {{ site.data.products.cloud }} stops one node at a time and restarts it with the new version, waits a few minutes to observe the upgraded node's behavior, then moves on to the next node. This "rolling upgrade" takes approximately 4-5 minutes per node and is enabled by CockroachDB's [multi-active availability](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/multi-active-availability) design. +
+ +
+When you start the upgrade, the cluster will be unavailable for a few minutes while the node is stopped and restarted with {{ page.page_version }}. +
+ +If you are upgrading from {{ page.prev_version }} to {{ page.page_version }}, the upgrade must be finalized. This is not required for subsequent patch upgrades. Approximately 72 hours after all nodes are running {{ page.page_version }}, the upgrade will be automatically [finalized]({% link {{ page.page_version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade). It's important to monitor your cluster and applications during this 72-hour window, so that you can [roll back the upgrade](#roll-back-the-upgrade) from the CockroachDB {{ site.data.products.cloud }} Console if you see [unexpected behavior according to key metrics]({% link {{ page.page_version }}/essential-metrics-dedicated.md %}) or if you experience application or database issues. + +During a major-version upgrade, certain features and performance improvements may not be available until the upgrade is finalized. However, when upgrading to v24.2, all features are available immediately, and no features require finalization. + +{{site.data.alerts.callout_info}} +Finalization is always required to complete an upgrade. +{{site.data.alerts.end}} + +When finalization is complete, it is no longer possible to roll back to {{ x.previous_version }}. + +{{site.data.alerts.callout_info}} +If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of {{ x.previous_version }}, which may differ from the patch release you were running before you initiated the upgrade. To learn more, refer to [CockroachDB {{ site.data.products.cloud }} Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). +{{site.data.alerts.end}} + +When finalization begins, a series of migration jobs run to enable certain types of features and changes in the new major version that cannot be rolled back. These include changes to system schemas, indexes, and descriptors, and [enabling certain types of improvements and new features](#expect-temporary-limitations). Until the upgrade is finalized, these features and functions will not be available and the command `SHOW CLUSTER SETTING version` will return `{{ previous_version_numeric }}`. + +You can monitor the process of the migration in the CockroachDB {{ site.data.products.cloud }} [**Jobs** page]({% link cockroachcloud/jobs-page.md %}). Migration jobs have names in the format `{{ major_version_numeric }}-{migration-id}`. If a migration job fails or stalls, Cockroach Labs can use the migration ID to help diagnose and troubleshoot the problem. Each major version has different migration jobs with different IDs. + +Finalization is complete when all migration jobs have completed. After migration is complete, the command `SHOW CLUSTER SETTING version` will return `{{ major_version_numeric }}`. + +## Step 4. Prepare to upgrade + +Before starting the upgrade, complete the following steps. + +
+ +### Prepare for brief unavailability + +Your cluster will be unavailable while its single node is stopped and restarted with {{ x.major_version }}. Prepare your application for this brief downtime, typically a few minutes. + +The [**SQL Users**]({% link cockroachcloud/managing-access.md %}#create-a-sql-user) and [**Tools**]({% link cockroachcloud/tools-page.md %}) tabs in the CockroachDB {{ site.data.products.cloud }} Console will also be disabled during this time. + +
+ +### Review breaking changes + +{% comment %} Be careful with this logic and the page-level variable page_version {% endcomment %} +{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == x.major_version" | first %} + +{% if page.pre_production_preview == true %} +Review the backward-incompatible changes and deprecated features announced in each {{ x.major_version }} testing release. If any affect your applications, make the necessary changes before proceeding. +{% else %} +Review the backward-incompatible changes and deprecated features announced in the [{{ x.major_version }} release notes](../releases/{{ x.major_version }}.html). If any affect your applications, make the necessary changes before proceeding. +{% endif %} + +## Step 5. Start the upgrade + +To start the upgrade process: + +1. [Sign in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. + +1. In the **Clusters** list, select the cluster you want to upgrade. + +1. Select **Actions > Upgrade {% if page.pre_production_preview == true and supported == false %}to Pre-Production Preview{% else %}major version{% endif %}**. + +1. In the **Upgrade your cluster** dialog, review the pre-upgrade message and then click {% if page.pre_production_preview == true and supported == false %}to Pre-Production Preview{% else %}major version{% endif %}. + +
+Your cluster will be upgraded one node at a time without interrupting the cluster's overall health and availability. This "rolling upgrade" will take approximately 4-5 minutes per node. +
+ +
+Your single-node cluster will be unavailable for a few minutes while the node is stopped and restarted with CockroachDB {{ x.major_version }}. +
+ +After it is started, an upgrade cannot be cancelled. Instead, you can wait for the upgrade to finish, then [roll it back](#roll-back-the-upgrade) for up to 72 hours, after which time it will be finalized and cannot be rolled back. + +## Step 6. Monitor the upgrade + +Once your cluster is running CockroachDB {{ x.major_version }}, you will have approximately 72 hours before the upgrade is automatically finalized. During this time, it is important to [monitor your applications](#monitor-your-application) and [expect temporary limitations](#expect-temporary-limitations). + +If you see unexpected behavior, you can [roll back](#roll-back-the-upgrade) to {{ x.major_version }} during the 72-hour window. + +### Monitor your application + +Use the [DB Console]({% link cockroachcloud/tools-page.md %}) or your own tooling to monitor your application for any unexpected behavior. + +- If everything looks good, you can wait for the upgrade to automatically finalize or you can [manually trigger finalization](#finalize-the-upgrade). + +- If you see unexpected behavior, you can [roll back to the latest patch release of {{ x.previous_version }}](#roll-back-the-upgrade) during the 72-hour window. + +### Expect temporary limitations +{% comment %}This situation is unique to v24.2{% endcomment %} +All v24.2 features can be used right away. However, finalization is always required to complete a major-version upgrade. + +For an expanded list of features included in {{ x.major_version }}, temporary limitations, backward-incompatible changes, and deprecated features, refer to the [{{ x.major_version }} release notes]({% link releases/{{ x.major_version }}.md %}). + +### Roll back the upgrade + +If you see unexpected behavior, you can roll back the upgrade during the 72-hour window. + +To stop the upgrade and roll back to {{ x.previous_version }}, click **Roll back** in the banner at the top of the CockroachDB {{ site.data.products.cloud }} Console, and then click **Roll back upgrade**. + +
+During rollback, nodes will be reverted to the latest production patch release of {{ x.previous_version }} one at a time without interrupting the cluster's health and availability. +
+ +
+Because your cluster contains a single node, the cluster will be briefly unavailable while the node is stopped and restarted with the latest production patch release of {{ x.previous_version }}. Be sure to [prepare for this brief unavailability](#prepare-for-brief-unavailability) before starting the rollback. +
+ + + +## Step 7. Complete the upgrade + +If everything looks good, you can wait for the upgrade to automatically finalize after 72 hours, or you can manually finalize the upgrade to lift any [temporary limitations](#expect-temporary-limitations) on the cluster more quickly. + +To manually finalize the upgrade, click **Finalize** in the banner at the top of the CockroachDB {{ site.data.products.cloud }} Console, and then click **Finalize upgrade**. + +After finalization, any [temporary limitations](#expect-temporary-limitations) will be lifted and all {{ x.major_version }} features will be available for use. No such features exist for v24.2. + +After finalization, it will no longer be possible to roll back to {{ x.previous_version }}. If you see unexpected behavior after the upgrade has been finalized, [contact support](https://support.cockroachlabs.com/hc/requests/new). + +## See also + +- [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}) +- [CockroachDB {{ x.major_version }} Release Notes]({% link releases/{{ x.major_version }}.md %}) diff --git a/src/current/releases/cloud.md b/src/current/releases/cloud.md index 08097a6aff1..3c43e471e28 100644 --- a/src/current/releases/cloud.md +++ b/src/current/releases/cloud.md @@ -14,6 +14,24 @@ Get future release notes emailed to you: {% include marketo.html formId=1083 %} + +## August 12, 2024 + +

General updates

+ +- CockroachDB v24.2 is now generally available for CockroachDB {{ site.data.products.dedicated }}. CockroachDB v24.2 is an optional [Innovation release]({% link cockroachcloud/upgrade-policy.md %}#innovation-releases). Refer to [Create a CockroachDB {{ site.data.products.dedicated }} cluster]({% link cockroachcloud/create-your-cluster.md %}) or [Upgrade to v24.2]({% link cockroachcloud/upgrade-to-v24.2.md %}). + +- 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_. + + - [Regular releases]({% link cockroachcloud/upgrade-policy.md %}#regular-releases) are required; they must be applied to CockroachDB {{ site.data.products.dedicated }} clusters, and they are applied automatically to CockroachDB {{ site.data.products.serverless }} clusters. Regular releases are produced twice a year, alternating with Innovation releases. They are supported for one year. Upgrading CockroachDB {{ site.data.products.dedicated }} directly from one regular release to the next regular release, skipping the intervening Innovation release, is supported. + - [Innovation releases]({% link cockroachcloud/upgrade-policy.md %}#innovation-releases) are optional and can be skipped for CockroachDB {{ site.data.products.dedicated }} but are required for CockroachDB {{ site.data.products.serverless }}. Innovation releases are produced twice a year, alternating with Regular releases. An innovation release is supported for 6 months, at which time a CockroachDB {{ site.data.products.dedicated }} cluster must be upgraded to the next Regular release. At a a given time, only one Innovation release is typically supported. Upgrading CockroachDB {{ site.data.products.dedicated }} 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](https://support.cockroachlabs.com/hc). + {{site.data.alerts.end}} + + To learn more, refer to [CockroachDB {{ site.data.products.cloud }} Support and Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). + ## July 31, 2024

General updates

diff --git a/src/current/releases/index.md b/src/current/releases/index.md index 7469e1194e5..c17fcf77e6f 100644 --- a/src/current/releases/index.md +++ b/src/current/releases/index.md @@ -1,11 +1,8 @@ --- -title: Releases +title: CockroachDB Releases summary: Information about CockroachDB releases with an index of available releases and their release notes and binaries. toc: true docs_area: releases -toc_not_nested: true -pre_production_preview: true -pre_production_preview_version: v24.1.0-beta.1 --- {% comment %}Enable debug to print debug messages {% endcomment %} @@ -17,21 +14,119 @@ of this file, block-level HTML is indented in relation to the other HTML, and bl indented in relation to the other Liquid. Please try to keep the indentation consistent. Thank you! {% endcomment %} -After downloading a supported CockroachDB binary, learn how to [install CockroachDB](https://www.cockroachlabs.com/docs/stable/install-cockroachdb). Be sure to review Cockroach Labs' [Release Support Policy]({% link releases/release-support-policy.md %}). +{% assign all_production_releases = site.data.releases | where: "release_type", "Production" | sort: "release_date" | reverse %} +{% assign latest_full_production_version = all_production_releases | first %} -- **Generally Available (GA)** releases (also known as Production releases) are qualified for production environments. These may have either a default GA support type or an extended LTS (Long-Term Support) designation. Refer to [Release Support Policy]({% link releases/release-support-policy.md %}) for more information. -- **Testing** releases are intended for testing and experimentation only, and are not qualified for production environments and not eligible for support or uptime SLA commitments. Testing releases allow you to begin testing and validating the next major version of CockroachDB early. -- **Experimental** binaries allow you to deploy and develop with CockroachDB on architectures that are not yet qualified for production use. Experimental binaries are not eligible for support or uptime SLA commitments, whether they are for testing releases or production releases. +{% assign major_versions = all_production_releases | map: "major_version" | uniq | sort | reverse %} +{% assign latest_major_version_with_production = major_versions | first %} -For more details, refer to [Release Naming](#release-naming). For information about applicable software licenses, refer to [Licenses](#licenses). +## Overview + +This page explains the types and naming of CockroachDB releases and provides access to the release notes and downloads for all CockroachDB [releases](#downloads). + +A new major version of CockroachDB is released quarterly. After a series of testing releases, each major version receives an initial production release, follwed by a series of patch releases. + +Releases are named in the format `vYY.R.PP`, where `YY` indicates the year, `R` indicates the major release starting with `1` each year, and `PP` indicates the patch number, starting with `0`. + +For example, the latest production release is `{{ latest_full_production_version.release_name }}`, within major version [`{{ latest_major_version_with_production }}`]({% link releases/{{ latest_major_version_with_production }}.md %}). + +After choosing a version of CockroachDB, learn how to: + +- [Create a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/create-a-serverless-cluster.md %}). +- [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}). +- [Install CockroachDB {{ site.data.products.core }}]({% link {{site.current_cloud_version}}/install-cockroachdb.md %}) +- [Upgrade a Self-Hosted cluster]({% link {{site.current_cloud_version}}/upgrade-cockroach-version.md %}). + +Be sure to review Cockroach Labs' [Release Support Policy]({% link releases/release-support-policy.md %}) and review information about applicable [software licenses](#licenses). + +### Release types + +#### Major releases + +As of 2024, every second major version is an **Innovation release**. For CockroachDB {{ site.data.products.core }} and CockroachDB {{ site.data.products.dedicated }}, these releases offer shorter support windows and can be skipped. + +All other major versions are **Regular releases**, which are required upgrades. These versions offer longer support periods, which, for self-hosted clusters, are further extended when a patch version is announced that begins their **LTS** (Long-Term Support) release series. + +For details on how this impacts support in CockroachDB {{ site.data.products.core }}, refer to [Release Support Policy]({% link releases/release-support-policy.md %}). For details on support per release type in CockroachDB Cloud, refer to [CockroachDB Cloud Support and Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). + +| Major Release Type | Frequency | Required upgrade | LTS releases and extended support | +| :---: | :---: | :---: | :---: | +| Regular (e.g. v24.1) | 2x/year | on Dedicated, Serverless, Self-Hosted | Yes | +| Innovation (e.g. v24.2) | 2x/year | on Serverless only | No* | +* Column does not apply to CockroachDB Serverless, where clusters are automatically upgraded when a new major version or a patch release is available, ensuring continuous support. + +For a given CockroachDB {{ site.data.products.core }} or Dedicated cluster, customers may choose to exclusively install or upgrade to Regular Releases to benefit from longer testing and support lifecycles, or to also include Innovation Releases, and benefit from earlier access to new features. This choice does not apply to CockroachDB Serverless, where every major release is an automatic upgrade. + +CockroachDB v24.2 is an Innovation release and v24.3 is planned as a Regular release. Starting with v25.1, four major releases are expected per year, where every first and third release of the year is expected to be an Innovation release. For more details, refer to [Upcoming releases](#upcoming-releases). + +#### Patch releases + +A major version has two types 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. + + + + + + + + + + + + + + + + + + + + + + + +
Patch Release TypeNamingDescription
ProductionvYY.R.0 - vYY.R.n
(ex. v24.2.1)		Production releases are qualified for production environments. The type and duration of support for a production release may vary depending on the major release type, according to the Release Support Policy.
TestingvYY.R.0-alpha.1+,
vYY.R.0-beta.1+,
vYY.R.0-rc.1+
(ex. v24.3.1-alpha.2)		Produced during development of a new major version, testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments.
{{site.data.alerts.callout_danger}} -In CockroachDB v22.2.x and above, a cluster that is upgraded to an alpha binary of CockroachDB or a binary that was manually built from the `master` branch cannot subsequently be upgraded to a production release. +A cluster that is upgraded to an alpha binary of CockroachDB or a binary that was manually built from the `master` branch cannot subsequently be upgraded to a production release. {{site.data.alerts.end}} -## Staged release process +### Staged release process + +As of 2024, CockroachDB is released under a staged delivery process. New releases are made available for select CockroachDB Cloud organizations for two weeks before binaries are published for CockroachDB {{ site.data.products.core }} downloads. + +### Recent releases + +{% comment %} TODO: Automate by Aug 12, 2024, or update the morning of August 12, then automate soon after. {% endcomment %} +| Version | Release Type | GA date | Latest patch release | +| :---: | :---: | :---: | :---: | +| [v24.2](#v24-2) | Innovation | 2024-08-12 | v24.2.0 | +| [v24.1](#v24-1) | Regular | 2024-05-20 | v24.1.3 | +| [v23.2](#v23-2) | Regular | 2024-02-05 | v23.2.9 (LTS) | +| [v23.1](#v23-1) | Regular | 2023-05-15 | v23.1.24 (LTS) | + +### Upcoming releases -As of 2024, CockroachDB is released under a staged delivery process. New releases are made available for select CockroachDB Cloud organizations for two weeks before binaries are published for CockroachDB Self-Hosted downloads. +The following releases and their descriptions represent proposed plans that are subject to change. Please contact your account representative with any questions. + +| Version | Release Type | Expected GA date | +| :---: | :---: | :---: | +| v24.3 | Regular | 2024-11-18 | +| v25.1 | Innovation | 2025 Q1 | +| v25.2 | Regular | 2025 Q2 | +| v25.3 | Innovation | 2025 Q3 | +| v25.4 | Regular | 2025 Q4 | + +## Downloads {{ experimental_js_warning }} @@ -53,21 +148,31 @@ As of 2024, CockroachDB is released under a staged delivery process. New release {% for v in versions %} {% comment %} Iterate through all major versions {% endcomment %} - {% comment %}Determine if the major version is LTS and the patch component of the initial LTS patch{% endcomment %} + {% comment %} + Determine if the major version is LTS and the patch component of the initial LTS patch, + or the major version is a skippable innovation release + {% endcomment %} {% assign has_lts_releases = false %} {% assign lts_link_linux = '' %} {% assign lts_patch = nil %} {% assign in_lts = false %} {% assign comparison = nil %} + {% assign skippable = false %} {% if v.initial_lts_patch != "N/A" %} {% assign has_lts_releases = true %} {% assign lts_link = ' (LTS) ' %} {% capture lts_patch_string %}{{ v.initial_lts_patch | split: '.' | shift | shift }}{% endcapture %} {% assign lts_patch = lts_patch_string | times: 1 %}{% comment %}Cast string to integer {% endcomment %} + {% elsif v.release_date != "N/A" and v.maint_supp_exp_date != "N/A" and v.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} {% endif %} +### {{ v.major_version }} -## {{ v.major_version }} +{% assign skippable = false %} +{% if v.release_date != "N/A" and v.maint_supp_exp_date != "N/A" and v.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} +{% endif %} {% if DEBUG == true %} has_lts_releases: {{ has_lts_releases }}
@@ -77,7 +182,28 @@ As of 2024, CockroachDB is released under a staged delivery process. New release v.major_version: {{ v.major_version }}
has_lts_releases: {{ has_lts_releases }}
v.release_date: {{ v.release_date }}
- v.initial_lts_release_date: {{ v.initial_lts_release_date }}
{% endif %} + v.initial_lts_release_date: {{ v.initial_lts_release_date }}
+ skippable: {{ skippable }}

+{% endif %} + +CockroachDB {{ v.major_version }} is {% if skippable == true %}an [Innovation release]({% link releases/release-support-policy.md %}#innovation-releases) that is optional for CockroachDB {{ site.data.products.dedicated }} and CockroachDB {{ site.data.products.core }} but required for CockroachDB {{ site.data.products.serverless }}.{% else %}a required [Regular release]({% link releases/release-support-policy.md %}#regular-releases).{% endif %}{% if released == false %} It is still in development and not yet supported.{% endif %}{% unless latest_full_production_version.release_name != v.major_version %} CockroachDB {{ latest_full_production_version.release_name }} is the latest supported version.{% endunless %} To learn more, refer to [CockroachDB {{ latest.major_version }} Release Notes]({% link releases/{{ v.major_version }}.md %}). + +Refer to [Major release types](#major-releases) before installing or upgrading for release support details. +{% comment %}Some old pages don't have feature highlights and won't get LTS{% endcomment %} +{% unless v.major_version == 'v1.0' or + v.major_version == 'v1.1' or + v.major_version == 'v2.0' or + v.major_version == 'v2.1' or + v.major_version == 'v19.1' or + v.major_version == 'v19.2' or + v.major_version == 'v20.1' or + v.major_version == 'v20.2' or + v.major_version == 'v21.1' or + v.major_version == 'v21.2' or + v.major_version == 'v22.1' or + v.major_version == 'v22.2' %} +To learn what’s new in this release, refer to [Feature Highlights]({% link releases/{{ v.major_version }}.md %}#feature-highlights). +{% endunless %}
@@ -111,14 +237,14 @@ As of 2024, CockroachDB is released under a staged delivery process. New release {% assign v_docker_arm = false %} {% for r in releases %} - {% if r.docker.docker_arm == true %} + {% if r.docker.docker_arm == true %} {% assign v_docker_arm = true %} {% break %} {% endif %} {% endfor %} {% if releases[0] %} -### {{ s }} Releases +#### {{ s }} Releases
@@ -434,22 +560,6 @@ macOS downloads are **experimental**. Experimental downloads are not yet qualifi {% endfor %} {% comment %}for s in sections {% endcomment %} {% endfor %} {% comment %}for v in versions{% endcomment %} -## Release naming - -Cockroach Labs uses a three-component calendar versioning scheme to name CockroachDB [releases](https://cockroachlabs.com/docs/releases/index#production-releases). The format is `YY.R.PP`, where `YY` indicates the year, `R` indicates the release (historically “1” or “2”, representing a typical biannual cycle), and `PP` indicates the patch release version. Example: Version 23.1.0 (abbreviated v23.1.0). Leading up to a new major version's initial GA (Generally Available) release, multiple testing builds are produced, moving from Alpha to Beta to Release Candidate. CockroachDB began using this versioning scheme with v19.1. - -A major release is typically produced twice a year indicating major enhancements to product functionality. A change in the `YY.R` component denotes a major release. - -Patch releases are produced during the [support period]({% link releases/release-support-policy.md %}) for a major version to roll out critical bug and security fixes. A change in the `PP` component denotes a patch release. - -During development of a major version of CockroachDB, releases are produced according to the following patterns. Alpha, Beta, and Release Candidate releases are testing releases intended for testing and experimentation only, and are not qualified for production environments and not eligible for support or uptime SLA commitments. - -- Alpha releases are the earliest testing releases leading up to a major version's initial GA (generally available) release, and have `alpha` in the version name. Example: `v23.1.0-alpha.1`. -- Beta releases are produced after the series of alpha releases leading up to a major version's initial GA release, and tend to be more stable and introduce fewer changes than alpha releases. They have `beta` in the version name. Example: `v23.1.0-beta.1`. -- Release candidates are produced after the series of beta releases and are nearly identical to what will become the initial generally available (GA) release. Release candidates have `rc` in the version name. Example: `v23.1.0-rc.1`. -- A major version's initial GA release is produced after the series of release candidates for a major version, and ends with `0`. Example: `v23.1.0`. GA releases are validated and suitable for production environments. -- Patch (maintenance) releases are produced after a major version's GA release, and are numbered sequentially. Example: `v23.1.13`. - ## Licenses Unless otherwise noted, all binaries available on this page are variously licensed under the Business Source License 1.1 (BSL), the CockroachDB Community License (CCL), and other licenses specified in the source code. To determine whether BSL or CCL applies to a CockroachDB feature, refer to the [Licensing FAQs](https://www.cockroachlabs.com/docs/stable/licensing-faqs) page under Feature Licensing. The default license for any feature that is not listed is the CCL. diff --git a/src/current/releases/release-support-policy.md b/src/current/releases/release-support-policy.md index e897b9b4229..992dd9e2bcb 100644 --- a/src/current/releases/release-support-policy.md +++ b/src/current/releases/release-support-policy.md @@ -2,51 +2,65 @@ title: Release Support Policy summary: Learn about Cockroach Labs' policy for supporting major releases of CockroachDB. toc: true +toc_not_nested: true docs_area: releases --- +{% assign DEBUG = false %} {% assign today = "today" | date: "%Y-%m-%d" %} {% comment %} Fetch today's date. {% endcomment %} {% assign versions = site.data.versions | where_exp: "versions", "versions.release_date <= today" | sort: "release_date" | reverse %} {% comment %} Get all versions (e.g., v21.2) sorted in reverse chronological order. {% endcomment %} -This page explains Cockroach Labs' policy for supporting [production releases]({% link releases/index.md %}) of CockroachDB Self-Hosted. For clusters deployed in {{ site.data.products.cloud }}, refer to the [CockroachDB {{ site.data.products.cloud }} Support and Upgrade Policy](https://www.cockroachlabs.com/docs/cockroachcloud/upgrade-policy). +This page explains Cockroach Labs' policy for supporting [production releases]({% link releases/index.md %}) of CockroachDB {{ site.data.products.core }}. For clusters deployed in {{ site.data.products.cloud }}, refer to the [CockroachDB {{ site.data.products.cloud }} Support and Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). -There are two support types: GA and LTS (Long-Term Support). Each patch release of CockroachDB is assigned one of these types. The default is GA, unless otherwise specified. - -Initially, a major release series has GA support. After the series demonstrates a continuously high level of stability and performance, new patch releases are designated as LTS releases, which provide extended support windows. Specifically, the distinction determines the time spans of a release’s support phases: Maintenance Support, Assistance Support, and EOL (End of Life). +There are two major release types: [Regular and Innovation releases]({% link releases/index.md %}#release-types). Each offers a unique set of Support Types, which define the durations for each [support phase](#support-phases). ## Support Phases -- **Maintenance Support**: Cockroach Labs will produce regular patch releases that include critical security fixes and resolutions to problems identified by users. - -- **Assistance Support**: Immediately follows the Maintenance Support period. During this period, the following guidelines apply: - - New enhancements will not be made to the major release. +- **Maintenance Support**: Begins for a CockroachDB major version upon its [GA release]({% link releases/index.md %}#patch-releases). During this phase: + - Cockroach Labs will produce regular patch releases that include critical security fixes and resolutions to problems identified by users. + - Cockroach Labs may backport non-breaking enhancements produced for newer major versions. + - Cockroach Labs may direct customers to workarounds or other fixes applicable to a reported case. + - Cockroach Labs may recommend that customers [upgrade](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version) to a later version of the product to resolve or further troubleshoot an issue. +- **Assistance Support**: Immediately follows the Maintenance Support phase for Regular releases. Innovation releases do not have an Assistance Support phase. During this phase: + - Feature enhancements will no longer be made available to the major release. - Cockroach Labs will continue to add critical security fixes to the major release in the form of patch releases. - Patch releases for the purpose of resolving bugs or other errors may no longer be made to the major release. - Cockroach Labs may direct customers to workarounds or other fixes applicable to the reported case. - - Cockroach Labs may direct customers to [upgrade](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version) to a later version of the product, to resolve or further troubleshoot an issue. - -- **End of Life (EOL)**: Following the assistance support period, Cockroach Labs will no longer provide any support for the release. + - Cockroach Labs may direct customers to [upgrade](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version) to a later version of CockroachDB to resolve or further troubleshoot an issue. +- **End of Life (EOL)**: The day that a major version’s final support period ends is its EOL date. After a version reaches EOL, Cockroach Labs provides no further support for the release. + - A Regular release reaches EOL at the Assistance Support phase's end date. + - An Innovation releases reaches EOL at the Maintenance Support phase's end date. ## Support Types -* **GA Support**: The default support type for production releases, starting with the initial production release of a major version, followed by each subsequent patch release before LTS releases begin for that major version. - * **Maintenance support ends**: - * **365 days** **after** the day of the **first production release** of the major version (i.e. the ‘GA release,’ ending in .0). - * **Assistance support ends**: - * **180 days after** the **Maintenance Support end date** of the release. - * Major versions prior to v23.1 will not have LTS releases. -* **LTS (Long-Term Support)**: Conferred to an initial LTS maintenance release of a given major version and its subsequent maintenance releases. LTS provides extended support windows while also indicating our highest level of expected release stability and performance. - * **Maintenance support ends**: - * **365 days** **after** the day of the **first LTS release** of the major version. - * **Assistance support ends**: - * **365 days after** the **Maintenance Support end date** of the release. +### Regular releases + +Initially, a Regular release series has GA Support. After the series demonstrates a continuously high level of stability and performance, new patch releases are designated as LTS releases, which have an extended support window for each [support phase](#support-phases): Maintenance Support, Assistance Support, and EOL (End of Life). + +- **GA Support**: The default support type for production releases, starting with the initial production release of a major version, followed by each subsequent patch release before LTS releases begin for that major version. + - **Maintenance support ends**: + - **365 days** **after** the day of the **first production release** of the major version (i.e. the ‘GA release,’ ending in .0). + - **Assistance support ends**: + - **180 days after** the **Maintenance Support end date** of the release. + - Major versions prior to v23.1 will not have LTS releases. +- **LTS (Long-Term Support)**: Conferred to an initial LTS maintenance release of a given major version and its subsequent maintenance releases. LTS provides extended support windows while also indicating our highest level of expected release stability and performance. + - **Maintenance support ends**: + - **365 days** **after** the day of the **first LTS release** of the major version. + - **Assistance support ends**: + - **365 days after** the **Maintenance Support end date** of the release. + +### Innovation releases + +Innovation releases do not have LTS releases. -## Current supported releases +- **Innovation Support**: + - **Maintenance Support ends:** + - **180 days after** the day of the **first production release** of the major version. -As of v19.1, Cockroach Labs uses a three-component calendar versioning scheme. Prior releases use a different versioning scheme. For more details, see [Release Naming]({% link releases/index.md %}#release-naming). +Innovation releases are not eligible for Assistance Support, and reach EOL at the end of Maintenance Support. -Date format: YYYY-MM-DD +## Supported versions @@ -71,14 +85,21 @@ Date format: YYYY-MM-DD {% assign r_has_lts = false %} {% assign r_lts_eol = false %} {% assign will_never_have_lts = false %} + {% assign skippable = false %} {% comment %}v23.1 and future will have LTS {% endcomment %} {% if major_version_numeric < 23.1 %} {% assign will_never_have_lts = true %} {% endif %} + {% comment %}Releases with a release date and no assistance date are skippable{% endcomment %} + {% if v.release_date != "N/A" and v.maint_supp_exp_date != "N/A" and v.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + {% assign will_never_have_lts = true %} + {% endif %} + {% comment %}Evaluate whether the version is EOL for GA or LTS or both{% endcomment %} - {% if v.asst_supp_exp_date < today %} + {% if v.asst_supp_exp_date != "N/A" and v.asst_supp_exp_date < today and skippable == false %} {% comment %}GA releases in this version are EOL{% endcomment %} {% assign r_eol = true %} {% if v.lts_asst_supp_exp_date != "N/A" %} @@ -89,8 +110,25 @@ Date format: YYYY-MM-DD {% assign r_lts_eol = true %} {% endif %} {% endif %} + {% elsif v.asst_supp_exp_date == "N/A" and v.maint_supp_exp_date != "N/A" and v.maint_supp_exp_date < today and skippable == true %} + {% comment %}GA releases in this version are EOL{% endcomment %} + {% assign r_eol = true %} {% endif %} + {% comment %}Evaluate whether skippable versions are EOL{% endcomment %} + {% if v.asst_supp_exp_date == "N/A" and v.maint_supp_exp_date < today and skippable == true %} + {% comment %}GA releases in this version are EOL{% endcomment %} + {% assign r_eol = true %} + {% endif %} + + {% if DEBUG %} + v.major_version: {{ v.major_version }}
+ major_version_numeric: {{ major_version_numeric }}
+ skippable: {{ skippable }}
+ r_eol: {{ r_eol }}
+ r_lts_eol: {{ r_lts_eol }}
+
+ {% endif %} {% if r_eol != true and r_lts_eol != true %}{% comment %}Only show non-EOL releases {% endcomment %} @@ -105,8 +143,12 @@ Date format: YYYY-MM-DD {% endif %} - {% comment %} Always print a GA row. For 23.2+, add a link to the first footnote{% endcomment %} - + {% comment %} Always print a GA row. + For regular releases not yet in LTS, add a link to the first footnote + For currently supported skippable releases, add a link to the second footnote + {% endcomment %} + + @@ -120,10 +162,11 @@ Date format: YYYY-MM-DD
{{ v.major_version }}{% if will_never_have_lts == false and v.initial_lts_patch == "N/A" %} *{% endif %}
{{ v.major_version }}{% if will_never_have_lts == false and v.initial_lts_patch == "N/A" %} *{% elsif skippable == true %} **{% endif %} {% if v.last_ga_patch != "N/A" %}{{ v.major_version }}.0 - {{ v.last_ga_patch }}{% else %}{{ v.major_version }}.0+{% endif %} GA {{ v.release_date }}
*  : This major version will receive LTS patch releases, which will be listed on an additional row, upon their availability.
+**  : This major version is an optional innovation release and will not receive receive LTS patch releases. Innovation releases are EOL when Maintenance Support ends.
-## End-of-life (EOL) releases +## End-of-life (EOL) versions -The following releases are no longer supported. +The following versions of CockroachDB are no longer supported. @@ -140,22 +183,56 @@ The following releases are no longer supported. {% for v in versions %} {% assign r_latest = site.data.releases | where_exp: "r_latest", "r_latest.major_version == v.major_version" | where_exp: "r_latest", "r_latest.withdrawn != true" | sort: "release_date" | last | map: "version" %} {% comment %} Calculate the latest non-withdrawn release for a version v. {% endcomment %} - {% comment %}Evaluate whether the version is EOL for GA or LTS or both{% endcomment %} + {% comment %}Convert version (string) to numeric{% endcomment %} + {% assign major_version_numeric = v.major_version | remove_first: "v" | times:1 %} + + {% comment %}Initialize local variables {% endcomment %} {% assign r_eol = false %} + {% assign r_has_lts = false %} {% assign r_lts_eol = false %} - {% if v.lts_asst_supp_exp_date != "N/A" %} - {% comment %}This major version has LTS releases{% endcomment %} - {% assign r_has_lts = true %} - {% if v.lts_asst_supp_exp_date < today %} - {% comment %}LTS releases exist for this major version and are EOL{% endcomment %} - {% assign r_lts_eol = true %} + {% assign will_never_have_lts = false %} + {% assign skippable = false %} + + {% comment %}v23.1 and future will have LTS {% endcomment %} + {% if major_version_numeric < 23.1 %} + {% assign will_never_have_lts = true %} + {% endif %} + + {% comment %}Releases with a release date and no assistance date are skippable{% endcomment %} + {% if v.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + {% assign will_never_have_lts = true %} + {% endif %} + + {% comment %}Evaluate whether the version is EOL for GA or LTS or both{% endcomment %} + {% if v.asst_supp_exp_date != "N/A" and v.asst_supp_exp_date < today and skippable == false %} + {% comment %}GA releases in this version are EOL{% endcomment %} + {% assign r_eol = true %} + {% if v.lts_asst_supp_exp_date != "N/A" %} + {% comment %}This major version has LTS releases{% endcomment %} + {% assign r_has_lts = true %} + {% if v.lts_asst_supp_exp_date < today %} + {% comment %}LTS releases exist for this major version and are EOL{% endcomment %} + {% assign r_lts_eol = true %} + {% endif %} {% endif %} {% endif %} - {% if v.asst_supp_exp_date < today %} + + {% comment %}Evaluate whether skippable versions are EOL{% endcomment %} + {% if v.asst_supp_exp_date == "N/A" and v.maint_supp_exp_date < today and skippable == true %} {% comment %}GA releases in this version are EOL{% endcomment %} {% assign r_eol = true %} {% endif %} + {% if DEBUG %} + v.major_version: {{ v.major_version }}
+ major_version_numeric: {{ major_version_numeric }}
+ skippable: {{ skippable }}
+ r_eol: {{ r_eol }}
+ r_lts_eol: {{ r_lts_eol }}
+
+ {% endif %} + {% if r_eol == true %} {% if r_lts_eol == true %} {% comment %} For LTS releases print an LTS row first{% endcomment %} @@ -170,7 +247,7 @@ The following releases are no longer supported. {% comment %} Always print a GA row{% endcomment %} - + @@ -180,5 +257,8 @@ The following releases are no longer supported. {% endif %} {% endfor %} {% comment %} Display each EOL version, its release date, its maintenance support expiration date, and its assistance support expiration date, and its LTS maintenance and assistance support dates. Also include links to the latest hotfix version. {% endcomment %} +
{{ v.major_version }}{{ v.major_version }}{% if skippable == true %} *{% endif %} {% if v.last_ga_patch != "N/A" %}{{ v.major_version }}.0 - {{ v.last_ga_patch }}{% else %}{{ v.major_version }}.0+{% endif %} GA {{ v.release_date }}
+ +*  : This EOL major version is an optional innovation release. Innovation releases do not receive LTS releases and are EOL when Maintenance Support ends.
diff --git a/src/current/v24.2/cost-based-optimizer.md b/src/current/v24.2/cost-based-optimizer.md index 01040b63996..6467f86a6a9 100644 --- a/src/current/v24.2/cost-based-optimizer.md +++ b/src/current/v24.2/cost-based-optimizer.md @@ -314,7 +314,7 @@ The following modes can be set: - `force_custom_plan` (default): Force the use of custom plans. - `force_generic_plan`: Force the use of generic plans. -- `auto`: Automatically determine whether to use custom or generic query plans for prepared statements. Custom plans are used for the first five statement executions. Subsequent executions use a generic plan if its estimated cost is not significantly higher than the average cost of the preceding custom plans. +- `auto`: Automatically determine whether to use custom or generic query plans for prepared statements. Custom plans are used for the first five statement executions. Subsequent executions use a generic plan if its estimated cost is not significantly higher than the average cost of the preceding custom plans. {{site.data.alerts.callout_info}} Generic plans are always used for non-prepared statements that do not contain placeholders or [stable functions]({% link {{ page.version.version }}/functions-and-operators.md %}#function-volatility), regardless of the `plan_cache_mode` setting. diff --git a/src/current/v24.2/install-cockroachdb-linux.md b/src/current/v24.2/install-cockroachdb-linux.md index c7e067446b2..2dff4e3ad46 100644 --- a/src/current/v24.2/install-cockroachdb-linux.md +++ b/src/current/v24.2/install-cockroachdb-linux.md @@ -15,9 +15,9 @@ docs_area: deploy {% include cockroachcloud/use-cockroachcloud-instead.md %} -See [Release Notes](https://www.cockroachlabs.com/docs/releases/{{page.version.version}}) for what's new in the latest release, {{ page.release_info.version }}. To upgrade to this release from an older version, see [Cluster Upgrade](https://www.cockroachlabs.com/docs/releases/{{page.version.version}}/upgrade-cockroach-version). +{% include latest-release-details.md %} -Use one of the options below to install CockroachDB. +Use one of the options below to install CockroachDB. To upgrade an existing cluster, refer to [Upgrade to {{ page.version.version }}]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}). To install a FIPS-compliant CockroachDB binary, refer to [Install a FIPS-compliant build of CockroachDB]({% link {{ page.version.version }}/fips.md %}). diff --git a/src/current/v24.2/install-cockroachdb-mac.md b/src/current/v24.2/install-cockroachdb-mac.md index cb16bac1e86..dc2c8382577 100644 --- a/src/current/v24.2/install-cockroachdb-mac.md +++ b/src/current/v24.2/install-cockroachdb-mac.md @@ -15,12 +15,7 @@ docs_area: deploy {% include cockroachcloud/use-cockroachcloud-instead.md %} -See [Release Notes](https://www.cockroachlabs.com/docs/releases/{{page.version.version}}) for what's new in the latest release, {{ page.release_info.version }}. To upgrade to this release from an older version, see [Cluster Upgrade](https://www.cockroachlabs.com/docs/releases/{{page.version.version}}/upgrade-cockroach-version). - -{% comment %}v22.2.0+{% endcomment %} -{{site.data.alerts.callout_danger}} -

On macOS ARM systems, spatial features are disabled due to an issue with macOS code signing for the GEOS libraries. Users needing spatial features on an ARM Mac may instead use Rosetta to run the Intel binary or use the Docker image distribution. Refer to GitHub tracking issue for more information.

-{{site.data.alerts.end}} +{% include latest-release-details.md %} {% capture arch_note_homebrew %}

For CockroachDB v22.2.x and above, Homebrew installs binaries for your system architecture, either Intel or ARM (Apple Silicon).

For previous releases, Homebrew installs Intel binaries. Intel binaries can run on ARM systems, but with a significant reduction in performance. CockroachDB on ARM for macOS is experimental and is not yet qualified for production use and not eligible for support or uptime SLA commitments.

{% endcapture %} @@ -28,7 +23,11 @@ See [Release Notes](https://www.cockroachlabs.com/docs/releases/{{page.version.v {% capture arch_note_docker %}

For CockroachDB v22.2.beta-5 and above, Docker images are multi-platform images that contain binaries for both Intel and ARM (Apple Silicon). Multi-platform images do not take up additional space on your Docker host.

Docker images for previous releases contain Intel binaries only. Intel binaries can run on ARM systems, but with a significant reduction in performance.

CockroachDB on ARM for macOS is experimental and is not yet qualified for production use and not eligible for support or uptime SLA commitments.

{% endcapture %} -Use one of the options below to install CockroachDB. +{{site.data.alerts.callout_info}} +CockroachDB on macOS is experimental and not suitable for production deployments. +{{site.data.alerts.end}} + +Use one of the options below to install CockroachDB. To upgrade an existing cluster, refer to [Upgrade to {{ page.version.version }}]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}). For limitations specific to geospatial features, refer to [Limitations](#limitations).
@@ -87,7 +86,7 @@ true {% endcapture %}
-

Download the binary

+

Download the binary

{{ arch_note_binaries }}
  1. @@ -230,3 +229,9 @@ CockroachDB runtimes built for the ARM architecture have the following limitatio {% include {{ page.version.version }}/misc/install-next-steps.html %} {% include {{ page.version.version }}/misc/diagnostics-callout.html %} + +## Limitations + +{% comment %}v22.2.0+{% endcomment %} + +On macOS ARM systems, [spatial features]{% link {{ page.version.version }}/spatial-data-overview.md %}) are disabled due to an issue with macOS code signing for the GEOS libraries. Users needing spatial features on an ARM Mac may instead [run the Intel binary](#install-the-binary) or use the[Docker container image](#use-docker). Refer to [GitHub issue #93161](https://github.com/cockroachdb/cockroach/issues/93161) for more information. diff --git a/src/current/v24.2/install-cockroachdb-windows.md b/src/current/v24.2/install-cockroachdb-windows.md index 1ad740a2de7..9a9af4693bc 100644 --- a/src/current/v24.2/install-cockroachdb-windows.md +++ b/src/current/v24.2/install-cockroachdb-windows.md @@ -15,15 +15,15 @@ docs_area: deploy {% include cockroachcloud/use-cockroachcloud-instead.md %} -See [Release Notes](https://www.cockroachlabs.com/docs/releases/{{page.version.version}}) for what's new in the latest release, {{ page.release_info.version }}. To upgrade to this release from an older version, see [Cluster Upgrade](https://www.cockroachlabs.com/docs/releases/{{page.version.version}}/upgrade-cockroach-version). +{% include latest-release-details.md %} -Use one of the options below to install CockroachDB. +{% include windows_warning.md %} + +Use one of the options below to install CockroachDB. To upgrade an existing cluster, refer to [Upgrade to {{ page.version.version }}]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}).

    Download the executable

    - {% include windows_warning.md %} - 1. Using PowerShell, run the following script to download the [CockroachDB {{ page.release_info.version }} archive for Windows](https://binaries.cockroachdb.com/cockroach-{{ page.release_info.version }}.windows-6.2-amd64.zip) and copy the binary into your `PATH`: {% include_cached copy-clipboard.html %} diff --git a/src/current/v24.2/upgrade-cockroach-version.md b/src/current/v24.2/upgrade-cockroach-version.md index b327222239c..64c4ebb8322 100644 --- a/src/current/v24.2/upgrade-cockroach-version.md +++ b/src/current/v24.2/upgrade-cockroach-version.md @@ -6,6 +6,17 @@ docs_area: manage --- {% assign previous_version = site.data.versions | where_exp: "previous_version", "previous_version.major_version == page.version.version" | map: "previous_version" | first %} +{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.version.version" | first %} + +{% assign released = false %} +{% assign skippable = false %} +{% if rd.release_date != "N/A" and rd.maint_supp_exp_date != "N/A" %} + {% assign released = true %} + {% if rd.asst_supp_exp_date == "N/A" %} + {% assign skippable = true %} + {% endif %} +{% endif %} + {% assign earliest = site.data.releases | where_exp: "earliest", "earliest.major_version == page.version.version" | sort: "release_date" | first %} {% assign latest = site.data.releases | where_exp: "latest", "latest.major_version == page.version.version" | sort: "release_date" | last %} {% assign prior = site.data.releases | where_exp: "prior", "prior.major_version == page.version.version" | sort: "release_date" | pop | last %} @@ -17,33 +28,32 @@ docs_area: manage Because of CockroachDB's [multi-active availability]({% link {{ page.version.version }}/multi-active-availability.md %}) design, you can perform a "rolling upgrade" of your CockroachDB cluster. This means that you can upgrade nodes one at a time without interrupting the cluster's overall health and operations. -This page describes how to upgrade to the latest **{{ page.version.version }}** release, **{{ latest.release_name }}**{% if latest.lts == true %} ([LTS]({% link releases/release-support-policy.md %}#support-types)){% endif %}. To upgrade CockroachDB on Kubernetes, refer to [single-cluster]({% link {{ page.version.version }}/upgrade-cockroachdb-kubernetes.md %}) or [multi-cluster]({% link {{ page.version.version }}/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md %}#upgrade-the-cluster) instead. +This page describes how to upgrade to the latest **{{ page.version.version }}** release, **{{ latest.release_name }}**{% if latest.lts == true %} ([LTS]({% link releases/release-support-policy.md %}#support-types)){% endif %}. -## Terminology +{% include latest-release-details.md %} -Before upgrading, review the CockroachDB [release](../releases/) terminology: +To upgrade CockroachDB on Kubernetes, refer to [single-cluster]({% link {{ page.version.version }}/upgrade-cockroachdb-kubernetes.md %}) or [multi-cluster]({% link {{ page.version.version }}/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md %}#upgrade-the-cluster) instead. -- A new *major release* is performed multiple times per year. The major version number indicates the year of release followed by the release number, starting with 1. For example, the latest major release is {{ actual_latest_prod.major_version }}. -- Each [supported](https://www.cockroachlabs.com/docs/releases/release-support-policy) major release is maintained across *patch releases* that contain improvements including performance or security enhancements and bug fixes. Each patch release increments the major version number with its corresponding patch number. For example, patch releases of {{ actual_latest_prod.major_version }} use the format {{ actual_latest_prod.major_version }}.x. -- All major and patch releases are suitable for production environments, and are therefore considered "production releases". For example, the latest production release is {{ actual_latest_prod.release_name }}. -- Prior to an upcoming major release, alpha, beta, and release candidate (RC) binaries are made available for users who need early access to a feature before it is available in a production release. These releases append the terms `alpha`, `beta`, or `rc` to the version number. These "testing releases" are not suitable for production environments and are not eligible for support or uptime SLA commitments. For more information, refer to the [Release Support Policy](https://www.cockroachlabs.com/docs/releases/release-support-policy). +## Step 1. Verify that you can upgrade {{site.data.alerts.callout_info}} -There are no "minor releases" of CockroachDB. +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}} -## Step 1. Verify that you can upgrade +{% if skippable == true %} +CockroachDB {{ page.version.version }} is an optional [Innovation release]({% link releases/release-support-policy.md %}#innovation-releases). If you skip it, you must upgrade to the next [Regular release]({% link releases/release-support-policy.md %}#regular-releases) when it is available to maintain support. +{% else %} +CockroachDB {{ page.version.version }} is a required [Regular release]({% link releases/release-support-policy.md %}#regular-releases). +{% endif %}{% comment %}TODO before next Regular, add logic for multiple targets to upgrade from to get to a Regular release{% endcomment %} -{{site.data.alerts.callout_danger}} -In CockroachDB v22.2.x and above, a cluster that is upgraded to an alpha binary of CockroachDB or a binary that was manually built from the `master` branch cannot subsequently be upgraded to a production release. -{{site.data.alerts.end}} +To verify that you can upgrade: -Run [`cockroach sql`]({% link {{ page.version.version }}/cockroach-sql.md %}) against any node in the cluster to open the SQL shell. Then check your current cluster version: +1. Run [`cockroach sql`]({% link {{ page.version.version }}/cockroach-sql.md %}) against any node in the cluster to open the SQL shell. Then check your current cluster version: -{% include_cached copy-clipboard.html %} -~~~ sql -> SHOW CLUSTER SETTING version; -~~~ + {% include_cached copy-clipboard.html %} + ~~~ sql + > SHOW CLUSTER SETTING version; + ~~~ To upgrade to {{ latest.release_name }}, you must be running{% if prior.release_name %} either{% endif %}: @@ -56,7 +66,7 @@ If you are running any other version, take the following steps **before** contin | Version | Action(s) before upgrading to any {{ page.version.version }} release | |------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Pre-{{ page.version.version }} testing release | Upgrade to a corresponding production release; then upgrade through each subsequent major release, [ending with a {{ previous_version }} production release](https://www.cockroachlabs.com/docs/{{ previous_version }}/upgrade-cockroach-version). | +| Pre-{{ page.version.version }} testing release | Upgrade to a corresponding production release, then upgrade through each subsequent major release, [ending with a {{ previous_version }} production release](https://www.cockroachlabs.com/docs/{{ previous_version }}/upgrade-cockroach-version). | | Pre-{{ previous_version }} production release | Upgrade through each subsequent major release, [ending with a {{ previous_version }} production release](https://www.cockroachlabs.com/docs/{{ previous_version }}/upgrade-cockroach-version). | | {{ previous_version}} testing release | [Upgrade to a {{ previous_version }} production release](https://www.cockroachlabs.com/docs/{{ previous_version }}/upgrade-cockroach-version). | @@ -68,7 +78,7 @@ 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](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 %}), [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 %}), and [key cluster setting changes](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-cluster-settings{% endunless %}) in {{ page.version.version }}. If any affect your deployment, make the necessary changes before starting the rolling upgrade to {{ page.version.version }}. @@ -136,11 +146,13 @@ By default, after all nodes are running the new version, the upgrade process wil ### Features that require upgrade finalization -When upgrading from {{ previous_version }} to {{ page.version.version }}, certain features and performance improvements will be enabled only after finalizing the upgrade, including but not limited to: +When upgrading from one major version to another, certain features and performance improvements will be enabled only after finalizing the upgrade. However, when upgrading from {{ previous_version }} to {{ page.version.version }}, all features are available immediately, and no features require finalization. -- {% include v24.1/finalization-required/119894.md version="v24.1" %} +{{site.data.alerts.callout_info}} +Finalization is always required to complete an upgrade. +{{site.data.alerts.end}} -For more details about a given feature, refer to the [CockroachDB v24.1.0 release notes](https://www.cockroachlabs.com/docs/releases/v24.1#v24-1-0). +For more details about a given feature, refer to the [CockroachDB v24.2.0 release notes](https://www.cockroachlabs.com/docs/releases/v24.2#v24-2-0). ## Step 4. Perform the rolling upgrade