A newer version of this documentation is available.

View Latest

Upgrading Couchbase Server

Upgrading Couchbase Server is a recommended regular best practice to ensure ideal cluster operation and supportability.
Back up your cluster data with the cbbackup tool before performing any upgrade.

Take into account the best practices for upgrading Couchbase Server.

Once a cluster is upgraded to a new version that contains new features, settings, API, and so on, you cannot add an older server version to that cluster since it will break the cluster compatibility.
Supported upgrade path

See Upgrade matrix for more information on the supported upgrade paths.

Although infrequent, there may be times when an upgrade to an intermediate version is required before getting to the latest release.

Cross-Datacenter Replication (XDCR)

To perform an upgrade, you can deploy a new cluster with the upgrade target version and then use XDCR to replicate bucket data from the existing cluster to the new cluster.

Multi-Dimensional Scaling (MDS)

Data, query, and index workloads are all independently scalable in Couchbase Server version 4.x. You must consider all node service types when upgrading a cluster that uses multiple service types.

If your cluster uses multiple service types, upgrade each type in a rolling manner. While upgrading, address only the nodes that support a given service to ensure that the service is not disrupted during the upgrade. If the node has multiple services, also ensure that enough of such nodes remain to service requests for the different services when upgrading.

Consider the following additional points about MDS and node service types when planning your upgrade:

  • You cannot introduce additional node service types when adding a newly upgraded node to a cluster consisting of mixed version 3.x and 4.x nodes. If you attempt to upgrade a node to 4.x and introduce it back into the cluster with additional services checked prior to upgrading all nodes, you’ll see a red warning similar to this:

    Attention - services parameter is not supported in this cluster compatibility mode.

  • You can be prompted to change the Server Quota When adding a node with additional data services selected to a cluster.

    If you are adding additional services to the nodes while upgrading, this can affect the Server RAM Quota, and you will be prompted to adjust it.

Sync Gateway

Take special precaution when upgrading Couchbase Server if your cluster is used for replication through Sync Gateway.

Be aware that Sync Gateway (as of version 1.1.0) does not yet support the automatic handling of Couchbase Server cluster topology changes for related buckets.

If you plan to upgrade a Couchbase Server cluster used by the Sync Gateway versions less than or equal to 1.1.0, you must carefully coordinate manual reconfiguration of the Sync Gateway service between the key points in your upgrade process.

Updating Sync Gateway configuration manually to reflect changes in the cluster topology during an upgrade-related rebalancing is required to ensure that Sync Gateway can continue to connect to an active and healthy node.

Community Edition to Enterprise Edition

If you are performing an online upgrade, you can rebalance nodes upgraded to Enterprise Edition into a Community Edition cluster. Be sure to use the same version when upgrading from the Couchbase Server Community Edition to Couchbase Server Enterprise edition. Version differences can result in a failed upgrade.

If you are performing an offline upgrade from Community Edition to Enterprise Edition, shut down the entire cluster and uninstall Couchbase Server Community Edition from each machine. Then install Couchbase Server Enterprise Edition on these machines. The data files will be retained, and the cluster can be restarted.