Upgrading to Couchbase Server 6.5

Upgrading to the latest version of Couchbase Server allows you to leverage the latest features and helps keep your cluster running well. The following table summarizes the new features in this release, and describes what parts of the cluster need to be upgraded to enable them.

Table 1. Couchbase Server 6.5 Feature Upgrade Matrix
Feature Upgrade Level Upgrade Type Upgrade Path Mixed Mode Dependencies

Durability

Cluster

Offline/Online

Direct

No

Existing Observe APIs for replicateTo and persistTo will continue to exist.

The new APIs for synchronous durability require Server 6.5 and SDK 3.0.

Robust rebalance

Cluster

Offline/Online

Direct

No

Available only when all nodes in a cluster are upgraded to 6.5.

Transactions

Cluster

Offline/Online

Direct

No

For XDCR setup, both source and target clusters must be on 6.5+ if transactions are used at the source cluster.

SDK 3.0 has to be used for the new APIs.

Node-to-node encryption

Cluster

Offline

First upgrade to 6.5 and then enable node-to-node encryption on every node using the API/CLI. Restart server for encryption to be effective.

No

With node-to-node encryption (and data option), newer TLS ports will be opened between services. If your firewalls are locked down to just the bare minimum ports, you will have to update your firewall rules to include the newer ports.

See Network and Firewall Requirements for the list of ports.

TLS cipher configuration

Cluster

Offline/Online

Direct

No

Available only when all nodes in a cluster are upgraded to 6.5.

LDAP Group Support

Cluster/Node

Offline/Online

Direct

No

Groups are not created during upgrade and built-in users continue to exist. A full administrator must create Couchbase Groups, add built-in users to these groups, and map Couchbase groups to Couchbase roles.

Analytics: MPP for parallel sort

Cluster

Offline/Online

Direct

No

No dependencies.

Analytics: Log redaction

Cluster

Offline/Online

Direct

No

No dependencies.

Analytics: Index creation without disconnecting bucket

Cluster

Offline/Online

Direct

No

No dependencies.

Analytics: (Metadata) backup

Cluster

Offline/Online

Direct

No

No dependencies.

N1QL-FTS integration

Node

Offline/Online

Direct

No

This feature will be available only when both Query and Search nodes are upgraded to 6.5.

Backup enhancements

Cluster

Offline/Online

Direct

No

No dependencies.

XDCR - advanced filtering

Cluster

Offline/Online

Direct

No

The source cluster must be running version 6.5, the target cluster can be on an earlier version. Key-based filtering is available on any nodes that are running earlier versions.

XDCR - prioritization of replication

Cluster

Offline/Online

Direct

No

The source cluster must be running version 6.5, the target cluster can be on an earlier version.

Mixed Mode

Mixed Mode in this context refers only to the nodes that are running the indicated service. So if No is marked in the Mixed Mode column for a given feature, then all of the cluster nodes that are running that service must be upgraded to Couchbase Server 6.5 in order to enable that feature. If Yes, then the feature can potentially be enabled even if some of the nodes that are running the indicated service are on older versions of Couchbase Server.

Prepared Statement Upgrades

When performing an online upgrade from Couchbase Server 6.0.3 or earlier to Couchbase Server 6.5 (or later), an improvement to Couchbase Server security in N1QL may cause active Couchbase SDK 2.x applications to return the error 4040: No such prepared statement. Note that 2.x here refers to the 2.x SDK API, and so includes Couchbase Go SDK 1.x.

Client-side workarounds:

  • Restart the application server after the server upgrade. This implicitly clears the client cache, leading it to prepare statements again.

  • Change the application code. If the application receives an error 4040, clean the cache using invalidateQueryCache() and retry. (This only works for Java.)

  • Upgrade to Java SDK 2.7.13; Go SDK 1.6.6; or LCB 2.10.6 (for C, Node.js, PHP, or Python SDK), or to SDK 3.0.

Server-side workarounds:

  1. Upgrade the first node — this can be a Data service node, or any other node.

  2. Increase the prepared statement cache size. In the Query Workbench, go to Settings  General  Query Settings  Advanced Query Settings and set Prepared Limit to 66560.

  3. Make sure that encoded_plan will be honored. Also in Settings  General  Query Settings  Advanced Query Settings, set N1QL Feature Controller to 8.

These settings persist, and will be used as other query service nodes are upgraded.