A newer version of this documentation is available.

View Latest

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 ascertain if there are bugs that might affect a running cluster or features that might be beneficial.

    For an overview of the new features in Couchbase Server, check out the release notes.

    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

    See Upgrade Matrix for more information on the supported upgrade paths.

    Although infrequent, there may be times when an upgrade to an intermediate version is required before getting to the latest release.

    For information on Couchbase Server end-of-life dates, please see Couchbase support policy.

    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.

    For each upgrade type mentioned above, there is an example checklist to help you start.

    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.

    Do I need to uninstall and reinstall, or just upgrade the Couchbase Server package?

    For all platforms except Mac OS X, you only need to upgrade the package to the new version. Mac OS X may not upgrade successfully without an uninstall and reinstall. For uninstallation instructions, see Uninstalling Couchbase Server.