From 1e150fa9848bb8214ce43827ed016d2773726966 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 3 Apr 2026 11:35:09 -0400 Subject: [PATCH 1/4] Initial draft --- .../images/couchbase_version_numbers.drawio | 49 +++++++ .../images/couchbase_version_numbers.svg | 4 + modules/install/pages/upgrade.adoc | 127 ++++++++++++++++-- 3 files changed, 170 insertions(+), 10 deletions(-) create mode 100644 modules/install/assets/images/couchbase_version_numbers.drawio create mode 100644 modules/install/assets/images/couchbase_version_numbers.svg diff --git a/modules/install/assets/images/couchbase_version_numbers.drawio b/modules/install/assets/images/couchbase_version_numbers.drawio new file mode 100644 index 0000000000..826d7f42a2 --- /dev/null +++ b/modules/install/assets/images/couchbase_version_numbers.drawio @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/install/assets/images/couchbase_version_numbers.svg b/modules/install/assets/images/couchbase_version_numbers.svg new file mode 100644 index 0000000000..12cfe166ab --- /dev/null +++ b/modules/install/assets/images/couchbase_version_numbers.svg @@ -0,0 +1,4 @@ + + + +
.
018
Major version
.
Minor version
Maintenance or patch version
 \ No newline at end of file diff --git a/modules/install/pages/upgrade.adoc b/modules/install/pages/upgrade.adoc index e1d6d5b109..f866fd7434 100644 --- a/modules/install/pages/upgrade.adoc +++ b/modules/install/pages/upgrade.adoc @@ -105,6 +105,24 @@ To upgrade a cluster, you must individually upgrade each node in turn. You must select the upgrade procedure for the cluster depending on whether the cluster needs to continue or cease serving data during the cluster-upgrade. A review of the factors that determine the appropriateness of an upgrade-procedure is provided in xref:install:upgrade-procedure-selection.adoc[Upgrade Procedure-Selection]. + +[#version-numbers] +== Couchbase Server Version Numbers + +When upgrading, you need to consider the version numbers of the server that you're upgrading from and to. +Not all versions of Couchbase Server can be directly upgraded to all later versions. +Also, the version numbers indicate under what conditions you can downgrade a version upgrade should you encounter problems. +See <> for more information about downgrading an upgrade. + +Couchbase Server uses a 3-number version scheme: + +image::couchbase_version_numbers.svg[alt="Couchbase Server 3-digit number scheme example: 8.0.1"] + +* The first number is the major version number. +* The second number is the minor version number. +* The third number is the maintenance or patch version number. +The terms patch version and maintenance version are interchangeable. + [#supported-upgrade-paths] == Upgrade Paths @@ -112,8 +130,6 @@ An upgrade path declares that Couchbase Server supports upgrading from one versi The tables in the following subsections list upgrade paths for Enterprise Edition and for Couchbase Server Community Edition, respectively. Each instance of the{nbsp}`->`{nbsp}sign declares support for the upgrade of the server-version on the left of the sign to the server-version on the right. - - You can perform all supported upgrades with the cluster either offline or online. TIP: As far as is possible, you should aim to keep your cluster up to date with the latest version of Couchbase Server. @@ -222,9 +238,9 @@ Delta Recovery is not supported since the new nodes must be fresh Enterprise Edi NOTE: Rolling upgrades from CE to EE are not supported if there are index service nodes running in the cluster. The Enterprise Edition nodes must be running the same version number of Couchbase Server as the Community Edition nodes that they're replacing, otherwise the upgrade may fail. -This means you can not upgrade to a newer version of Couchbase Server while also upgrading to Enterprise Edition during the same rolling upgrade. +This means you can not upgrade to a later version of Couchbase Server while also upgrading to Enterprise Edition during the same rolling upgrade. -If you want to upgrade from an older version of `Community Edition` to a later version of `Enterprise Edition`, you need to perform 2 separate upgrade procedures: +If you want to upgrade from an earlier version of `Community Edition` to a later version of `Enterprise Edition`, you need to perform 2 separate upgrade procedures: . Upgrade the entire cluster to Enterprise Edition via a rolling online upgrade . Upgrade to the desired version number of Couchbase Server using any supported type of upgrade @@ -264,11 +280,102 @@ For information, see xref:learn:security/certificates.adoc#node-certificate-vali [#downgrade] == Downgrade -Once an upgrade of a Couchbase-Server cluster has started, -you can downgrade to an earlier version of Couchbase Server by using the `swap/rebalance` method: +If you have issues with an upgrade, you may want to downgrade to the earlier version of Couchbase Server. +Your ability to downgrade depends on the whether the upgrade was between and major or minor version numbers or a maintenance version. +See <> for an explanation of Couchbase Server's version numbering scheme. + +[#downgrade_major_minor] +=== Downgrading an Upgrade Between Major or Minor Versions + +When you're upgrading between major or minor versions of Couchbase Server, you can downgrade at any time before you finalize your upgrade. + +Examples of a major or minor version upgrade include: + +* Upgrading from version 6.6 to version 7.2.3 +* Upgrading from version 7.2.3 to version 7.6.10. + +Finalizing an upgrade means that all nodes in the cluster are running the new version of Couchbase Server. +When you upgrade Couchbase Server on the last node running the prior version, +Couchbase Server updates all metadata, objects, and structures to any new formats to enable new features. +As long as the cluster is running in mixed mode (at least 1 node running a different version), it cannot make these changes. + +Use the online downgrade method of downgrading If you choose to downgrade before finalizing an major or minor version upgrade. +See <> to learn how to perform an online downgrade. + +After you finalize an upgrade between major or minor versions, the new features in the new version become available for use. +As long as the cluster is running in mixed mode, you cannot use the new features in the new version. + +After you finalize your upgrade, you cannot roll back your upgrade because +Couchbase Server cannot roll back the metadata, objects, and structures to their prior formats. +If your applications have issues with the new version, you can only revert to the earlier version by creating a new cluster running the earlier version and migrating your data to it. +For this reason, it's vital to test the new version of Couchbase Server with your applications before you finalize your upgrade. + +NOTE: If you do need to roll back a finalized upgrade and you have a disaster recovery cluster synced via XDCR, consider switching to it. +Then you can create a new cluster running the prior version and use it as the disaster recovery cluster or switch back to it after it has synched data. + +[#prevent-finalization] +=== Preventing Finalization + +You may want to verify that your entire cluster performs well using the new version of Couchbase Server before you finalize your upgrade. +You can prevent finalization by adding a small arbiter node to the cluster that runs the earlier version of Couchbase Server. +The presence of this node prevents Couchbase Server from finalizing the upgrade because the cluster is running in mixed mode. + +An arbiter node does not host any services including the data service, so you can allocate minimal resources to it. +Couchbase Server 7.6 introduced arbiter nodes. +Therefore, you can only use this method if you're upgrading from 7.6.0 or later. +See xref:learn:clusters-and-availability/nodes.adoc#adding-arbiter-nodes[] for more about arbiter nodes. + +To add an arbiter node, follow the steps in xref:manage:manage-nodes/join-cluster-and-rebalance.adoc[] and deselect all services when you add the node to the cluster. + +The arbiter node prevents the cluster from finalizing the upgrade because it's running a previous version of Couchbase Server. +While the arbiter node is in place, you can upgrade your regular nodes to the new version of Couchbase Server. +Then you can verify your application's stability and performance. +However, the arbiter node also prevents you from using any of the new features in the new version of Couchbase Server. + +Once you have verified that the new version of Couchbase Server works well for your applications, remove the arbiter node to finalize the upgrade. + +If you find that the new version of Couchbase Server does not work well for your applications, keep the arbiter node in place. +Then downgrade the other nodes to the earlier version of Couchbase Server. +Once you have finished updating the nodes, remove the arbiter node to complete the downgrade. +See <> for the steps to take to perform the downgrade. + +[#downgrade-maintenance] +=== Downgrading an Upgrade Between Maintenance or Patch Versions + +If you're upgrading between maintenance versions of Couchbase Server, you can downgrade at any time, even after you finalize the upgrade. +A maintenance or patch version upgrade is an upgrade between versions that have the same major and minor version numbers but different maintenance or patch version numbers. +For example, an upgrade from version 8.0.0 to version 8.0.1 is a maintenance version upgrade. + +The only concern is if you enabled any new features by enabling Developer Preview Mode. +See xref:developer-preview:preview-mode.adoc[] for more information about Developer Preview Mode and the features it enables. +If you have enabled Developer Preview Mode, contact Couchbase Customer Support for assistance before attempting to downgrade your cluster. + +You downgrade a maintenance version upgrade by performing an online downgrade. +See <> for more the steps to take. + +[#online-downgrade] +=== Perform an Online Downgrade + +You can perform an online downgrade when: + +* You're downgrading an upgrade between maintenance or patch versions of Couchbase Server. +See <> for more information. +* You're downgrading an upgrade between major or minor versions of Couchbase Server and you have not finalized the upgrade. +See <> for more information. + +The online downgrade method is similar to an xref:install:upgrade-cluster-online.adoc#online-upgrade-at-reduced-and-full-capacity[online upgrade] procedure. +You perform a swap rebalance procedure where you remove a node, downgrade it, and then add it back to the cluster before rebalancing: -. Remove the target node from the cluster, then perform a rebalance on the cluster. -. Downgrade the target node (or create a new node using the earlier version of Couchbase). -. Add the node to the cluster and rebalance. +. Remove a node from the cluster. +. Perform a rebalance to complete the removal. +. On the node you removed, install the earlier version of Couchbase Server. +. Add the node back to the cluster. +. Perform a rebalance to complete the addition. +. Repeat steps 1-5 for each node in the cluster until all nodes are running the earlier version of Couchbase Server. +. If you added an arbiter node to prevent finalization, remove the arbiter node and perform a rebalance to finalize the downgrade. +See <> for more information about using an arbiter node to prevent finalization. -Once all nodes are running the later version, you can no longer downgrade and you must create an entirely new cluster running the earlier version if application-support needs it. +NOTE: You cannot use an offline downgrade to roll back an upgrade. +An offline downgrade is similar to an offline upgrade, except that you install an earlier version of Couchbase Server instead of a later version. +See xref:install:upgrade-procedure-selection.adoc#offline-upgrade[Upgrade with Cluster Offline] for more information about online upgrades. +You also cannot use a graceful failover followed by a full recovery to perform a downgrade. From 190f89ef141ae8eb855739d3e0c66f0e09f266e9 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 6 Apr 2026 11:39:42 -0400 Subject: [PATCH 2/4] General edits/cleanup. --- modules/install/pages/upgrade.adoc | 59 ++++++++++++++++++------------ 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/modules/install/pages/upgrade.adoc b/modules/install/pages/upgrade.adoc index f866fd7434..30e75a48d5 100644 --- a/modules/install/pages/upgrade.adoc +++ b/modules/install/pages/upgrade.adoc @@ -287,50 +287,57 @@ See <> for an explanation of Couchbase Server's version numberi [#downgrade_major_minor] === Downgrading an Upgrade Between Major or Minor Versions -When you're upgrading between major or minor versions of Couchbase Server, you can downgrade at any time before you finalize your upgrade. - +A major or minor version upgrade is an upgrade between versions that have different first or second digit in their version numbers. Examples of a major or minor version upgrade include: * Upgrading from version 6.6 to version 7.2.3 * Upgrading from version 7.2.3 to version 7.6.10. +See <> for more information about version numbers. + +When you're upgrading between major or minor versions of Couchbase Server, you can downgrade at any time before you finalize your upgrade. Finalizing an upgrade means that all nodes in the cluster are running the new version of Couchbase Server. -When you upgrade Couchbase Server on the last node running the prior version, -Couchbase Server updates all metadata, objects, and structures to any new formats to enable new features. + +When you upgrade the last node in the cluster running the prior version, +Couchbase Server updates metadata, objects, and structures to enable new features. As long as the cluster is running in mixed mode (at least 1 node running a different version), it cannot make these changes. -Use the online downgrade method of downgrading If you choose to downgrade before finalizing an major or minor version upgrade. +Use the online downgrade process to downgrade a major or minor upgrade before you have finalized it. See <> to learn how to perform an online downgrade. -After you finalize an upgrade between major or minor versions, the new features in the new version become available for use. -As long as the cluster is running in mixed mode, you cannot use the new features in the new version. +Once you finalize your upgrade, you cannot roll back your upgrade because +Couchbase Server cannot roll back the metadata, objects, and structures to their earlier formats. +If your applications have issues with the new version, you can only revert to the earlier version by: -After you finalize your upgrade, you cannot roll back your upgrade because -Couchbase Server cannot roll back the metadata, objects, and structures to their prior formats. -If your applications have issues with the new version, you can only revert to the earlier version by creating a new cluster running the earlier version and migrating your data to it. -For this reason, it's vital to test the new version of Couchbase Server with your applications before you finalize your upgrade. +. Creating a new cluster. +. Install the earlier version of Couchbase Server. +. Migrate your data to the new cluster. + +Because finalization increases the difficulty in rolling back an upgrade, it's vital to test the new version with your applications before you finalize it. +See the next section for tips on preventing finalization until you're ready to finalize your upgrade. NOTE: If you do need to roll back a finalized upgrade and you have a disaster recovery cluster synced via XDCR, consider switching to it. -Then you can create a new cluster running the prior version and use it as the disaster recovery cluster or switch back to it after it has synched data. +Then you can create a new cluster running the prior version and either use it as the disaster recovery cluster or switch back to it after it has synched all data. [#prevent-finalization] === Preventing Finalization -You may want to verify that your entire cluster performs well using the new version of Couchbase Server before you finalize your upgrade. -You can prevent finalization by adding a small arbiter node to the cluster that runs the earlier version of Couchbase Server. +You should verify that your applications perform well using the new version of Couchbase Server before you finalize your upgrade. +Fully testing your applications may require you to upgrade all nodes in the cluster. +However, Couchbase Server finalizes your installation when you upgrade the last node to the new version of Couchbase Server. + +To upgrade all your nodes while preventing finalization, add a small arbiter node to the cluster running the earlier version of Couchbase Server before completing your upgrade. The presence of this node prevents Couchbase Server from finalizing the upgrade because the cluster is running in mixed mode. +You upgrade all other nodes in the cluster and test your applications with the new version of Couchbase Server while the arbiter node is in place. + +NOTE: The arbiter node also prevents you from using any of the new features in the new version of Couchbase Server. -An arbiter node does not host any services including the data service, so you can allocate minimal resources to it. +An arbiter node does not host any services, including the data service, so you can allocate minimal resources to it. Couchbase Server 7.6 introduced arbiter nodes. Therefore, you can only use this method if you're upgrading from 7.6.0 or later. See xref:learn:clusters-and-availability/nodes.adoc#adding-arbiter-nodes[] for more about arbiter nodes. -To add an arbiter node, follow the steps in xref:manage:manage-nodes/join-cluster-and-rebalance.adoc[] and deselect all services when you add the node to the cluster. - -The arbiter node prevents the cluster from finalizing the upgrade because it's running a previous version of Couchbase Server. -While the arbiter node is in place, you can upgrade your regular nodes to the new version of Couchbase Server. -Then you can verify your application's stability and performance. -However, the arbiter node also prevents you from using any of the new features in the new version of Couchbase Server. +To add an arbiter node, follow the steps in xref:manage:manage-nodes/join-cluster-and-rebalance.adoc[] and deselect all services before adding the node to the cluster. Once you have verified that the new version of Couchbase Server works well for your applications, remove the arbiter node to finalize the upgrade. @@ -345,8 +352,9 @@ See <> for the steps to take to perform the downgrade. If you're upgrading between maintenance versions of Couchbase Server, you can downgrade at any time, even after you finalize the upgrade. A maintenance or patch version upgrade is an upgrade between versions that have the same major and minor version numbers but different maintenance or patch version numbers. For example, an upgrade from version 8.0.0 to version 8.0.1 is a maintenance version upgrade. +You can downgrade a finalized maintenance version upgrade because they do not make changes to metadata, objects, and structures that would prevent downgrading. -The only concern is if you enabled any new features by enabling Developer Preview Mode. +The only concern about a maintenance version downgrade is if you enabled any new features using Developer Preview Mode. See xref:developer-preview:preview-mode.adoc[] for more information about Developer Preview Mode and the features it enables. If you have enabled Developer Preview Mode, contact Couchbase Customer Support for assistance before attempting to downgrade your cluster. @@ -363,8 +371,11 @@ See <> for more information. * You're downgrading an upgrade between major or minor versions of Couchbase Server and you have not finalized the upgrade. See <> for more information. -The online downgrade method is similar to an xref:install:upgrade-cluster-online.adoc#online-upgrade-at-reduced-and-full-capacity[online upgrade] procedure. -You perform a swap rebalance procedure where you remove a node, downgrade it, and then add it back to the cluster before rebalancing: +The online downgrade method is similar to an xref:install:upgrade-cluster-online.adoc#online-upgrade-at-reduced-and-full-capacity[online upgrade] procedure. +You perform the same swap rebalance procedure where you remove a node, install Couchbase Server, and then add it back to the cluster before rebalancing. +The difference is that instead of installing a later version of Couchbase Server on the node, you install an earlier version of Couchbase Server. + +To perform an online downgrade: . Remove a node from the cluster. . Perform a rebalance to complete the removal. From 2dfa818440d7bbe01ce2e0bbaac4db96a0a67b04 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 13 Apr 2026 11:17:28 -0400 Subject: [PATCH 3/4] Some minor fixes --- modules/install/pages/upgrade.adoc | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/modules/install/pages/upgrade.adoc b/modules/install/pages/upgrade.adoc index 30e75a48d5..4f438827ea 100644 --- a/modules/install/pages/upgrade.adoc +++ b/modules/install/pages/upgrade.adoc @@ -298,20 +298,19 @@ See <> for more information about version numbers. When you're upgrading between major or minor versions of Couchbase Server, you can downgrade at any time before you finalize your upgrade. Finalizing an upgrade means that all nodes in the cluster are running the new version of Couchbase Server. -When you upgrade the last node in the cluster running the prior version, -Couchbase Server updates metadata, objects, and structures to enable new features. +When you finalize an upgrade, Couchbase Server updates metadata, objects, and structures to enable new features. As long as the cluster is running in mixed mode (at least 1 node running a different version), it cannot make these changes. Use the online downgrade process to downgrade a major or minor upgrade before you have finalized it. See <> to learn how to perform an online downgrade. -Once you finalize your upgrade, you cannot roll back your upgrade because +Once you finalize your upgrade, you cannot roll back your upgrade. Couchbase Server cannot roll back the metadata, objects, and structures to their earlier formats. -If your applications have issues with the new version, you can only revert to the earlier version by: +If your applications have issues with the new version after finalization, you can only revert to the earlier version by: . Creating a new cluster. -. Install the earlier version of Couchbase Server. -. Migrate your data to the new cluster. +. Installing the earlier version of Couchbase Server. +. Migrating your data to the new cluster. Because finalization increases the difficulty in rolling back an upgrade, it's vital to test the new version with your applications before you finalize it. See the next section for tips on preventing finalization until you're ready to finalize your upgrade. @@ -326,16 +325,17 @@ You should verify that your applications perform well using the new version of C Fully testing your applications may require you to upgrade all nodes in the cluster. However, Couchbase Server finalizes your installation when you upgrade the last node to the new version of Couchbase Server. -To upgrade all your nodes while preventing finalization, add a small arbiter node to the cluster running the earlier version of Couchbase Server before completing your upgrade. -The presence of this node prevents Couchbase Server from finalizing the upgrade because the cluster is running in mixed mode. -You upgrade all other nodes in the cluster and test your applications with the new version of Couchbase Server while the arbiter node is in place. - -NOTE: The arbiter node also prevents you from using any of the new features in the new version of Couchbase Server. - +A workaround is to add a small arbiter node running the earlier version of Couchbase Server to your cluster before completing your upgrade. An arbiter node does not host any services, including the data service, so you can allocate minimal resources to it. -Couchbase Server 7.6 introduced arbiter nodes. + +NOTE: Couchbase Server introduced arbiter nodes in version 7.6. Therefore, you can only use this method if you're upgrading from 7.6.0 or later. -See xref:learn:clusters-and-availability/nodes.adoc#adding-arbiter-nodes[] for more about arbiter nodes. +See xref:learn:clusters-and-availability/nodes.adoc#adding-arbiter-nodes[Adding Arbiter Nodes] for more about arbiter nodes. + +The presence of the arbiter node prevents Couchbase Server from finalizing the upgrade because the cluster is running in mixed mode. +You can upgrade all other nodes in the cluster to test your applications with the new version of Couchbase Server. + +The arbiter node also prevents you from using any of the new features in the new version of Couchbase Server. To add an arbiter node, follow the steps in xref:manage:manage-nodes/join-cluster-and-rebalance.adoc[] and deselect all services before adding the node to the cluster. From 166f031ed2eeac15c69dff73036c402a68dc3793 Mon Sep 17 00:00:00 2001 From: Gary Gray Date: Wed, 15 Apr 2026 10:12:12 -0400 Subject: [PATCH 4/4] Added links to the Online Downgrade procedure steps. --- modules/install/pages/upgrade.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/install/pages/upgrade.adoc b/modules/install/pages/upgrade.adoc index 4f438827ea..cc2085a18b 100644 --- a/modules/install/pages/upgrade.adoc +++ b/modules/install/pages/upgrade.adoc @@ -312,7 +312,7 @@ If your applications have issues with the new version after finalization, you ca . Installing the earlier version of Couchbase Server. . Migrating your data to the new cluster. -Because finalization increases the difficulty in rolling back an upgrade, it's vital to test the new version with your applications before you finalize it. +Because finalization increas__es the difficulty in rolling back an upgrade, it's vital to test the new version with your applications before you finalize it. See the next section for tips on preventing finalization until you're ready to finalize your upgrade. NOTE: If you do need to roll back a finalized upgrade and you have a disaster recovery cluster synced via XDCR, consider switching to it. @@ -377,13 +377,13 @@ The difference is that instead of installing a later version of Couchbase Server To perform an online downgrade: -. Remove a node from the cluster. +. xref:manage:manage-nodes/remove-node-and-rebalance.adoc[Remove a node from the cluster]. . Perform a rebalance to complete the removal. . On the node you removed, install the earlier version of Couchbase Server. -. Add the node back to the cluster. +. xref:manage:manage-nodes/add-node-and-rebalance.adoc[Add the node back to the cluster]. . Perform a rebalance to complete the addition. . Repeat steps 1-5 for each node in the cluster until all nodes are running the earlier version of Couchbase Server. -. If you added an arbiter node to prevent finalization, remove the arbiter node and perform a rebalance to finalize the downgrade. +. If you added an arbiter node to prevent finalization, remove the arbiter node and perform a rebalance to complete the downgrade. See <> for more information about using an arbiter node to prevent finalization. NOTE: You cannot use an offline downgrade to roll back an upgrade.