Upgrade

    +
    To upgrade a Couchbase-Server cluster means to revise upwards the version of Couchbase Server that is running on every node.
    Upgrading to Version 7.x with older versions of .NET SDK

    If you are upgrading to Couchbase 6.5/6.6 → 7.x+ whilst using .NET SDK prior to 3.2.9 then make sure your cluster is not running in mixed mode (i.e. some nodes are using IPv4 addressing while some are using IPv6) before issuing any write operations on the cluster.

    Understanding Upgrade

    To upgrade a Couchbase-Server cluster means to revise upwards the version of the server that is running on every node. For example, a cluster each of whose nodes has been running Couchbase Server Enterprise Edition Version 6.6 is modified; such that each of its nodes subsequently runs Couchbase Server Enterprise Edition Version 7.2.

    An upgrade procedure, like an install procedure, involves both preparation routines and specific upgrade commands that are performed on each individual node. To be upgraded, a cluster must have each of its nodes individually upgraded in turn; and the upgrade procedure for the cluster must therefore be selected with regards to whether the cluster is required to continue serving data, or to cease serving data, during the course of the cluster-upgrade. A review of the factors that determine the appropriateness of an upgrade-procedure is provided in Upgrade Procedure-Selection.

    Upgrade Paths

    An upgrade path declares that the upgrade of one version of Couchbase Server to another is supported. The tables in the following subsections list upgrade paths for Enterprise Edition and for Community Edition, respectively. Each instance of the sign → declares support for the upgrade of the server-version on the left of the sign to the server-version on the right. Note that upgrade between non-adjacent version-numbers is frequently not supported: for example, to upgrade from 5.5.0+ to 7.2, upgrade must be performed twice; first from 5.5.0+ to 6.6, and secondly from 6.6 to 7.2.

    All supported upgrades can be performed with the cluster either offline or online.

    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 1, Node 2 and Node 3) from version 5.0x to 7.2, then you would use the following sequence:

    Step Description Upgrades

    1

    Upgrade all nodes from 5.0x to 5.1x

    Node 1 ⇒ 5.0x → 5.1x
    Node 2 ⇒ 5.0x → 5.1x
    Node 3 ⇒ 5.0x → 5.1x

    2

    Upgrade all nodes from 5.1x to 6.6

    Node 1 ⇒ 5.1x → 6.6
    Node 2 ⇒ 5.1x → 6.6
    Node 3 ⇒ 5.1x → 6.6

    3

    Upgrade all nodes from 6.6 to 7.2

    Node 1 ⇒ 6.6 → 7.2
    Node 2 ⇒ 6.6 → 7.2
    Node 3 ⇒ 6.6 → 7.2

    Enterprise Edition Upgrade Paths

    Starting Version Path to Current Version

    5.0.x

    5.0.x and 5.1.x → 6.0.4+ → 6.6 → 7.2x

    5.0.x and 5.1.x → 6.6 → 7.2x

    5.5.0+ → 6.6 → 7.2x

    6.x

    6.0 → 6.5 → 7.2x

    Community Edition Upgrade Paths

    Starting Version Path to Current Version

    5.x

    5.x → 6.0 → 6.5 → 7.2x

    6.x

    6.0 → 6.5 → 7.2x

    Important note when upgrading from 7.0.4 to 7.2x on Windows 2019

    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.

    Upgrade from Community Edition to Enterprise

    If you’re currently operating a Couchbase Server cluster on Community Edition, you can upgrade it to Enterprise Edition by way of a rolling online upgrade. This involves switching out the Community Edition nodes with fresh, net-new Enterprise Edition nodes. Both 'swap rebalance' and 'remove and reblance' methods are supported. (Delta Recovery is not supported since the new nodes must be fresh Enterprise Edition installations without any pre-existing Community Edition data remaining on them.)

    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.

    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:

    1. Upgrade the entire cluster to Enterprise Edition via a rolling online upgrade

    2. Upgrade to the desired version number of Couchbase Server using any supported type of upgrade

    For example, if you wanted to upgrade from Couchbase Server 6.6 Community Edition to Couchbase Server 7.2 Enterprise Edition, the process would look like the following:

    Example Upgrade Path from Community to Enterprise
                  /-----------------\           /-----------------\
                  |     Step 1:     |           |     Step 2:     |
                  : Upgrade Edition |           : Upgrade Version |
                  \--------+--------/           \--------+--------/
                           |                             |
                           |                             |
    +-----------------+    :     +-----------------+     :      +-----------------+
    |cBLU             | ---+---> |cC02             | ----+----> |cC02             |
    |Cluster 1        | Rolling  |Cluster 1        |    Any     |Cluster 1        |
    |Version: 6.6     | Online   |Version: 6.6     | Supported  |Version: 7.2     |
    |Edition: CE      | Upgrade  |Edition: EE      |  Upgrade   |Edition: EE      |
    |              {s}|          |              {s}|   Type     |              {s}|
    +-----------------+          +-----------------+            +-----------------+
    Additional Notes about Upgrading from Community to Enterprise
    • 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.

    • 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.
      Users can create equivalent indexes (same index with 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.

    Remember that Enterprise Edition is not free to run in production. If you’re interested in upgrading to Couchbase Server Enterprise Edition, check out the editions page.

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

    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. For information, see Node-Certificate Validation.

    Downgrade

    Once an upgrade of a Couchbase-Server cluster has started, downgrade to the earlier version of Couchbase Server can be performed, provided that one node continues to run the earlier version. However, 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.