Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Upgrade

      +
      To upgrade a Couchbase-Server cluster means to upgrade the version of Couchbase Server that’s running on every node.
      Upgrading from Versions 7.1 or 7.2 to Versions 7.6.0 or 7.6.1

      If there are index service nodes running in your cluster, you must use the swap rebalance method when upgrading from Couchbase Server 7.1 or 7.2 to Server 7.6.0 or 7.6.1.

      See Swap Rebalance for more information about the swap rebalance method.

      Before You Upgrade

      Before upgrading, consider the following version compatibility concerns.

      New Default Storage Backend in Couchbase Server Version 8.0

      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 2 behavior changes from previous versions:

      • 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 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 views feature. On versions prior to Couchbase Server 8.0, your script created a Couchstore bucket with 1024 vBuckets, In version 8.0, due to change in the default backend, your script creates a bucket with the Magma storage backend with 128 vBuckets. Attempting to use MapReduce Views with this bucket results in errors, because Magma buckets do not support this feature.

      Views are deprecated in Couchbase Server 7.0 and later versions. Views support in Couchbase Server will be removed in a future release. Instead of views, use indexes and queries using the Index Service (GSI) and the Query Service (SQL++). Views will not run on the newer Magma storage engine.

      Another concern is that versions of Couchbase Server earlier than 8.0 do not support XDCR replication between buckets with different numbers of vBuckets. Therefore, you cannot replicate to a bucket you create with the new default backend setting from buckets on an earlier server version. To replicate from a bucket on an earlier version of Couchbase Server, explicitly set the new bucket’s storage backend to Couchstore or to Magma with 1024 vBuckets during creation.

      For more information about storage backends, see Storage Engines.

      x86 AVX2 Requirement for Couchbase Server Version 8.0 and Later

      When running on x86-64 processors, Couchbase Server 8.0 and later requires that the CPU support the AVX2 instruction set. Most Intel processors manufactured since 2013 and AMD processors manufactured since 2015 support AVX2. If you attempt to run Couchbase Server 8.0 or later on a CPU that does not support AVX2, the server exits with an error. See Instruction Set Requirements for x86 Processors for more information.

      Memcached Buckets Have Been Removed in Couchbase Server Version 8.0 and Later

      Memcached buckets have been removed in Couchbase Server 8.0 and later. The upgrade process exits with an error if you attempt to upgrade a cluster with Memcached buckets. If your cluster has Memcached buckets, you must replace them with ephemeral buckets before upgrading. See Bucket Capabilities in the Version 6.6 documentation for a summary of the differences between Memcached and ephemeral buckets.

      Upgrading to Version 7.x With Earlier Versions of .NET SDK

      When upgrading from Couchbase 6.5 or 6.6 to 7.0 or later, determine if both of the following are true:

      • You use a version of the .NET SDK prior to 3.2.9.

      • Your cluster is in mixed mode networking where some nodes use IPv4 addressing and others use IPv6. See Changing Address Family for steps to determine if your cluster is running in this mode.

      Using a version of the .NET SDK prior to 3.2.9 with mixed mode network addressing can cause issues with write operations. Before upgrading, resolve the mixed-mode networking issue.

      Upgrading from Pre-7.1 Versions of Couchbase Server

      You cannot upgrade directly from a version of Couchbase Server earlier than 7.1 to version 7.2.4 or later.

      For example, you can directly upgrade from version 6.6 to version 7.2.3.

      You cannot directly upgrade from version 6.6 to version 7.2.4. A compatibility issue with the Erlang version used by these earlier server versions prevents a direct upgrade to later versions of the server. To upgrade from server versions 6.5, 6.6, or 7.0 to version 7.6 or later, first upgrade to a version between 7.1 and 7.2.3. Then upgrade to version 7.6 or later.

      Understanding Upgrade

      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 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 Upgrade Procedure-Selection.

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

      As far as is possible, you should aim to keep your cluster up to date with the latest version of Couchbase Server.

      Enterprise Edition Upgrade Paths

      Starting Version Path to Current Version

      5.x

      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 → latest 7.2.x → 8.0.1

      7.x

      Any 7.0.x / 7.1.x → 7.2.3 → latest 7.2.x → 8.0.1

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

      Community Edition Upgrade Paths

      Starting Version Path to Current Version

      5.x

      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 → latest 7.2.x → 8.0.1

      7.x

      Any 7.0.x / 7.1.x → 7.2.3 → latest 7.2.x → 8.0.1

      Any 7.2.x → latest 7.2.x → 8.0.1 Any 7.6.x → latest 7.6.x → 8.0.1
      Important note when upgrading from 7.0.4 to 7.2.x on Windows 2019
      Upgrading from version 7.0.4 → 7.2x on Windows Server 2019 may result in a missing java executable files error. 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.

      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’re upgrading several nodes at once, then you must keep the version of the software on each node in step throughout the upgrade process.
      For example, if you upgrade 3 enterprise nodes (Node 1, Node 2 and Node 3) from version 5.1x to 7.6.x, then you would use the following sequence:

      Example 1. Upgrading from version 6.6.x to 8.0.x
      Step Description Upgrades

      1

      Upgrade all nodes from 6.6.x to 7.2.3

      Node 1 ⇒ 6.6.x → 7.2.3
      Node 2 ⇒ 6.6.x → 7.2.3
      Node 3 ⇒ 6.6.x → 7.2.3

      2

      Upgrade all nodes from 7.2.3 to 8.0.x

      Node 1 ⇒ 7.2.3 → 8.0.x
      Node 2 ⇒ 7.2.3 → 8.0.x
      Node 3 ⇒ 7.2.3 → 8.0.x
      Upgrading between non-adjacent version numbers is not supported.
      To upgrade from 5.1.x to 7.2.4, 3 upgrades must be performed (as shown in Example 1):
      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.

      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 rebalance 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’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 later version of Enterprise Edition, you need to perform 2 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.6 Enterprise Edition, the process would look like the following:

      Example Upgrade Path from Community to Enterprise
      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 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. 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 capability.

      • If a rolling online upgrade to Enterprise Edition is not 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. Graceful Failover for Data Service nodes, with Delta Recovery, is not supported for such upgrades: instead you should use removal, addition, and swap rebalance for all nodes.

      Node-Naming and 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 Node-Certificate Validation.

      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:

      1. Remove the target node from the cluster, then perform a rebalance on the cluster.

      2. Downgrade the target node (or create a new node using the earlier version of Couchbase).

      3. Add the node to the cluster and rebalance.

      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.