SDK Release Notes

KCBC-132: BucketManager and CollectionManager now know about the history preservation settings added in Couchbase Server 7.2.

JVMCBC-1402, JVMCBC-1410: Upgraded Netty from 4.1.96 to 4.1.100, and upgraded OpenTelemetry dependency.

JVMCBC-1430: Optimization: removed creation of unnecessary metrics labels when default LoggingMeter is used.

JVMCBC-1391: The Bucket Manager API is now forward-compatible with future versions of Couchbase Server that might support storage engine types other than "magma" and "couchstore".

JVMCBC-1327: Improved support for failover handling in future server versions.

KCBC-139: When using BucketManager with Couchbase Server Community Edition, specifying a bucket creation argument not supported by Community Edition now always results in a FeatureNotAvailableException. Previously, this exception was thrown only if the argument differed from the default.

JVMCBC-1264: DNS SRV lookups now honor the DNS search path. This enables DNS SRV resolution in Kubernetes environments where the *-srv hostname advertised by the Couchbase Operator is a partial name that must be resolved using a suffix from the DNS search path.

JVMCBC-1426: When Couchbase Server is too busy to start a new KV range scan, the SDK now retries instead of throwing a CouchbaseException.

JCBC-2046: With thanks to community member Marcin Grzejszczak for the contribution, support for Micrometer Observation has been added to all JVM SDKs via the new tracing-micrometer-observation module.

JVMCBC-1327: Internal improvements to support upcoming faster failover and config push features.

JVMCBC-1364: Fixed decoding of certain niche sub-document errors, so they no longer raise a DecodingFailureException.

JVMCBC-1367: The db.couchbase.operations metric now has db.name (bucket), db.couchbase.scope, db.couchbase.collection and outcome labels (tags). This new feature is at Stability.Volatile, and may change before it is promoted to Stability.Committed in a future release.

JVMCBC-1311, JVMCBC-1352: Upgraded dependencies.

JVMCBC-1350: lookupInAnyReplica now throws FeatureNotAvailableException if the server does not support the feature.

JVMCBC-1351: lookupInAnyReplica no longer hangs when too many operations are specified.

JVMCBC-1353: Removed the unrelocated io.opentracing classes that accidentally slipped into version 2.4.9 of the Couchbase core-io library.

JVMCBC-1361: When the SDK receives multiple cluster map versions at the same time, it is now more careful about applying only the most recent version. Before this change, there was a brief window where the SDK could apply an obsolete cluster map. If this happened, the SDK would temporarily dispatch requests to incorrect or non-existent nodes. This condition was typically short-lived, and healed the next time the SDK polled for an updated cluster map, or dispatched a KV request to the wrong node.

JVMCBC-1368: Fixed a rare java.lang.ArithmeticException: / by zero exception in RoundRobinSelectionStrategy.select that could occur during rebalance.

JVMCBC-1339: When KV traffic capture is enabled, each ReadTrafficCapturedEvent now contains a single protocol frame, and the human-readable frame description is more accurate.

JVMCBC-1320: The waitUntilReady method is now more aggressive about retrying failed pings. Also, waiting for a desired state of DEGRADED no longer fails when the client is fully connected to the cluster.

JVMCBC-1343: Reduced the default value for the io.idleHttpConnectionTimeout client setting to 1 second. The previous default (4.5 seconds) was too close to the 5-second server-side timeout, and could lead to spurious request failures.

JVMCBC-1322: The waitUntilReady() method now logs additional diagnostic information to the com.couchbase.core.WaitUntilReady logging category at DEBUG level.

KCBC-123: Added new versions of MutateInSpec.incrementAndGet and decrementAndGet without a delta parameter ("increment/decrement" implies the delta is 1). Added a MutateInSpec.addAndGet method that takes a delta. Deprecated the old increment/decrement methods that take a delta, in favor of the new addAndGet method.

JVMCBC-1290: Added a new client setting, security.enableCertificateVerification, which defaults to true. This setting allows disabling TLS certificate verification in development environments where configuring the CA certificate to trust is not practical. Setting this to false is equivalent to configuring the environment to use InsecureTrustManager.INSTANCE. For compatibility with other modern Couchbase SDKs, certificate verification can now be disabled using the connection string parameter tls_verify=none. This feature is introduced at stability level Volatile, meaning it may change in a patch release without notice.

JVMCBC-1278, JVMCBC-1310, JVMCBC-1313: Dependencies updated.

JVMCBC-1223: Adds a RetryReason.AUTHENTICATION_ERROR at Uncommitted API stability level. A custom RetryStrategy can use this new, more granular information to distinguish if a connection problem is down to an authentication issue.

KCBC-118: Accessing the result of a sub-document lookupIn exists command now throws an appropriate exception (instead of returning false) in more cases where it’s not possible to determine whether the field exists:

JVMCBC-1252: Orphaned "observe" operations will no longer occasionally contain a total_duration_us field equal to 0.

JVMCBC-1255: If you were subscribing to the event bus and printing all the events, you may have noticed Event.toString() throwing a NullPointerException if the event context is null. Event.toString() now handles null contexts more gracefully, and no longer throws this exception.

JVMCBC-1237: Added "network" as an alias for the "io.networkResolution" connection string parameter. For example, the connection string "couchbase://example.com?network=external" is now equivalent to "couchbase://example.com?io.networkResolution=external". This was done for compatibility with other Couchbase SDKs that use "network" as the name of this parameter.

JVMCBC-1232: Cluster.connect() now rejects connection strings that have no addresses (like "couchbase://"). Before this change, it would accept the invalid connection string, and subsequent operations would fail with a misleading error message: "The cluster does not support cluster-level queries".

JVMCBC-1181: It is now possible to authenticate over secure connections even if the JVM does not support the SASL PLAIN authentication mechanism.

JVMCBC-1184: Updated dependencies.

JVMCBC-1160: When a sub-document path has a syntax error or is inappropriate for an operation, the SDK now throws PathInvalidException. Prior to this change, it would throw a generic CouchbaseException with the message "Unexpected SubDocument response code".

JVMCBC-1175: The SDK now includes native libraries for IO and TLS that can enhance performance on aarch_64 architectures like Graviton and Apple Silicon. Previously, native libraries were included only for x86_64 architectures. Native libraries for IO and TLS are enabled by default. If you need to disable native IO, set the ioEnvironment.enableNativeIo client setting to false. To disable native TLS, set the security.enableNativeTls client setting to false.

JVMCBC-1161: Fixed a minor issue where cluster.disconnect() could occasionally time out due to a race condition.

JVMCBC-1176: Setting security.enableNativeTls to false now prevents the SDK from even attempting to load the native TLS library. (Prior to this change, the SDK would load the library and just not use it.) In addition to saving a bit of memory, this prevents the JVM from segfaulting on Alpine Linux where glibc is not available.

JVMCBC-1174: Fixed a regression that prevented native TLS from being used regardless of whether the security.enableNativeTls client setting was set to true.

JVMCBC-1163: Dependencies have been updated.

JVMCBC-1156: The traffic tracing functionality has been enhanced to perform Wireshark-style dissection of portions of the KV protocol.

JCBC-2021: Diagnostics for an endpoint now include the state of the endpoint’s circuit breaker.

KCBC-107: The logging configuration DSL property enableDiagnosticContext is now mutable.

JVMCBC-1157: The SDK no longer rejects a PersistTo requirement in a bucket using the Magma storage engine. Before this change, the SDK would refuse the request because it misidentified Magma buckets as ephemeral (unable to persist documents).

JVMCBC-1167: If you call CancellationErrorContext.getWaitUntilReadyContext() on an error context that didn’t come from a "wait until ready" request, the method is now guaranteed to return null instead of sometimes throwing a ClassCastException.

JVMCBC-1178: Fixed a memory leak in ManagerMessageHandler.

JVMCBC-1102: Added support for serverless execution environments including AWS Lambda.

KCBC-101: Added an experimental JSON serializer backed by kotlinx.serialization. See this sample code for usage and caveats.

KCBC-102: Added support for configuration profiles, which allow you to quickly configure an environment for common use-cases. In particular, this makes it easy to apply timeouts appropriate for WAN (Internet) development, such as developing against a remote Couchbase Capella instance. Example usage:

val cluster = Cluster.connect(
    connectionString, username, password
) {
    applyProfile("wan-development")
}

KCBC-105, JVMCBC-1144: If your Couchbase Server cluster’s root certificate is signed by a well-known certificate authority whose certificate is included in the JVM’s trust store, it’s no longer necessary to configure the certificate in the securityConfig settings.

KCBC-104: Changed AuthenticationFailureException error message to indicate that bucket hibernation is now a potential cause. Bucket hibernation is a feature coming in a future Couchbase release.

JVMCBC-1154: Bumped dependencies.

JVMCBC-1141: Provide required OpenTelemetry span attributes.

JVMCBC-1155: Make sure targeted round-robin request keeps retrying if no config is available.

KCBC-94: UserManager has a new changePassword function that lets you change the password of the currently authenticated user.

KCBC-99: Bucket has a new collections property of type CollectionManager. You can use the collection manager to create and delete scopes and collections. (Requires Couchbase Server 7.0 or later.)

KCBC-100: Added two new global config properties to help diagnose leaked Cluster instances. Cluster.maxAllowedInstances is the number of connected Cluster instances that may exist at the same time. Calling Cluster.connect after this limit is reached will either fail or log a warning, depending on the value of the new Cluster.failIfInstanceLimitReached property. The default values log a warning if more than 1 Cluster is connected at a time.

JVMCBC-1134: Updated MemcachedProtocol::decodeStatus to be inlineable.

JVMCBC-1135: Moved Core#reconfiguration off IO threads.

JVMCBC-1143: Failed telemetry spans will now record their exception and error status.

JVMCBC-1145: Updated maintenance dependencies.

JVMCBC-1116: Dependency versions have been increased.

JVMCBC-1119: The num (kv) nodesExt to equal number of nodes check can lead to otherwise healthy clusters being flagged as not ready. The check has been removed, and now bucket.waitUntilReady will not time out on these edge cases.

JVMCBC-1120: ClusterConfig#allNodeAddresses now takes global config into account — avoiding the triggering of some unnecessary reconfigurations.

JVMCBC-1112: Deprecated Reactor Processors have been replaced.

JVMCBC-1115: The SDK now allows for configurations with only TLS ports.

JVMCBC-1103: To reduce overhead, the MAX_PARALLEL_FETCH value in KeyValueBucketRefresher has been updated to only fetch one config per poll interval.

JVMCBC-1104: Fixed issue where the global refresher did not honor the config poll interval.

KCBC-79: JacksonJsonSerializer now accepts the jackson ObjectMapper which for example makes it easier to use out of the box with Spring Boot.

JVMCBC-1093: Previously, when a DNS SRV lookup failure occurred, the SDK logged this as a WARNING along with a stack trace. The lookup failure is typically harmless, so the log message has now been downgraded to INFO level, without a stack trace.

JVMCBC-1088: Updated Netty to version 4.1.77.Final.