Distributed Transactions from the C++ SDK

Couchbase transactions require no additional components or services to be configured. Simply add the transactions library into your project. The latest version, as of 19 April 2021, is 1.0.0.

The starting point is the transactions object. It is very important that the application ensures that only one of these is created, as it performs automated background processes that should not be duplicated.

Transactions can optionally be configured at the point of creating the transactions object:

The default configuration will perform all writes with the durability setting Majority, ensuring that each write is available in-memory on the majority of replicas before the transaction continues. There are two higher durability settings available that will additionally wait for all mutations to be written to physical storage on either the active or the majority of replicas, before continuing. This further increases safety, at a cost of additional latency.

A level of None is present but its use is discouraged and unsupported. If durability is set to None, then ACID semantics are not guaranteed.

A core idea of Couchbase transactions is that an application supplies the logic for the transaction inside a lambda, including any conditional logic required, and the transaction is then automatically committed. If a transient error occurs, such as a temporary conflict with another transaction, then the transaction will rollback what has been done so far and run the lambda again. The application does have to do these retries and error handling itself.

Each run of the lambda is called an attempt, inside an overall transaction.

The lambda gets passed a attempt_context object, generally referred to as ctx here.

A code example is worth a thousand words, so here is a quick summary of the main transaction operations. They are described in more detail below.

While this document is focussed on presenting how transactions are used at the API level, it is useful to have a high-level understanding of the mechanics. Reading this section is completely optional.

Recall that the application-provided lambda (containing the transaction logic) may be run multiple times by Couchbase transactions. Each such run is called an attempt inside the overall transaction.

There are two ways to get a document, get and getOptional:

get will cause the transaction to fail with transaction_failed (after rolling back any changes, of course). It is provided as a convenience method so the developer does not have to check the optional if the document must exist for the transaction to succeed.

Gets will 'read your own writes', e.g. this will succeed:

Committing is automatic: if there is no explicit call to ctx.commit() at the end of the transaction logic callback, and no exception is thrown, it will be committed.

As soon as the transaction is committed, all its changes will be atomically visible to reads from other transactions. The changes will also be committed (or "unstaged") so they are visible to non-transactional actors, in an eventually consistent fashion.

Commit is final: after the transaction is committed, it cannot be rolled back, and no further operations are allowed on it.

An asynchronous cleanup process ensures that once the transaction reaches the commit point, it will be fully committed - even if the application crashes.

The cluster, bucket, collection, and transactions objects all are safe to use across multiple threads. When creating the cluster, you can specify the maximum number of libcouchbase instances the cluster and bucket can use. Transactions currently only using KV operations from the bucket. Specifying max_bucket_instances in the cluster_options when creating the cluster is sufficient. This will be the maximum number of concurrent transaction operations which can be made:

The example below allows for up to 10 instances to be created, then has 10 threads get and replace the content in a document:

Let’s pull together everything so far into a more real-world example of a transaction.

This example simulates a simple Massively Multiplayer Online game, and includes documents representing:

In this example, the player is dealing damage to the monster. The player’s client has sent this instruction to a central server, where we’re going to record that action. We’re going to do this in a transaction, as we don’t want a situation where the monster is killed, but we fail to update the player’s document with the earned experience.

(Though this is just a demo - in reality, the game would likely live with the small risk and limited impact of this, rather than pay the performance cost for using a transaction.)

A complete version of this example is available on our GitHub transactions examples page.

This release of transactions for Couchbase requires a degree of co-operation from the application. Specifically, the application should ensure that non-transactional writes (such as key-value writes or N1QL UPDATES) are never done concurrently with transactional writes, on the same document.

This requirement is to ensure that the strong Key-Value performance of Couchbase was not compromised. A key philosophy of our transactions is that you 'pay only for what you use'.

If two such writes do conflict then the transactional write will 'win', overwriting the non-transactional write.

Note this only applies to writes. Any non-transactional reads concurrent with transactions are fine, and are at a Read Committed level.

If an exception is thrown, either by the application from the lambda, or by the transactions library, then that attempt is rolled back. The transaction logic may or may not be retried, depending on the exception.

If the transaction is not retried then it will throw a transaction_failed exception, and its cause method can be used for more details on the failure. The application can use this to signal why it triggered a rollback.

The transaction can also be explicitly rolled back:

In this case, if ctx.rollback() is reached, then the transaction will be regarded as successfully rolled back and no TransactionFailed will be thrown.

After a transaction is rolled back, it cannot be committed, no further operations are allowed on it, and the library will not try to automatically commit it at the end of the code block.

As discussed previously, Couchbase transactions will attempt to resolve many errors for you, through a combination of retrying individual operations and the application’s lambda. This includes some transient server errors, and conflicts with other transactions.

But there are situations that cannot be resolved, and total failure is indicated to the application via errors. These errors include:

Transactions, as they are multi-stage and multi-document, also have a concept of partial success or failure. This is signalled to the application through the transaction_result.unstaging_complete attribute, described later.

There are three exceptions that Couchbase transactions can return to the application: transaction_failed, transaction_expired and transaction_commit_ambiguous. All exceptions derive from transaction_exception for backwards-compatibility purposes.

Transactions will try to clean up after themselves in the advent of failures. However, there are situations that inevitably created failed, or 'lost' transactions, such as an application crash.

This requires an asynchronous cleanup task, described in this section.

Creating the Transactions object spawns a background cleanup task, whose job it is to periodically scan for expired transactions and clean them up. It does this by scanning a subset of the Active Transaction Record (ATR) transaction metadata documents, on each bucket. As you’ll recall from earlier, an entry for each transaction attempt exists in one of these documents. They are removed during cleanup or at some time after successful completion.

The default settings are tuned to find expired transactions reasonably quickly, while creating negligible impact from the background reads required by the scanning process. To be exact, with default settings it will generally find expired transactions within 60 seconds, and use less than 20 reads per second. This is unlikely to impact performance on any cluster, but the settings may be tuned as desired.

All applications connected to the same cluster and running transactions will share in the cleanup, via a low-touch communication protocol on the "_txn:client-record" metadata document that will be created in each bucket in the cluster. This document is visible and should not be modified externally as it is maintained automatically. All ATRs on a bucket will be distributed between all cleanup clients, so increasing the number of applications will not increase the reads required for scanning.

An application may cleanup transactions created by another application.

It is important to understand that if an application is not running, then cleanup is not running. This is particularly relevant to developers running unit tests or similar.

If this is an issue, then the deployment may want to consider running a simple application at all times that just opens a transaction, to guarantee that cleanup is running.

To aid troubleshooting, the transactions library logs information to stdout. The default logging level is INFO, but can be changed to produce more or less detailed output. For instance, to see very detailed logging: