Couchbase Distributed ACID Transactions for Java SDK Release Notes

Couchbase Distributed ACID Transactions is distributed as a separate library for the Java SDK. This page features the release notes for that library — for release notes, download links, and installation methods for the latest 3.x Java SDK releases, see the current Release Notes page.

Using Distributed Transactions

See the Distributed ACID Transactions concept doc in the server documentation for details of how Couchbase implements transactions. The Distributed Transactions HOWTO doc walks you through all aspects of working with Distributed Transactions.

Distributed Transactions Java 1.0.0 (17th January 2020)

This is the first General Availability (GA) release of Distributed ACID Transactions 1.0.0 for Couchbase Server 6.5.

Built on Couchbase java-client version 3.0.0 (GA). Requires Couchbase Server 6.5 or above.

Bug Fixes & Stability

  • TXNJ-119: Calling commit multiple times leads to an error mentioning "rollback"; changed to separate error messages for commit and rollback.

  • TXNJ-126: Expire a transaction immediately if it expires while deferred.

  • TXNJ-149: Improve ambiguous error handling during commit.

  • TXNJ-163, TXNJ-156: Ensure that java-client errors are correctly handled after its changes to error handling.

  • TXNJ-165: Fix reactor.core.Exceptions$OverflowException seen during cleanup. Would only affect users setting a cleanup window of 1 second or less.


  • TXNJ-173: Register for changes to bucket configurations, so if the application opens a bucket after creating Transactions object, background cleanup will be started on those new buckets.

  • TXNJ-69: Provide some future proofing for client-record. Implementation detail, allows for future extensibility of the background cleanup process.

  • TXNJ-111, TXNJ-110: Sends new events to the java-client event-bus with details from the background cleanup process.

  • TXNJ-120: Once Transactions object is closed, prevent futher operations on it as a sanity check.

  • TXNJ-151: Add Java client metadata to help track failures. Implementation detail, adds some additional info to exceptions to help debugging.

  • TXNJ-152: When transaction expires, attempt to roll it back (or complete commit). Completes the work in TXNJ-124 (in 1.0.0-beta.3), to cover all cases.

  • TXNJ-155: Remove OpenTracing dependency. An implementation detail as it has already been removed from the API, this completes the work and removes the dependency on the jar. Once OpenTelemetry (OpenTracing’s direct replacement) is stable, support for it will be added.

  • TXNJ-162: Performance improvements related to String parsing. Internal benchmarking sees a huge reduction in memory allocations and GC pressure with this change.

  • TXNJ-167: Rebuild on java-client 3.0.0 GA.

  • TXNJ-170: Perform ATR cleanup in serial, which prevents errors being sent to Hooks.onErrorDropped (and by default stdout) when shutting down transactions. Along with java-client fix JVMCBC-781, users should no longer see Hooks.onErrorDropped errors.

API changes

  • TXNJ-171: Rename MAJORITY_AND_PERSIST_ON_MASTER to MAJORITY_AND_PERSIST_ON_ACTIVE, in accordance with new naming conventions.

  • TXNJ-169: Simplify cleanup window logic to remove divide-by-2; previously, specifying TransactionConfigBuilder.cleanupWindow(120 seconds) would lead to ATRs getting checked every 60 seconds (in the general case): now to reduce confusion they will be checked every 120 seconds.

  • TXNJ-164: Remove TransactionConfigBuilder.logDirectlyCleanup. As all cleanup trace is now sent directly to java-client’s event-bus, it can be configured from there and this parameter is useless.

Distributed Transactions Java 1.0.0-beta.3 (13th November 2019)

This is the third Beta release of Distributed ACID Transactions 1.0.0 for Couchbase Server 6.5 and the Java 3.0.0 client. There are no major changes. The main purpose of the release is to rebuild on top of the beta.1 release of the java-client, so applications can use both together.

Built on Couchbase java-client version 3.0.0-beta.1. Requires Couchbase Server 6.5 or above.

Bug-fixes And Stability

  • TXNJ-127: Fixes an ArrayIndexOutOfBoundsException error when using the reactive API to perform concurrency inside a txn.

  • TXNJ-145: ATR names are changed, to hash to their expected vbucket. It is recommended to flush (remove all documents from) the bucket to remove ATR documents from previous releases.

  • TXNJ-136: Fixes an erroneous IllegalDocumentState alert in edge-cases involving the DurabilityAmbiguous error.

New Features and Enhancements

  • TXNJ-124: An aborting transaction will now attempt rollback before completing raising TransactionExpired failure, rather than leaving cleanup solely to cleanup process.

  • TXNJ-131: Minor logging improvement.

Distributed Transactions Java 1.0.0-beta.2 (9th September 2019)

This is the second Beta release of Distributed ACID Transactions 1.0.0 for Couchbase Server 6.5 and the Java 3.0.0 client.

Built on Couchbase java-client version 3.0.0-alpha.7. Requires Couchbase Server 6.5 beta or above.

Bug-fixes and stability

  • JVMCBC-728: This fix in the underlying Couchbase java-client prevented conflict detection from working correctly in all situations with durability enabled (which it is, by default). All users are strongly recommended to upgrade as soon as possible, for this fix.

Breaking changes

As a rule, we do not make breaking API changes after GA release, and only consider them rarely during the beta period. This particular breaking change aligns the transaction and Java libraries much better, makes for a more natural and usable API, and requires little porting work.

  • TXNJ-121: Align with the Couchbase Java client, by renaming the get method to getOptional, getOrError to get, and TransactionJsonDocument to TransactionGetResult.


  • TXNJ-40: Retry operations on many transient errors, rather than retrying the full transaction.

New features

  • TXNJ-85: (Experimental) Supported deferred commit for transactions. Please see the documentation for details. This feature should be regarded as alpha, as its API and functionality may change in the future; please feel free to try it out and provide feedback.

  • TXNJ-112: (Experimental) Allow the number of ATRs to be configured. This can potentially be used to improve transactions throughput, but is currently experimental and should be used only with Couchbase’s guidance.

  • TXNJ-107: Make txn metadata documents more consistently named by prefacing them with "_txn:"

Distributed Transactions Java 1.0.0-beta.1

This is the first Beta release of Distributed ACID Transactions 1.0.0 for Couchbase Server 6.5 and the Java 3.0.0 client.

Built on Couchbase java-client version 3.0.0-alpha.6. Requires Couchbase Server 6.5 beta or above.

New features

Bug-fixes and stability

  • TXNJ-47: Improved handling for expiry — the transaction will now try to enter Aborted state

  • TXNJ-50: Intermittent reactive asserts about blocking on a thread from the "parallel" scheduler

  • TXNJ-55: Retry transient errors while rolling back ATR entry, rather than retrying transaction

  • TXNJ-57: Add log redaction for document keys

  • TXNJ-59: Fix an issue with the lost cleanup thread aborting early

  • TXNJ-64: Commit documents in the order they were staged

  • TXNJ-79, TXNJ-81: Improved handling of transient server errors while trying to create ATR entries

  • TXNJ-90: Improved handling of conflicts when multiple applications start at once and try to create the client record

  • TXNJ-96: Improved handling of transient errors removing entries from the client record

Deprecations and removals

  • TXNJ-92: OpenTracing removed from API — will be re-added when OpenTelemetry is ready