Skip to content

DOC-13847 Update upgrade paths to match Erlang support #4075

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
supritha-kumar wants to merge 2 commits into
base: prerelease/8.0.1
Choose a base branch
from
Open

DOC-13847 Update upgrade paths to match Erlang support #4075

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a0b9ab
DOC-13847 Update upgrade paths to match Erlang support
supritha-kumar Jan 22, 2026
9eb61ad
pdated for bug DOC-13847
supritha-kumar Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 40 additions & 45 deletions modules/install/pages/upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,16 +27,16 @@ Before upgrading, consider the following version compatibility concerns.
[#8-0-storage-backend]
=== New Default Storage Backend in Couchbase Server Version 8.0

After you have fully upgraded a cluster to Couchbase Server 8.0.x and later, the default storage backend for buckets is Magma with 128 vBuckets.
After you fully upgrade to Couchbase Server 8.0.x or later, the default storage backend for buckets is Magma with 128 vBuckets.
Previous versions of Couchbase Server used Couchstore with 1024 vBuckets as the default storage backend.

This new default results in two behavior changes from previous versions:
This new default results in 2 behavior changes from previous versions:

* If you create a bucket and do not specify the storage backend, your bucket will use the Magma storage backend instead of the Couchstore backend.
* If you specify Magma as the storage backend but do not set the new `numVBuckets` parameter, the bucket will have 128 vBuckets instead of the prior default of 1024 vBuckets.
* If you create a bucket and do not specify the storage backend, your bucket uses the Magma storage backend instead of the Couchstore backend.
* If you specify Magma as the storage backend but do not set the new `numVBuckets` parameter, the bucket has 128 vBuckets instead of the prior default of 1024 vBuckets.
Magma buckets with 128 vBuckets is a new feature in Couchbase Server 8.0 and later.

These behavior changes could cause issues if you rely on the prior behavior, especially if you use deployment scripts.
These behavior changes could cause issues if you rely on the prior behavior and you use deployment scripts.
If you have deployment scripts that create buckets, review them to determine if you need to make changes.

For example, suppose your deployment script does not specify the storage backend when it creates a bucket that you intend to use with the xref:learn:views/views-intro.adoc[views] feature.
Expand Down Expand Up @@ -96,25 +96,25 @@ Then upgrade to version 7.6 or later.
[#understanding-upgrade]
== Understanding Upgrade

To _upgrade_ a Couchbase-Server cluster means to upgrade the version of the server that's running on every node.
To `upgrade` a Couchbase-Server cluster means to upgrade the version of the server that's running on every node.
For example, modifying a cluster where all of its nodes are running Couchbase Server Enterprise Edition Version 6.6,
so that each of its nodes subsequently runs Couchbase Server Enterprise Edition Version 7.6.x.

An _upgrade procedure_, like an _install_ procedure, involves both preparation routines and specific upgrade commands that are performed on each node.
To be upgraded, a cluster must have each of its nodes individually upgraded in turn.
The upgrade procedure for the cluster must be selected in regard to whether the cluster is required to continue serving data, or to cease serving data, during the cluster-upgrade.
An `upgrade procedure` involves both preparation routines and specific upgrade commands that you perform on each node.
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].

[#supported-upgrade-paths]
== Upgrade Paths

An upgrade _path_ declares that the upgrade of one Couchbase Server version to another is _supported_.
The tables in the following subsections list upgrade paths for Enterprise Edition and for Community Edition, respectively.
An upgrade path declares that Couchbase Server supports upgrading from one version to another.
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.



All supported upgrades can be performed with the cluster either _offline_ or _online_.
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.

Expand All @@ -123,19 +123,20 @@ TIP: As far as is possible, you should aim to keep your cluster up to date with

[cols="2,6"]
|===
| Starting Version | Path to Current Version
| Starting Version | Path to Current Version

| 5.x

| Any 5.0.x / 5.1.x / 5.5.x → 6.6 → 7.2.3 → 8.0
| Any 5.0.x / 5.1.x / 5.5.x → 6.6 → 7.2.3 → latest 7.2.x → 8.0.1

| 6.x
| Any 6.0.x / 6.5.x → 6.6 → 7.2.3 → 8.0
| Any 6.0.x / 6.5.x → 6.6 → 7.2.3 → latest 7.2.x → 8.0.1

| 7.x
| Any 7.0.x / 7.1.x → 7.2.3 → 8.0{empty}xref:##erlang-8-0-footnote1[^+[1]+^]
| Any 7.0.x / 7.1.x → 7.2.3 → latest 7.2.x → 8.0.1

Any 7.2.x / 7.6.x → 8.0
Any 7.2.x → latest 7.2.x → 8.0.1
Any 7.6.x → latest 7.6.x → 8.0.1

|===

Expand Down Expand Up @@ -164,24 +165,21 @@ Any 7.2.x / 7.6.x → 8.0

[#erlang-8-0-footnote1]^1^{erlang-upgrade-note}

.Important note when upgrading from 7.0.4 to 7.2.x on Windows 2019
.Important note when upgrading from 7.0.4 to 7.2.x on Windows 2019
[sidebar]
****
Upgrading from version 7.0.4 -> 7.2x on Windows Server 2019 may result in a missing `java` executable files.

Note: Upgrading from version 7.0.4 -> 7.2x on Windows Server 2019 may result in a missing `java` executable files.
The problem is caused by the way Windows handles upgrades when dealing with older files, resulting in files being removed from the Couchbase installation without being replaced.

The server can be fixed by invoking the Windows Repair operation on the Couchbase installation.
This will restore the missing files.

You can fix the server by invoking the Windows Repair operation on the Couchbase installation.
This restores the missing files.
****


== How to Upgrade Your Cluster

If you are upgrading several nodes at once, then the version of the software on each node must be kept in step throughout the upgrade process. +
For example, if you are upgrading three enterprise nodes (`*Node{nbsp}1*`, `*Node{nbsp}2*` and `*Node{nbsp}3*`) from version 6.6.x to 8.0.x, then you would use the following sequence:
For example, if you upgrade 3 enterprise nodes (`*Node{nbsp}1*`, `*Node{nbsp}2*` and `*Node{nbsp}3*`) from version 5.1x to 7.6.x, then you would use the following sequence:

[#upgrade-example]
.Upgrading from version 6.6.x to 8.0.x
Expand Down Expand Up @@ -210,13 +208,13 @@ For example, if you are upgrading three enterprise nodes (`*Node{nbsp}1*`, `*Nod

====

.Upgrading between non-adjacent version numbers is usually _not_ supported.
.Upgrading between non-adjacent version numbers is not supported.
[NOTE]
====
For example, to upgrade from *6.6.x* to *8.0.x*, then 2 upgrades must be performed (as shown in <<upgrade-example>>):

. First, from *6.6.x* to *7.2.3*.
. Then, from *7.2.3* to *8.0.x*.
For example, to upgrade from *5.1.x* to *7.2.4*, then 3 upgrades must be performed (as shown in <<upgrade-example>>): +
first, from **5.1.x** to** 6.6**, +
then, from *6.6* to *7.2.3* +
and from *7.2.3* to *7.6.x*.
====


Expand All @@ -231,10 +229,10 @@ 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 are replacing, otherwise the upgrade may fail.
This means you can't upgrade to a newer version of Couchbase Server while also upgrading to Enterprise Edition during the same rolling upgrade.
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.

If you want to upgrade from an older version of _Community Edition_ to a newer version of _Enterprise Edition_, you need to perform two separate upgrade procedures:
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:

. 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
Expand All @@ -247,13 +245,13 @@ include::partial$diagrams.adoc[tag="upgrade-diagram"]
.Additional Notes about Upgrading from Community to Enterprise
[sidebar]
****
* Couchbase Server clusters _must_ be run either entirely on Enterprise Edition nodes or entirely on Community Edition nodes. +
Once you've upgraded one node to Enterprise Edition, you must upgrade all the other nodes before the cluster is considered as being in a steady, supportable state.
* Couchbase Server clusters must be run either entirely on Enterprise Edition nodes or entirely on Community Edition nodes. +
Once you have upgraded 1 node to Enterprise Edition, you must upgrade all the other nodes before the cluster is considered as being in a steady, supportable state.
* CE does not support index service rebalancing.
So, when the cluster is running with one or more CE nodes, then the indexes hosted on nodes being removed may be lost. +
When the cluster is running with 1 or more CE nodes, then the indexes hosted on nodes being removed may be lost. +
Users can create equivalent indexes (the same index with a different name) on different nodes
to avoid loss of index functionality.
* If a rolling online upgrade to Enterprise Edition isn't possible in your environment, contact Couchbase for assistance.
* If a rolling online upgrade to Enterprise Edition is not possible in your environment, contact Couchbase for assistance.
****

[IMPORTANT]
Expand All @@ -265,27 +263,24 @@ If you're interested in upgrading to Couchbase Server Enterprise Edition, check

See xref:install:upgrade-procedure-selection.adoc[Upgrade Procedure-Selection] for a list of procedures
that can be used when upgrading from Community Edition to Enterprise.
Note, however, that _Graceful Failover_ for Data Service nodes, with _Delta Recovery_,
is _not_ supported for such upgrades: instead, _removal_, _addition_, and _swap rebalance_ should be used; for all nodes.
Note, however, that `Graceful Failover` for Data Service nodes, with `Delta Recovery`,
is not supported for such upgrades: instead, `removal`, `addition`, and `swap rebalance` should be used for all nodes.

[#node-naming-and-upgrade]
== Node-Naming and Upgrade

In Couchbase Enterprise Server Version 7.2 or later, the node-name _must_ be correctly identified in the node-certificate as a Subject Alternative Name.
If the node-name is _not_ correctly identified, failure may occur during upgrade.
In Couchbase Enterprise Server Version 7.2 or later, the node-name must be identified in the node-certificate as a Subject Alternative Name.
If the node-name is not correctly identified, failure may occur during upgrade.
For information, see xref:learn:security/certificates.adoc#node-certificate-validation[Node-Certificate Validation].

[#downgrade]
== Downgrade

Once an upgrade of a Couchbase-Server cluster has started,
_downgrading_ to an earlier version of Couchbase Server can be performed by using the _swap/rebalance_ method:
you can downgrade to an earlier version of Couchbase Server by using the `swap/rebalance` method:

. 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.

Bear in mind that once all nodes are running the later version, downgrade can no longer be performed: therefore,
once all nodes are running the later version,
should application-support require the earlier version, an entirely new cluster must be created,
running the earlier version.
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.