Skip to content

DOC-14003 downgrade doc updates #4103

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
ggray-cb wants to merge 4 commits into
base: release/8.0
Choose a base branch
from
Open

DOC-14003 downgrade doc updates #4103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1e150fa
Initial draft
ggray-cb Apr 3, 2026
190f89e
General edits/cleanup.
ggray-cb Apr 6, 2026
2dfa818
Some minor fixes
ggray-cb Apr 13, 2026
166f031
Added links to the Online Downgrade procedure steps.
ggray-cb Apr 15, 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
49 changes: 49 additions & 0 deletions modules/install/assets/images/couchbase_version_numbers.drawio
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<mxfile host="app.diagrams.net">
<diagram name="Page-1" id="Up56mmDf09-GfEDIPxSz">
<mxGraphModel dx="72" dy="40" grid="1" gridSize="1" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-1" parent="1" style="text;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=18;" value="." vertex="1">
<mxGeometry height="11" x="441" y="288" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-3" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=18;spacing=0;" value="0" vertex="1">
<mxGeometry height="16" width="11" x="443" y="285" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-4" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=18;spacing=0;" value="1" vertex="1">
<mxGeometry height="16" width="10" x="456" y="285" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-7" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=18;spacing=0;" value="8" vertex="1">
<mxGeometry height="16" width="10" x="429" y="285" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-10" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;shape=wire;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;dashed=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=none;endFill=0;" value="">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="434" y="307" />
</Array>
<mxPoint x="420" y="307" as="sourcePoint" />
<mxPoint x="434" y="303" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-8" parent="1" style="text;whiteSpace=wrap;strokeColor=none;fillColor=none;align=right;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=15;" value="Major version" vertex="1">
<mxGeometry height="10" width="130" x="290" y="300" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-11" parent="1" style="text;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=18;" value="." vertex="1">
<mxGeometry height="11" x="455" y="288" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-23" edge="1" parent="1" source="Wn0PCLrpr3hHzOSjv8fh-12" style="edgeStyle=orthogonalEdgeStyle;shape=wire;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;dashed=1;endArrow=none;endFill=0;entryX=0.504;entryY=1.126;entryDx=0;entryDy=0;entryPerimeter=0;" target="Wn0PCLrpr3hHzOSjv8fh-3">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-12" parent="1" style="text;whiteSpace=wrap;strokeColor=none;fillColor=none;align=right;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=15;" value="Minor version" vertex="1">
<mxGeometry height="10" width="130" x="290" y="319" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-19" parent="1" style="text;whiteSpace=wrap;strokeColor=none;fillColor=none;align=right;verticalAlign=middle;rounded=0;fontFamily=Open Sans;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DOpen%2BSans;fontSize=15;" value="Maintenance or patch version" vertex="1">
<mxGeometry height="10" width="245" x="175" y="338" as="geometry" />
</mxCell>
<mxCell id="Wn0PCLrpr3hHzOSjv8fh-20" edge="1" parent="1" source="Wn0PCLrpr3hHzOSjv8fh-19" style="edgeStyle=orthogonalEdgeStyle;shape=wire;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.51;entryY=1.146;entryDx=0;entryDy=0;entryPerimeter=0;dashed=1;endArrow=none;endFill=0;" target="Wn0PCLrpr3hHzOSjv8fh-4">
<mxGeometry relative="1" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
4 changes: 4 additions & 0 deletions modules/install/assets/images/couchbase_version_numbers.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
138 changes: 128 additions & 10 deletions modules/install/pages/upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,15 +105,31 @@ 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 <<downgrade>> 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

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.



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 Down Expand Up @@ -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
Expand Down Expand Up @@ -264,11 +280,113 @@ 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 <<version-numbers>> for an explanation of Couchbase Server's version numbering scheme.

[#downgrade_major_minor]
=== Downgrading an Upgrade Between Major or Minor Versions

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 <<version-numbers>> 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 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 <<online-downgrade>> to learn how to perform an online downgrade.

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 after finalization, you can only revert to the earlier version by:

. Creating a new cluster.
. Installing the earlier version of Couchbase Server.
. Migrating your data to the new cluster.

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

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.

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

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

You downgrade a maintenance version upgrade by performing an online downgrade.
See <<online-downgrade>> 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 <<downgrade-maintenance>> for more information.
* You're downgrading an upgrade between major or minor versions of Couchbase Server and you have not finalized the upgrade.
See <<downgrade_major_minor>> 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 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 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.
. 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.
. 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 complete the downgrade.
See <<prevent-finalization>> 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.