Cluster Transaction - Overview

Open a cluster transaction

  • To work with a cluster transaction open a cluster-wide session,
    by explicitly setting the transactionMode to ClusterWide.

const session = store.openSession({
    // Set mode to be cluster-wide
    transactionMode: "ClusterWide"

    // Session will be single-node when either:
    //   * Mode is not specified
    //   * Explicitly set to SingleNode
  • Similar to the single-node session,
    any CRUD operations can be made on the cluster-wide session and the session will track them as usual.

Cluster-wide transaction vs. Single-node transaction


  • Cluster-wide transactions are fully ACID transactions across all the database-group nodes.
    Implemented by the Raft algorithm, the cluster must first reach a consensus.
    Once the majority of the nodes have approved the transaction,
    the transaction is registered for execution in the transaction queue of all nodes in an atomic fashion.

  • The transaction will either succeed on all nodes or be rolled-back.
    • The transaction is considered successful only when successfully registered on all the database-group nodes. Once executed on all nodes, the data is consistent and available on all nodes.
    • A failure to register the transaction on any node will cause the transaction to roll-back on all nodes and changes will Not be applied.

  • The only actions available are:
    • PUT / DELETE a document
    • PUT / DELETE a compare-exchange item

  • To prevent from concurrent documents modifications,
    the server creates Atomic-Guards that will be associated with the documents.
    An Atomic-Guard will be created when:
    • A new document is created
    • Modifying an existing document that doesn't have yet an Atomic-Guard

  • Cluster-wide transactions are conflict-free.

  • The cluster-wide transaction is considered more expensive and less performant
    since a cluster consensus is required prior to execution.

  • Prefer a cluster-wide transaction when:
    • Prioritizing consistency over performance & availability
    • When you would rather fail if a successful operation on all nodes cannot be ensured


  • A single-node transaction is considered successful once executed successfully on the node the client is communicating with. The data is immediately available on that node, and it will be eventually-consistent across all the other database nodes when the replication process takes place soon after.

  • Any action is available except for PUT / DELETE a compare-exchange item.
    No Atomic-Guards are created by the server.

  • Conflicts may occur when two concurrent transactions modify the same document on different nodes at the same time. They are resolved according to the defined conflict settings, either by using the latest version (default) or by following a conflict resolution script.
    Revisions are created for the conflicting documents so that any document can be recovered.

  • The single-node transaction is considered faster and less expensive,
    as no cluster consensus is required for its execution.

  • Prefer a single-node transaction when:
    • Prioritizing performance & availability over consistency
    • When immediate data persistence is crucial
    • When you must ensure data is written even when other nodes are not reachable at the moment
    • And - when resolving occasional conflicts is acceptable

Transactions in RavenDB

For a detailed description of transactions in RavenDB please refer to the Transaction support in RavenDB article.