Skip to content

RDoc-3766 Document OptimisticConcurrencyMode enum (None / Writes / WritesAndReads) #2390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
reebhub merged 2 commits into from
Apr 13, 2026
Merged

RDoc-3766 Document OptimisticConcurrencyMode enum (None / Writes / WritesAndReads) #2390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8809f9
RDoc-3766 Document OptimisticConcurrencyMode enum (None / Writes / Wr…
Danielle9897 Mar 30, 2026
9867eb1
RDoc-3766 fix links
Danielle9897 Apr 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 35 additions & 23 deletions docs/client-api/configuration/content/_conventions-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ import CodeBlock from '@theme/CodeBlock';
[MaxNumberOfRequestsPerSession](../../../client-api/configuration/conventions.mdx#maxnumberofrequestspersession)
[Modify serialization of property name](../../../client-api/configuration/conventions.mdx#modify-serialization-of-property-name)
[OperationStatusFetchMode](../../../client-api/configuration/conventions.mdx#operationstatusfetchmode)
[OptimisticConcurrencyMode](../../../client-api/configuration/conventions.mdx#optimisticconcurrencymode)
[PreserveDocumentPropertiesNotFoundOnModel](../../../client-api/configuration/conventions.mdx#preservedocumentpropertiesnotfoundonmodel)
[ReadBalanceBehavior](../../../client-api/configuration/conventions.mdx#readbalancebehavior)
[RequestTimeout](../../../client-api/configuration/conventions.mdx#requesttimeout)
Expand All @@ -54,7 +55,6 @@ import CodeBlock from '@theme/CodeBlock';
[UseHttpCompression](../../../client-api/configuration/conventions.mdx#usehttpcompression)
[UseHttpDecompression](../../../client-api/configuration/conventions.mdx#usehttpdecompression)
[HttpCompressionAlgorithm](../../../client-api/configuration/conventions.mdx#httpcompressionalgorithm)
[UseOptimisticConcurrency](../../../client-api/configuration/conventions.mdx#useoptimisticconcurrency)
[WaitForIndexesAfterSaveChangesTimeout](../../../client-api/configuration/conventions.mdx#waitforindexesaftersavechangestimeout)
[WaitForNonStaleResultsTimeout](../../../client-api/configuration/conventions.mdx#waitfornonstaleresultstimeout)
[WaitForReplicationAfterSaveChangesTimeout](../../../client-api/configuration/conventions.mdx#waitforreplicationaftersavechangestimeout)
Expand Down Expand Up @@ -913,6 +913,40 @@ public OperationStatusFetchMode OperationStatusFetchMode \{ get; set; \}
</TabItem>

</Admonition>

<Admonition type="note" title="">

#### OptimisticConcurrencyMode

* Use the `OptimisticConcurrencyMode` convention to set the default optimistic concurrency mode for ALL sessions opened under the document store.
Sessions that do not explicitly set `OptimisticConcurrencyMode` in their `SessionOptions` will inherit this value.

* Learn more about optimistic concurrency modes and how to configure them in [Configure optimistic concurrency](../../../client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx).

* DEFAULT: `OptimisticConcurrencyMode.None`

<TabItem>
```csharp
// Syntax:
public OptimisticConcurrencyMode OptimisticConcurrencyMode { get; set; }

// Available modes:
public enum OptimisticConcurrencyMode
{
None, // Default - no concurrency checks (Last Write Wins)
Writes, // Checks modified documents only
WritesAndReads // Checks all tracked documents (modified and not modified)
}
```
</TabItem>

<Admonition type="warning" title="">
The `UseOptimisticConcurrency` boolean convention is obsolete and will be removed in a future major version.
Use `OptimisticConcurrencyMode` instead.
</Admonition>

</Admonition>

<Admonition type="note" title="">

#### PreserveDocumentPropertiesNotFoundOnModel
Expand Down Expand Up @@ -1163,28 +1197,6 @@ public HttpCompressionAlgorithm HttpCompressionAlgorithm \{ get; set; \}

</Admonition>


<Admonition type="note" title="">

#### UseOptimisticConcurrency
* When setting the `UseOptimisticConcurrency` convention to `true`,
Optimistic Concurrency checks will be applied for all sessions opened from the Document Store.

* Learn more about Optimistic Concurrency and the various ways to enable it in the
[how to enable optimistic concurrency](../../../client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx)
article.

* DEFAULT: `false`

<TabItem value="UseOptimisticConcurrencySyntax" label="UseOptimisticConcurrencySyntax">
<CodeBlock language="csharp">
{`// Syntax:
public bool UseOptimisticConcurrency \{ get; set; \}
`}
</CodeBlock>
</TabItem>

</Admonition>
<Admonition type="note" title="">

#### WaitForIndexesAfterSaveChangesTimeout
Expand Down
70 changes: 38 additions & 32 deletions docs/client-api/session/cluster-transaction/content/_overview-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,16 @@ import CodeBlock from '@theme/CodeBlock';
* [Cluster-wide transaction vs. Single-node transaction](../../../../client-api/session/cluster-transaction/overview.mdx#cluster-wide-transaction-vs-single-node-transaction)

</Admonition>

## Open a cluster transaction

* To work with a cluster transaction open a **cluster-wide session**,
by explicitly setting the `TransactionMode` to `TransactionMode.ClusterWide`.

<Tabs groupId='languageSyntax'>
<TabItem value="Sync" label="Sync">
<CodeBlock language="csharp">
{`using (var session = store.OpenSession(new SessionOptions
```csharp">
using (var session = store.OpenSession(new SessionOptions
{
// Set mode to be cluster-wide
TransactionMode = TransactionMode.ClusterWide
Expand All @@ -34,12 +35,11 @@ import CodeBlock from '@theme/CodeBlock';
// * Mode is not specified
// * Explicitly set TransactionMode.SingleNode
}))
`}
</CodeBlock>
```
</TabItem>
<TabItem value="Async" label="Async">
<CodeBlock language="csharp">
{`using (var session = store.OpenAsyncSession(new SessionOptions
```csharp
using (var session = store.OpenAsyncSession(new SessionOptions
{
// Set mode to be cluster-wide
TransactionMode = TransactionMode.ClusterWide
Expand All @@ -48,56 +48,66 @@ import CodeBlock from '@theme/CodeBlock';
// * Mode is not specified
// * Explicitly set TransactionMode.SingleNode
}))
`}
</CodeBlock>
```
</TabItem>
</Tabs>

* 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

<Admonition type="note" title="">
#### Cluster-Wide
* Cluster-wide transactions are **fully ACID** transactions across all the database-group nodes.

### Cluster-Wide

* **ACID compliance**:
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,
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**.
* **All-or-nothing execution**:
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:
* **Available actions**:
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](../../../../compare-exchange/atomic-guards.mdx) that will be associated with the documents.
* **Conflict-free**:
Cluster-wide transactions are conflict-free. To prevent from concurrent documents modifications,
the server creates [Atomic-Guards](../../../../compare-exchange/atomic-guards.mdx) 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.
* **Performance**:
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

</Admonition>

<Admonition type="note" title="">
#### 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.

### Single-Node

* **Execution and availability**:
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.
* **Available actions**:
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.
* **Conflicts**:
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.
* **Optimistic concurrency**:
Single-node sessions support optional [Optimistic concurrency checks](../../../../client-api/session/configuration/how-to-enable-optimistic-concurrency.mdx).
By default, no checks are performed (Last Write Wins), but you can configure the session to detect and reject conflicting writes.
* **Performance**:
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
Expand All @@ -110,8 +120,4 @@ import CodeBlock from '@theme/CodeBlock';

For a detailed description of transactions in RavenDB please refer to the [Transaction support in RavenDB](../../../../client-api/faq/transaction-support.mdx) article.

</Admonition>




</Admonition>
Loading
Loading