Upgrading from couchbase 2.2 to 3.0

I would like to know the safest upgrade path from 2.2 to 3.0? I see that i have a few options and please correct me where I am wrong.

  1. Back up couchbase data using CLI tool…upgrade server and client to 3.0…then use the backup tool to restore

  2. Spin up a new 3.0 cluster and replicate data over. Then upgrade clients to point to the new cluster…with the new SDK.

I would like to hear from an Engineer on this. I am thinking the latter is the safer bet…with less downtime

The most common approach is node-by-node rebalance upgrade. Make sure you use Couchbase Server version 3.0.1. Also, it’s (of course) a good idea to have a backup from the 2.2 cluster with cbbackup before beginning.

You don’t state which client library you’re using. Depending on the version we may offer some specific advice, but the most common advice is to check the release notes for fixes in maintenance releases which could impact your deployment and if possible, update to the most recent within the dot-minor or major you’re using.

Thanks for that. We will be upgrading the client library in lockstep should we go down the upgrade path. To be perfectly frank adding and removing node in couchbase 2.2 has been a painful process for us and has resulted in us losing a large percentage of data 4 times out of 6 so I would rather stay away from rebalancing and swapping in nodes.

We can take downtime to mitigate the problem…If we take down time can we do this all without rebalancing?

Sorry to hear of the troubles. I know 2.5 addressed a lot of the rebalance issues but you shouldn’t have been losing data. In 2.2, there were scenarios where rebalance would fail, but it was re-startable.

I’ll defer to the documentation, but offline upgrade should be no problem. As previously recommended, do a backup first.


I would be interested to know the cases where you encountered data loss while doing swap rebalance in case of 2.2. Knowing the SDK version would be useful too.

If you’re planning to go for offline upgrade from v2.2 to v3.0.1, then I would recommend:

  • 1st option(using cbbackup and node upgrade):
    • Stop traffic to couchbase cluster, make sure disk queue items have dropped down to 0. Disable auto-failover.
    • Take cbbackup snapshot of your data to have a backup in case something bad happens.
    • Upgrade the cluster nodes one by one, using either(if you’re running on linux):
rpm -U couchbase-server-architecture_meta_current_version.rpm
dpkg -i couchbase-server-architecture___meta_current_release.deb

Post this cluster nodes will warm-up and you could monitor the status using cbstats utility. Once all nodes are online, start ramping up production traffic to v3.0.1 cluster.

  • 2nd option(using cbtransfer utility):

  • Stop traffic to couchbase cluster, make sure disk queue items have dropped down to 0.

  • Create another cluster with similar specs as current one running on v3.0.1

  • Fire cbtransfer utility to transfer data from original cluster to new cluster. Might take some time depending on your dataset.

  • Once transfer is done, change your couchbase connection string to point to the new cluster running on v3.0.1.

I’ll not suggest XDCR on v2.2 to transfer data to v3.0.1 cluster because of some known issues and it needs close assistance from Couchbase Support.

Wow thank you…I can follow up with more details in a but. But If the cluster is offline…do we need to do a node by node rebalance or just one big one?

If you’re bringing up same v2.2.0 online after offline upgrade to v3.0.1, rebalance isn’t required. I have seen a case where Admin Console UI reports “Rebalance required” after offline upgrade but it’s a false alarm and if you click on “Rebalance” button, it finishes in no time and no vbuckets are transferred. We will get it addressed.

Hi, I have a v2.2 community edition cluster using XDCR to sync data to an Elasticsearch cluster. I am wondering if I can do online upgrade to v3.x by swap rebalance method. It seems upgrading v2.2 to v3 is complicated when XDCR is in place. Is there any step-by-step guide for this? Or does anyone have experience on this?