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.0.
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 upgrade paths from one major version to another.
Be aware of the currently supported versions and versions at or near their end of life. The support information is available in the Couchbase Support Policy.
Although infrequent, there may be times when an upgrade to an intermediate version is required before getting to the latest release.
| Current Version | Edition | Upgrade Option | Path |
|---|---|---|---|
3.x |
Enterprise Edition |
Offline or Online |
3.x > 5.0 > 6.0 |
4.x |
Enterprise Edition |
Offline or Online |
4.x > 5.0 > 6.0 |
5.x |
Enterprise Edition |
Offline or Online |
Direct upgrade to 6.0 |
3.x |
Community Edition |
Offline or Online |
3.x(CE) > 3.x(EE) > 5.0(EE) > 6.0(EE) |
4.x |
Community Edition |
Offline or Online |
4.x(CE) > 4.x(EE) > 5.0(EE) > 6.0(EE) |
5.x |
Community Edition |
Offline or Online |
5.x(CE) > 5.x(EE) > 6.0(EE) |
The following table shows some commonly supported upgrade paths:
| Current version | Target version | Process |
|---|---|---|
2.5.x |
3.x |
Upgrade from version 2.5.x directly to the latest version 3.x using any supported upgrade strategy. |
3.x |
4.x |
Upgrade from the latest version 3.x directly to version 4.x using any supported upgrade strategy. |
2.5.x |
4.x |
Upgrade from the latest version 2.5.x directly to version 4.x using any supported upgrade strategy. |
4.0 |
4.x (> 4.0) |
Services require more planning during an upgrade. |
4.x |
5.x |
Services require more planning during an upgrade. |
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.
| When upgrading from the Community Edition to the Enterprise Edition, ensure that you use the same Couchbase Server version number. Version differences can result in a failed upgrade. |
Multi-Dimensional Scaling (MDS)
In Couchbase Server Enterprise Edition version 4.0+ the Data, Query, and Index Service workloads can all 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 4.5 and one still on 4.1.x, you can still roll all nodes back to 4.1.x.
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?
-
You can perform online and offline upgrade options when upgrading from Couchbase Server Community Edition to Enterprise Edition. Remember that Enterprise Edition is not free to run in production. If you are interested in upgrading to Couchbase Server Enterprise Edition, click here. For more information on supported upgrade paths of Couchbase Server, see the upgrade-matrix.adoc.
- 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.