Upgrading

Upgrading

The Couchbase Server can be upgraded online (using swap rebalance or the standard online upgrade), offline, or using XDCR.

Remember: Before performing an upgrade, whether it is online or offline, back up your data.

Install the latest version of the Couchbase Server. The installer will automatically detect the files from the earlier installation and convert them to the correct format, if needed.

Feature Online upgrades Offline upgrades
Applications remain available Yes No
Cluster stays in operation Yes No
Cluster must be shut down No Yes
Time required Requires rebalance, upgrade, rebalance per node All nodes in cluster upgraded at once
CAUTION:
Replication of certain per-node keys is broken after a node is first upgraded offline from 2.x to 3.0 and then added back to the formerly 2.x cluster that is now upgraded to 3.0. When performing an online upgrade from the Couchbase Server 2.x to 3.x, always fully delete the 2.x package (including the config files) before installing the 3.x package.

Online upgrades

When you perform an online upgrade, there is no need to take the cluster down and application keeps running during the upgrade process. You can upgrade the Couchbase Server using a standard online upgrade, or an online upgrade with swap rebalance.

Online upgrade with swap rebalance
For swap rebalance, first add a node to the cluster and then perform a swap rebalance to shift data from an old node to the new one. This is the preferred upgrade method when there is not enough cluster capacity to handle data once an old node is removed. It is also much faster from the standard online upgrade, because you only need to rebalance each upgraded node once. For this procedure see Online upgrade with swap rebalance .
Standard online upgrade
For standard online upgrade, take down one or two nodes from a cluster and rebalance so that remaining nodes handle incoming requests. You can use this upgrade option only if you have enough remaining cluster capacity to handle the nodes you want to remove and upgrade.
Standard online upgrades can take a while, because each node must be taken out of the cluster, upgraded to a current version, brought back into the cluster, and then rebalanced.
Important: Swap rebalance is recommended because it always maintains cluster capacity. Use the standard online upgrade only if upgrade with swap rebalance is not possible.
Important: The suggested procedure is to rebalance and remove a node, proceed with a swap upgrade as if the removed node was an extra ‘spare’ node, and once this is done add and rebalance the extra node back in.

Offline upgrades

Offline upgrades can take less time than online upgrades because all nodes in the cluster can be upgraded at once.

An offline upgrade must be well-planned and scheduled. First, shut down your application so that no more incoming data arrives. Second, verify that the disk write queue is 0 and then shut down each node. This way you know that the Couchbase Server has stored all items onto disk during shutdown. After shutting down applications and nodes, perform the upgrade on each machine and then bring the cluster and applications back again.

To perform an offline upgrade, see Offline upgrade .

Upgrading with XDCR

This upgrade has to be taken cautiously and only in specific situations. Be sure that you are familiar with all requirements before deciding to use this process.