Upgrading from 2.1.5 to 4.0


I am currently working with couchbase 2.1.5 and I would like to upgrade, possibly to the latest stable version : 4.0. We are on ubuntuu and using node sdk.

Nothing else specific with our config.

What should we do ? Can we go direct from 2.1.5 to 4.0 or do we have to upgrade to intermediate releases ? Anything special I should know ?

I am not very familiar with couchbase install process and I would like to do it as safely as possible.

Thanks for your advice.

Best regards


Hey Thomas,

Glad to hear that you’re upgrading from 2.1.5!

Unfortunately you are unable to go straight from 2.1.5 to 4.0 due to potential compatibility issues, it may work for you but this upgrade path has not been through our full QA suite of tests.

Instead your upgrade path should be:

You can perform these upgrades by any method that you wish, which are covered in upgrade strategies, although I would recommend online upgrades as they ensure that your cluster remains fully operational during the upgrade process!

Finally, you should ensure that all nodes in the cluster have been fully upgraded to the next version before beginning subsequent steps.
e.g All nodes must be at 2.2 in the cluster before you begin upgrading any of them to 2.5.2.

May I also ask what version of the node.js SDK you are using? You may want to ensure that you are running the latest version before performing the upgrade as older versions (particularly pre-2.x) of the SDK may have trouble when there are topology changes (which there will be during the upgrade if doing this online).
If you do plan to upgrade your version of the node.js SDK you will probably want to fully test this and do it before upgrading your Couchbase cluster to 4.0.

If all of that sounds like a lot of work for you and you have the spare hardware, an alternative could also be to stand up a brand new cluster on 4.0, configured how you would like and populate it with the data from your existing 2.1.5 cluster.

You could do this by taking a backup with cbbackup and then restoring the data to the new cluster.
Alternatively you could use XDCR to transfer the data across, although I am not 100% sure of the compatibility with 4.x, I think that it should work correctly but it’s worth testing.

Hope this helps, let me know if you have any more questions!

Thank you Matt for this long and precise answer. I’ll look into that and probably get back to you with more questions :slight_smile:

We’re in the same position i.t.o server versions. We’re currently on server v2.5.1, using v1.3.3 of the c# client. I’m assuming we’ll need to upgrade to some newer version of the c# sdk in order for it operate correctly, say v2.2.8.

Will the methods we’re currently using still work, or will we be looking at rewriting some of this?


Sorry, I should have clarified myself more regarding the recommendation to upgrade the client, there should be no outright compatibility issues between any versions of the SDK and Couchbase Server.

Prior to the 2.x release of SDKs, all clients updated their cluster topology maps from a rest endpoint which was generally prone to issues, however a big improvement was made to instead use Optimised Connection Management, which is covered briefly in this blog.
This means that during a rebalance your application will generally be much more stable on the 2.x SDK than on the 1.x SDK, which is why I made that recommendation!

Hello Matt,

Reading your answer (after a few month…), I have the feeling that an “easy way” to do it if we can afford having our app unavailable for a while would be :

  • stop our app and cb server
  • backup data
  • uninstall cb 2.1.5
  • install cb 4.0
  • restore data

Would this work ? Any risk ?

Thank you for your answer.

Best regards


Hi Thomas,

We recently re-wrote the Couchbase docs about upgrades. What you’re describing is the offline upgrade and you can read more about it and the other upgrade options here:

If you decide to do the offline upgrade, be sure to follow the link at the bottom of that page to read up on it.


Hi Thomas,
One important note to add. People who are upgrading from 2.5.x versions of Couchbase should consult MB-19635 to ensure they are moving to a version that supports offline upgrade from 2.5.x.

4.5.0 and 3.1.6 are safe choices. 4.1.2 has the fix but it hasn’t been released yet.


I have similar problem.
We have huge Java 6 web application, that was developed 6-7 years ago.
It is running using Couchbase 2.2 (CE) 10 nodes cluster. Couchbase-client version is 1.4.9.
I just recently joined the team and to get my feet wet, has been given a project to refactor and upgrade the whole thing.
We’ll be upgrading to 14 node cluster running 4.1.1 (CE), 2.2 Java SDK, Java 8, etc.
I need to develop a strategy to ensure:

  1. Zero data loss;

  2. Minimum application downtime.

I was thinking about using XDCR, but now read about possible incompatibilities.
Will cbtransfer be a safer approach?
Apparently, it is not. I have try to do it and got an error message

error: cannot back up 2.x or older clusters with 3.x tools

Now I am at a loss, XDCR has incompatibilities, cbbackup/restore/transfer won’t work. :cry:

You can use backup, you just need to use the backup tools from a 2.x installation, and then use the newer 4.x tools to perform the restore (to your new cluster).

The other thing to consider is you can do perform an online upgrade (i.e. with zero downtime) from 2.2 to 4.1.1. However you’ll have to do it in a number of stages:

  1. 2.2 → 2.5
  2. 2.5 → 3.x
  3. 3.x → 4.1.1

See Couchbase Server | Couchbase Docs for details.

I’d recommend however taking a backup of the data before you start (and probably also testing performing a restore - say on a test cluster) to ensure you have a rollback plan if you hit any issues.

1 Like