SDK Release Notes

      Release notes for the Couchbase Kotlin Client.

      Kotlin SDK 1.2 Releases

      We always recommend using the latest version of the SDK — it contains all of the latest security patches and support for new and upcoming features. All patch releases for each dot minor release should be API compatible, and safe to upgrade; any changes to expected behavior are noted in the release notes that follow.

      Version 1.2.0 (21 November 2023)

      The SDK now supports the new couchbase2 protocol, which is upcoming in future Couchbase Server versions. It can be enabled through using a connection string starting with couchbase2://. Please see Cloud Native Gateway for more information.

      The SDK now directly depends on SLF4J, which may impact some users — see below for details.

      API Impacting

      When upgrading from a previous version of the SDK, please be aware of this behavioral change:

      JVMCBC-1319: As previously announced, the SLF4J API is now a required dependency, and the SDK does all logging through SLF4J. The following client settings for customizing logging behavior are deprecated, and no longer have any effect:

      • logger.disableSlf4J

      • logger.fallbackToConsole

      • logger.consoleLoggerFormatter

      If your project does not already use SLF4J, please follow the announcement link for details and a mini-migration guide.


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

        CollectionManager has a new updateCollection method for changing the settings of an existing collection. Note that updating a collection’s maxExpiry setting requires Couchbase Server 7.6.

      • 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.

      Kotlin SDK 1.1 Releases

      Version 1.1.11 (4 October 2023)

      This is a regular maintenance release.


      • 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.

      Version 1.1.10 (6 September 2023)


      • JVMCBC-1367: The db.couchbase.operations metric now has (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 that could occur during rebalance.

      Version 1.1.9 (2 August 2023)


      • 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.

      Version 1.1.8 (19 July 2023)


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

      Version 1.1.7 (12 June 2023)

      This release refines the sub-document counter methods, and adds a new connection string parameter for disabling TLS certificate verification.


      • 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.

      Version 1.1.6 (4 May 2023)

      This is a regular maintenance release, with no notable changes apart from depedency version bumps.

      Version 1.1.5 (12 April 2023)

      This is a regular maintenance release.


      • 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.

      Bug Fixes

      • 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:

        • If the document is not JSON, DocumentNotJsonException is thrown.

        • If a user without the SystemXattrRead permission attempts to check the existence of a system XATTR, XattrNoAccessException is thrown.

      • 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.

      Version 1.1.4 (8 March 2023)

      This is a regular maintenance release.


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

      Bug Fixes

      • 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".

      Version 1.1.3 (9 February 2023)

      This is a regular maintenance release.


      • 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.

      Bug Fixes

      • 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".

      Version 1.1.2 (16 January 2023)

      This is a regular maintenance release.


      • 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.

      Bug Fixes

      • 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.

      Version 1.1.1 (7 December 2022)


      • 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.

      Bug Fixes

      • 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.

      Version 1.1.0 (24 October 2022)


      • 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
        ) {
      • 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.

      Bug Fixes

      • JVMCBC-1141: Provide required OpenTelemetry span attributes.

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

      Kotlin SDK 1.0 Releases

      Version 1.0.4 (9 September 2022)

      This maintenance release adds more cluster management APIs, and updates dependency versions.


      • 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.

      Version 1.0.3 (2 August 2022)

      Maintenance release.


      • JVMCBC-1116: Dependency versions have been increased.

      Bug Fixes

      • 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.

      Version 1.0.2 (6 July 2022)

      Maintenance release.

      Bug Fixes

      • 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.

      Version 1.0.1 (8 June 2022)

      Maintenance release.


      • 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.

      Version 1.0.0 (3 May 2022)

      Initial GA release.