SDK Release Notes

KCBC-190: New APIs added to allow getting KV documents from a preferred server group. This feature allows the implementation of network optimization when traffic cost between server groups is higher than in the local group. In this case the application might select preferred server group in the connection options, and later opt-in for local operations during replica reads.

KCBC-189: KotlinxSerializationJsonSerializer is now part of the SDK’s stable API, with full support for nullable types and contextual serializers.

JVMCBC-1602: Application Telemetry improvements.

KCBC-187: The bucket management API now supports specifying the number of VBuckets for a Magma bucket (requires Couchbase Server 8.0 or later).

KCBC-184: Added transaction methods getMulti and getMultiReplicasFromPreferredServerGroup for getting a batch of documents with minimal read skew.

JVMCBC-1616 Upgraded Netty from 4.1.15 to 4.1.118.

KCBC-163: When using Couchbase Server 7.6.2 or later, you can now specify a “preferred server group” for replica reads. To use this feature, configure the cluster environment with a preferredServerGroup name. The following Collection methods now have an optional readPreference parameter:

KCBC-178: CouchbaseHttpClient can now send PATCH requests.

KCBC-180: The experimental KotlinxSerializationJsonSerilaizer can now serialize and deserialize documents, query parameters, and query result rows that have a JSON null at the root.

KCBC-179: Deprecated the existing methods for specifying SQL++ query parameters, and added new methods that preserve parameter type information required by some JsonSerializer implementations. This will be increasingly important as we add better support for kotlinx.serialization in the future.

// DEPRECATED
parameters = QueryParameters.named(
    "name" to "Fido",
    "data" to MyDataClass(),
)

// REPLACEMENT
parameters = QueryParameters.named {
    param("name", "Fido")
    param("data", MyDataClass())
}

// DEPRECATED
parameters = QueryParameters.positional(
    listOf(
        "Fido",
        MyDataClass(),
    )
)

// REPLACEMENT
parameters = QueryParameters.positional {
    param("Fido")
    param(MyDataClass())
}

JVMCBC-1592: When fetching fresh cluster topology information for a bucket, the SDK now dispatches the request to a random eligible node instead of using a round-robin algorithm. Randomizing the node selection avoids a pathological condition where if the number of open buckets is equal to the number of nodes, and one of the nodes is degraded, the config refresh attempt for a particular bucket would fail repeatedly because it was always sent to the degraded node.

JVMCBC-1583: Fixed a race condition that could cause the SDK to continuously attempt to reconnect to a node, even after the node is rebalanced out of the cluster.

JVMCBC-1560: Added cluster UUID and name to metrics and spans.

JVMCBC-1582: Upgraded Netty from 4.1.112 to 4.1.115.

JVMCBC-1572: Due to a regression in Kotlin SDK 1.4.1, using a secure connection would cause waitUntilReady() to not wait, and would cause ping() to report failures even when nothing was wrong. The issue that caused these problems is now fixed.

JVMCBC-1577: Due to a regression in Kotlin SDK 1.4.1, sometimes a request made shortly after calling Cluster.connect() would fail with a message that said the service is not available in the cluster, even if the service was actually available. This no longer happens.

JVMCBC-1579: Deprecated com.couchbase.client.core.node.NodeIdentifier in favor of com.couchbase.client.core.topology.NodeIdentifier.

JVMCBC-1570: The SDK was producing an incorrect partition map in CouchbaseBucketConfig, for buckets with >= 2 replicas. This has now been fixed.

KCBC-96: Added experimental API for Couchbase transactions. This is a new Kotlin-flavored candy shell on the same Couchbase transactions engine used by the Java SDK.

JVMCBC-1564: Query index manager operation watchIndexes() now uses any provided parentSpan, and sets required span attributes.

JVMCBC-1562: Updated version dependencies:

JVMCBC-1297: When the SDK starts up, it now logs its actual Git commit hash instead of a ${buildNumber} placeholder.

JVMCBC-1547: Updated DnsJava to 3.6.0.

JVMCBC-1523: Upgraded org.iq80.snappy from 0.4 to 0.5.

JVMCBC-1532: Upgraded Jackson from 2.17.0 to 2.17.2.

JVMCBC-1544: SearchIndexManager.upsertIndex() now prevents vector indexes from being created on server versions before version 7.6.0, which do not support these index types.

KCBC-165: Adds support for base64-encoded vectors in VectorQuery.

JVMCBC-1508 Upgraded Netty dependency.

JVMCBC-1509 Upgraded Jackson dependency.

JVMCBC-1506 Reduced the rate at which messages appear in the server’s http_access.log when a user provides valid credentials but does not have permission to access the bucket.

JVMCBC-1512 Correctly adapt to server cluster topology changes when a service migrates from one port to another on the same host.

JVMCBC-1477 Reduced the rate at which messages appear in the server’s http_access.log when invalid credentials are provided resulting in 401 errors. Issues resulting in 403 errors will be handled in a future release.

JVMCBC-1499 Disabled DNS SRV caching. The SDK now responds quicker to DNS changes in dynamic environments like Kubernetes.

KCBC-145: Added support for vector search, a new feature in Couchbase Server 7.6. This API is currently at @Stability.Uncommitted level.

JVMCBC-1491: Added support for KV range scan, a new feature in Couchbase Server 7.6. The Collection.scanDocuments() and Collection.scanIds() methods are now part of the SDK’s committed public API.

JVMCBC-1493: Added support for Sub-Document read from replica, a new feature in Couchbase Server 7.6. The Collection.lookupInAnyReplica() and Collection.lookupInAllReplicas() methods are now part of the SDK’s committed public API.

KCBC-147: Scope.searchIndexes() is now part of the committed public API.

KCBC-157: UserManager.changePassword() is now part of the committed public API.

KCBC-158: SearchIndexManager is now part of the committed public API.

JVMCBC-1487: Upgraded reactor-core from 3.5.8 to 3.6.3.

JVMCBC-1488: Upgraded Jackson from 2.16.0 to 2.16.1.

JVMCBC-1489: Upgraded Netty from 4.1.101 to 4.1.107.

JVMCBC-1480: couchbase2: should do exponential backoff when BestEffortRetryStrategy is used.

JVMCBC-1494: If you specify min=1 for a Full-Text Search disjunction query, the SDK now always sends the value to the server. Previously, the SDK assumed 1 was the default value, and omitted the parameter in that case.

KCBC-146 Collection manager improvements:

JVMCBC-1460 couchbase2 now supports compressing data between the SDK and the server.

JVMCBC-1464 The metrics-opentelemetry package is now aligned with the same OpenTelemetry version as tracing-opentelemetry.

JVMCBC-1468 Cluster.connect now validates that connection strings using the couchbase2 scheme have exactly one host. (Previously, hosts after the first were silently ignored.).

JVMCBC-1470 Improved support for Full Text Search in couchbase2 mode.

JVMCBC-1472 couchbase2 errors will now include diagnostic information when CNG is running with the --debug flag.

JVMCBC-1475 Accessing the terms of a TermFacet result no longer throws NullPointerException if the target field is absent from all documents.

KCBC-141: Added new QueryMetadata.signatureBytes property. The value is a byte array containing the signature encoded as JSON (QueryMetadata.signature failed if the signature was not a JSON Object). Deprecated QueryMetadata.signature in favor of signatureBytes.

JVMCBC-1455: Fixed compatibility with couchbase2:// endpoints by upgrading internal GRPC dependency. All couchbase2 protocol users should upgrade to this release.

JVMCBC-1463: Fixed compatibility between couchbase2:// endpoints and the tracing-opentelemetry module.

JVMCBC-1435, JVMCBC-1436: Upgraded Netty and Jackson dependencies.

JVMCBC-1440: Adding DocumentNotLockedException supporting future Couchbase Server versions that will return an error code when unlocking a document that is not locked.

JVMCBC-1433: The SDK can now connect to Memcached buckets whose names contain the percent (%) character. (We’d like to take this opportunity to remind everyone that Memcached buckets are deprecated in favor of Ephemeral buckets.)

JVMCBC-1437: With Couchbase Server versions that support updating a collection’s max expiry, it’s now possible to clear the expiry by passing Duration.ZERO for the new value.

JVMCBC-1441: The SDK now handles an additional error case for IndexNotFoundException.

JVMCBC-1442: Fixed a dependency issue with tracing-opentelemetry module.

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.