Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Distributed Transactions Migration Guide

      +
      For those transitioning from using the Couchbase Transactions library for Java.

      Couchbase transactions for Java were originally introduced as a library separate from the Couchbase Java SDK.

      We subsequently chose to integrate transactions directly into the SDKs with the release of Java SDK 3.3.0, to make it easier for users to get started.

      This document details the small changes that existing users of the legacy transactions library need to make, to migrate to the SDK-integrated version.

      The legacy transactions library will continue to be supported with bugfixes for some time, but new transaction features will only be added to the SDK and it is recommended that all users migrate.

      Accessing transactions

      This is now done via a Cluster object. There is no longer any need to create a Transactions object.

      Before
      var transactions = Transactions.create(cluster);

transactions.run((ctx) -> {
    // Your transaction logic.
});
      After
      cluster.transactions().run((ctx) -> {
    // Your transaction logic.
});

      Configuration

      Configuration used to be performed when creating the Transactions object, and is now performed when creating the Cluster object.

      Before
      var transactions =
  Transactions.create(cluster,
    TransactionConfigBuilder.
      .durabilityLevel(TransactionDurabilityLevel.MAJORITY)
      .metadataCollection(collection));
      After
      var keyspace = TransactionKeyspace.create("bucketName", "scopeName", "collectionName");

var cluster = Cluster.connect("localhost", ClusterOptions.clusterOptions("username", "password")
        .environment(env -> env.transactionsConfig(TransactionsConfig
                .durabilityLevel(DurabilityLevel.PERSIST_TO_MAJORITY)
                .metadataCollection(keyspace))));

      A few details of configuration change:

      • TransactionsConfig::metadataCollection takes a TransactionKeyspace instead of a Collection (since a Collection cannot be created at this point).

      • keyValueTimeout has been removed from TransactionsConfig and TransactionOptions.

      • TransactionDurabilityLevel has been dropped in favour of using the SDK’s DurabilityLevel.

      • TransactionOptions now allows a metadataCollection parameter.

      And certain classes have been renamed to be compliant with the Java SDK:

      Before After

      TransactionConfigBuilder

      TransactionsConfig

      TransactionQueryConfigBuilder

      TransactionsQueryConfig

      SingleQueryTransactionConfigBuilder

      SingleQueryTransactionOptions

      PerTransactionConfigBuilder

      TransactionOptions

      Cleanup configuration

      Cleanup configuration options have been encapsulated into their own class:

      Before
      var transactions =
  Transactions.create(cluster,
    TransactionConfigBuilder.create()
      .cleanupClientAttempts(false)
      .cleanupLostAttempts(false)
      .cleanupWindow(Duration.ofSeconds(30)));
      After
      var cluster = Cluster.connect("localhost", ClusterOptions.clusterOptions("username", "password")
        .environment(env -> env.transactionsConfig(TransactionsConfig
                        .cleanupConfig(TransactionsCleanupConfig
                                .cleanupClientAttempts(true)
                                .cleanupLostAttempts(true)
                                .cleanupWindow(Duration.ofSeconds(30))))));

      Lambda

      ctx.commit() has been removed, as it is redundant: commit automatically happens when the lambda successfully reaches the end.

      ctx.rollback() has been removed, as it too is redundant: the application can throw any exception from the lambda to trigger a rollback.

      ctx.getOptional() has been replaced with ctx.get() throwing a DocumentExistsException. This may be caught, allowing the transaction to continue.

      Package changes

      All classes have changed packages to be compatible with the Java SDK conventions.

      The simplest way to convert many of the classes to their new locations is to search for import com.couchbase.transactions. and replace it with import com.couchbase.client.java.transactions..

      Some additional manual conversion after this may be required.

      Single query transactions

      These are now integrated with the existing SDK QueryOptions.

      Before
      SingleQueryTransactionResult sqr = transactions.query("INSERT...");
      After
      QueryResult qr = cluster.query("INSERT...", queryOptions().asTransaction());

      Or with configuration:

      Before
      SingleQueryTransactionResult sqr = transactions.query("INSERT...",
  SingleQueryTransactionConfigBuilder.create()
    .durabilityLevel(TransactionDurabilityLevel.MAJORITY));

QueryResult qr = sqr.queryResult();
      After
      QueryResult qr = cluster.query("INSERT...",
        queryOptions().asTransaction(
                singleQueryTransactionOptions()
                        .durabilityLevel(DurabilityLevel.MAJORITY)));

      Cleanup

      This doesn’t impact the API, but it is useful to know that lost cleanup has changed.

      Previously, lost cleanup would look for expired transactions on the default collections of all buckets in the cluster. Unless a metadata collection was specified, in which case only that collection would be cleaned up.

      Now, cleanup is dynamic. As transactions are run, the collection where metadata is created for that collection, is added to what we call the 'cleanup set'. This is just the set of collections where cleanup, for this application, is looking for expired transactions.

      The intent has always been that users without complex requirements should never need to think about or configure transaction cleanup, and this new dynamic cleanup allows us to be closer still to that goal.

      Naming

      All exceptions and events have been renamed to be compliant with the SDK. For example, TransactionFailed is now TransactionFailedException, and TransactionCleanupAttempt is now TransactionCleanupAttemptEvent.

      Logging

      TransactionFailedException now exposes the logs directly, rather than containing a nested TransactionResult.

      Before
      catch (TransactionFailedException err) {
    err.result().log().logs().forEach(msg -> logger.warning(msg.toString()));
}
      After
      catch (TransactionFailedException err) {
    err.logs().forEach(msg -> logger.warning(msg.toString()));
}

      Further Reading