Upgrading Couchbase Server
Periodically upgrading Couchbase Server helps maintain a properly functioning cluster and offers new features. Upgrading is a relatively simple process that usually incurs zero downtime.
Upgrading Couchbase Server regularly is vital to keep your cluster running well. New releases of Couchbase Server provide both bug fixes and new features. For each release, read the Release Notes to understand if there are bugs that might affect a running cluster, or if there are new features that you might find beneficial.
See the following topic for a list of new features in this release and their upgrade behavior: Upgrading to Couchbase Server 6.6.
When to Do an Upgrade
If you can, it is best to upgrade during off hours. Avoid upgrading during the system’s peak usage times. Even though rebalances are designed to be a background process, they can impact performance.
Supported Upgrade Paths
Couchbase Server supports direct upgrades up to a maximum of one major version ahead. That means, if you’re more than one major version behind, you’ll need to upgrade to an intermediate version before getting to the latest release.
| Current Version | Edition | Upgrade Option | Path |
|---|---|---|---|
3.x |
Enterprise Edition |
Offline or Online |
3.x → 4.x → 5.5.0+ → 6.6 |
4.x |
Enterprise Edition |
Offline or Online |
4.x → 5.5.0+ → 6.6 |
5.x |
Enterprise Edition |
Offline or Online |
5.0.x and 5.1.x → 6.0.4+ → 6.6 5.0.x and 5.1.x → 6.6 5.5.0+ → 6.6 |
6.x |
Enterprise Edition |
Offline or Online |
Direct upgrade to 6.6 |
| Current Version | Edition | Upgrade Option | Path |
|---|---|---|---|
3.x |
Community Edition |
Offline or Online |
3.x → 4.x → 5.x → 6.0 |
4.x |
Community Edition |
Offline or Online |
4.x → 5.x → 6.0 |
5.x |
Community Edition |
Offline or Online |
5.x → 6.0 → 6.5 |
6.x |
Community Edition |
Offline or Online |
Direct upgrade to 6.6 |
Be aware of the currently-supported versions of Couchbase Server, as well as the versions that are at or near their end of life. This information can be found in the Couchbase Support Policy.
Upgrading from Community 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 reblance' 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.)
The Enterprise Edition nodes must be running the same version number of Couchbase Server as the Community Edition nodes that they are replacing, otherwise the upgrade may fail. This means you can’t 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 newer version of Enterprise Edition, you need to perform two separate upgrade procedures:
-
Upgrade the entire cluster to Enterprise Edition via a rolling online upgrade
-
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 5.0.1 Community Edition to Couchbase Server 6.0.1 Enterprise Edition, the process would look like the following:
-
Couchbase Server clusters must be run either entirely on Enterprise Edition nodes, or entirely on Community Edition nodes.
-
Once you’ve upgraded one node to Enterprise Edition, you must upgrade all of the other nodes before the cluster is considered as being in a steady, supportable state.
-
-
If a rolling online upgrade to Enterprise Edition isn’t 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. |
Preparing for an Upgrade
Before upgrading your production cluster, be sure to test the upgrade process in a test environment that matches your production environment as closely as possible.
Multi-Dimensional Scaling (MDS)
In Couchbase Server Enterprise Edition version 4.0+, all services can be independently scaled, to isolate workloads. This feature is called Multi-Dimensional Scaling (MDS).
While all nodes are part of a cluster, each node in the cluster might only run one or more services. For example, consider a seven-node cluster: three nodes run only the Data Service, two nodes run only the Indexing Service and two nodes run just the Query Service. In this example, each workload is isolated to a set of nodes. There are special considerations for most online upgrade options in an MDS cluster. For more information on this, see Performing the Rolling Online Upgrade.
Downgrades and Limitations
Once an upgrade of a single Couchbase Server cluster has started, you can roll back to the previous version as long as at least one node is on the previous version. For example, if you have three nodes upgraded to 6.0 and one still on 5.5, you can still roll all nodes back to 5.5.
Once all nodes in the cluster have been fully upgraded, the window for a rollback of that cluster has closed. If you first upgrade a cluster but then decide to downgrade to a previous version, your only option is to set up another Couchbase Server cluster and use XDCR with the target cluster being the older version.
Follow Upgrading Using Intercluster Replication, having in mind that the new cluster would be the older version to which you are rolling back.
Precautions for Couchbase Mobile’s Sync Gateway
Take special precaution when upgrading Couchbase Server if you use the cluster in conjunction with Sync Gateway
Sync Gateway versions prior to v1.2 do not support the automatic handling of Couchbase Server cluster topology changes for related buckets. An upgrade of Couchbase used with older versions of Sync Gateway must carefully coordinate a manual reconfiguration of the Sync Gateway service connection between the key points in your upgrade process.
It is recommended first to upgrade all Couchbase Sync Gateways to at least version 1.2 before upgrading the Couchbase Server cluster to which they are connected.
Upgrade FAQ
- At which point in the upgrade process will the new features of the upgrade be available?
-
Once every node in the cluster is upgraded to the target release, the new features of that release are available for use. Even if 90% of all nodes are upgraded, the cluster is still considered to be on the older revision, and newer features are unavailable.
- Do I have to upgrade the Couchbase client SDKs?
-
You are not required to upgrade the client SDKs your applications use when you upgrade Couchbase Server. Couchbase client SDKs are forward and backward compatible. You may want to upgrade, however, because older client SDKs typically cannot take advantage of the newest Couchbase Server features.
It is strongly recommended to verify periodically the version of client SDK being used by applications and to plan for regular upgrades. Every month Couchbase releases new versions that contain updates, bug fixes and new features for each SDK. For more information and release notes, see the supported client SDKs.
- Can I upgrade from Couchbase Community Edition to Enterprise Edition?
-
Yes. Refer to Upgrading from Community to Enterprise for detailed information.
If you’d like to know more about Couchbase Server Enterprise Edition, check out the editions page.
- Do I need to uninstall and reinstall, or just upgrade the Couchbase Server package?
-
For all platforms except macOS, you only need to upgrade the package to the new version. On macOS, Couchbase Server may not upgrade successfully without an uninstall and reinstall. For instructions on how to uninstall Couchbase Server, see Uninstalling Couchbase Server.