A newer version of this documentation is available.

View Latest


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

      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.0, upgrade must be performed twice; first from 5.5.0+ to 6.6, and secondly from 6.6 to 7.0.

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

      If your 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.0, then you would use the following sequence:

      Step Description Upgrades


      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


      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


      Upgrade all nodes from 6.6 to 7.0

      Node 1 ⇒ 6.6 → 7.0
      Node 2 ⇒ 6.6 → 7.0
      Node 3 ⇒ 6.6 → 7.0

      Enterprise Edition Upgrade Paths

      Starting Version Path to Current Version


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

      5.0.x and 5.1.x → 6.6 → 7.0

      5.5.0+ → 6.6 → 7.0


      6.x → 7.0

      Community Edition Upgrade Paths

      Starting Version Path to Current Version


      5.x → 6.0 → 6.5 → 6.6 → 7.0


      6.0 → 6.5 → 6.6 → 7.0

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

      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.0 Enterprise Edition, the process would look like the following:

      upgrade ce to ee for 7
      Figure 1. Example Upgrade Path from Community to Enterprise
      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.

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


      Downgrading from version 7.0.4 to earlier 7.0.x releases

      Couchbase Server 7.0.4

      Due to fixes made to TCP authentication, it is not possible to downgrade from Version 7.0.4 to earlier 7.0.x releases.

      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.