Cluster Transaction - Overview
-
A session represents a single business transaction (not to be confused with an ACID transaction).
-
When opening a session, the session's mode can be set to either:
- Single-Node - transaction is executed on a specific node and then replicated
- Cluster-Wide - transaction is registered for execution on all nodes in an atomic fashion
-
In this page:
Open a cluster transaction
- To work with a cluster transaction open a cluster-wide session,
by explicitly setting theTransactionMode
toTransactionMode.clusterWide
.
$sessionOptions = new SessionOptions();
// Set mode to be cluster-wide
$sessionOptions->setTransactionMode(TransactionMode::clusterWide());
// Session will be single-node when either:
// * Mode is not specified
// * Explicitly set TransactionMode.SingleNode
$session = $store->openSession($sessionOptions);
try {
//
} finally {
$session->close();
}
- 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
- 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
Single-Node
- 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.