Distributed ACID Transactions

    Transactions guarantee that multiple documents can be updated atomically.

    Couchbase provides Distributed ACID Transactions for K-V (data) and Query operations — these are available through APIs in C++, .NET, and Java.

    Understanding Transactions

    Distributed ACID Transactions are operations that ensure that when multiple documents need to be modified such that only the successful modification of all justifies the modification of any, either all the modifications do occur successfully; or none of them occurs. This Atomicity supports insert, update, and delete operations, across any number of documents. It also enables seamless integration between KV and Query operations within transactions.

    Only following commit of the documents modified by the transaction — when the modified data-copy is removed from the meta data area (which uses Extended Attributes), and is written over the main body of the document’s data — do the corresponding changes become readable by other transactions and operations. This is Read Committed isolation.

    A transaction can be performed across multiple buckets. Only nodes that contain data to be updated are affected by a transaction.

    Multiple transactions can read the same document at the same time. If two transactions simultaneously attempt to write to the same document, one is allowed to proceed, while the other is obliged to retry.

    Use of transactions requires Network Time Protocol (NTP) to be used to synchronize time across all cluster-nodes. See Clock Sync with NTP, for details.

    Services and Transactions

    The indexes provided by the Index, Search, and Analytics Services are not atomically updated with the commits performed by transactions: however, they are updated with Eventual Consistency.

    Neither the Query Service nor the Search Service sees uncommitted data. However, Snapshot Isolation is not provided: consequently, if a transaction performs a commit while a query or search is ongoing, then the query or search may return data from both prior to and subsequent to the commit.

    Unresolved include directive in modules/ROOT/pages/distributed-acid-transactions.adoc - include::java-sdk:howtos:distributed-acid-transactions-from-the-sdk.adoc[]


    Couchbase Distributed ACID Transactions currently have the following limitations:

    • Only documents whose initial size is 10 MB or less can be included in a transaction.

    • Non-transactional updates should not be made to any document involved in a transaction while the transaction is itself in progress: this prevents the non-transactional update from being overwritten.

    • The number of writes required by a transactional update is greater than the number required for a non-transactional update. Thus transactional updates may be less performant than non-transactional updates.

      Note that data within a single document is always updated atomically (without the need for transactions): therefore, whenever multiple key-value pairs consistently require atomic update, their co-location within a single document may best ensure high performance.

    • Cross Data Center Replication (XDCR) supports eventual consistency: however, it does not support atomicity — nor does XDCR Conflict Resolution. Consequently, transactionally modified documents should only be replicated across clusters if no transactions involving the same documents can occur on those clusters simultaneously. In other words, Active-Active XDCR deployment (that is, where both clusters are being written to simultaneously) is not supported with the use of transactions and can lead to unexpected behavior and data loss.

      See XDCR Direction and Topology, for a description of bidirectional XDCR. See Ensuring Safe Failover, for information on failing a transactional application from one data center to another.

    • Since transactions make use of the Durability provided by synchronous writes, in order to use transactions in development on a single-node cluster, the number of replicas assigned to any bucket to be used transactionally must be established as zero: if the number is greater than zero, the required durability level is unattainable, and the write fails.

      If using a single node cluster (for example, during development), then note that the default number of replicas for a newly created bucket is 1. If left at this default, then all Key-Value writes performed at with durability will fail with a DurabilityImpossibleException. In turn this will cause all transactions (which perform all Key-Value writes durably) to fail. This setting can be changed via GUI or command line.
    • A Transactional N1QL Query using AT_PLUS will be automatically upgraded to REQUEST_PLUS.

    Additional Storage Use

    Transactions make use of the Durability provided by synchronous writes. As well as making use of individual documents' extended attributes, transactions also create additional documents in each bucket that they access. These include:

    • Active Transaction Records. Multiple Active Transaction Records can exist per bucket. Each of these documents can contain entries for multiple transactions. Collectively, these documents record all currently active transactions for the bucket. The name of each document is prefixed with _txn:atr-.

    • Transaction Client Records. One of these exists per bucket, covering all clients currently accessing the bucket transactionally. The document is named _txn:client-record.

    These documents, which may persist indefinitely, are automatically maintained by Couchbase Server, and should not be modified by any application.

    Creating and Using Transactions

    For examples of creating and using transactions on Couchbase Server, see:

    SDK Transactions Version 1.0.x do not support N1QL operations, but can be used with Couchbase Server 6.6. SDK Transactions Version 1.1.x require at least Server 7.0, and will work with N1QL operations.

    It is also possible to create and use transactions using the N1QL query language. Refer to the N1QL Language Reference for further details.