---
title: "How to Enable Optimistic Concurrency"
url: "https://docs.ravendb.net/6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency"
version: "6.2"
language: "python"
---

# How to Enable Optimistic Concurrency

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.md), [Java](https://docs.ravendb.net/6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.java.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/configuration/how-to-enable-optimistic-concurrency.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - By default, optimistic concurrency checks are **disabled**. Changes made outside of the session object will be overwritten.
>   Concurrent changes to the same document will use the *Last Write Wins* strategy so a lost update anomaly is possible
>   with the default configuration of the [session](https://docs.ravendb.net/6.2/client-api/session/what-is-a-session-and-how-does-it-work.python.md).
>
> - Optimistic concurrency can be **enabled** for:
>   - A specific document
>   - A specific session (enable on a per-session basis)
>   - All sessions (enable globally, at the document store level)
>
> - With optimistic concurrency enabled, RavenDB will generate a concurrency exception (and abort all modifications in
>   the current transaction) when trying to save a document that has been modified on the server side after the client
>   loaded and modified it.
>
> - The `ConcurrencyException` that might be thrown upon the `save_changes` call needs to be handled by the caller.
>   The operation can be retried (the document needs to be reloaded since it got changed meanwhile) or handle the error
>   in a way that is suitable in a given scenario.
>
> - In this page:
>   - [Enable for specific session](#enable-for-specific-session)
>   - [Enable globally](#enable-globally)
>   - [Disable for specific document (when enabled on session)](#disable-for-specific-document-\(when-enabled-on-session\))
>   - [Enable for specific document (when disabled on session)](#enable-for-specific-document-\(when-disabled-on-session\))
>
> > **Warning**
> >
> > - Note that the `use_optimistic_concurrency` setting only applies to documents that have been modified by the current session.
> >   E.g., if you load documents `users/1-A` and `users/2-A` in a session, make modifications only to `users/1-A`, and then call `save_changes`,
> >   the operation will succeed regardless of the optimistic concurrency setting, even if `users/2-A` has been changed by another process in the meantime.
> >
> > - However, if you modify both documents and attempt to save changes with optimistic concurrency enabled, an exception will be raised
> >   if `users/2-A` has been modified externally.  
> >   In this case, the updates to both `users/1-A` and `users/2-A` will be cancelled.
>
> > **Info**
> >
> > A detailed description of transactions and concurrency control in RavenDB is available here:
> > [Transaction support in RavenDB](https://docs.ravendb.net/6.2/client-api/faq/transaction-support.md)

## Enable for specific session

```python
with store.open_session() as session:
  # Enable optimistic concurrency for this session
  session.advanced.use_optimistic_concurrency = True

  # Save a document in this session
  product = Product(name="Some name")
  session.store(product, "products/999")
  session.save_changes()

  # Modify the document 'externally' by another session
  with store.open_session() as other_session:
      other_product = other_session.load("products/999")
      other_product.name = "Other name"
      other_session.save_changes()

  # Trying to modify the document without reloading it first will throw
  product.name = "Better Name"
  session.save_changes()  # This will throw a ConcurrencyException

gion optimistic_concurrency_2
able for all sessions that will be opened within this document store
e.conventions.use_optimistic_concurrency = True
store.open_session() as session:
is_session_using_optimistic_concurrency = session.advanced.use_optimistic_concurrency  # will return True
```

> **Warning**
>
> - Enabling optimistic concurrency in a session will ensure that changes made to a document will only be persisted
>   if the version of the document sent in the `save_changes` call matches its version from the time it was initially read (loaded from the server).
>
> - Note that it's necessary to enable optimistic concurrency for ALL sessions that modify the documents for which you want to guarantee that no writes will be silently discarded.
>   If optimistic concurrency is enabled in some sessions but not in others, and they modify the same documents, the risk of the lost update anomaly still exists.

## Enable globally

- Optimistic concurrency can also be enabled for all sessions that are opened under a document store.

- Use the [store.conventions.use\_optimistic\_concurrency](https://docs.ravendb.net/6.2/client-api/configuration/conventions.md#useoptimisticconcurrency) convention to enable globally.

```python
# Enable for all sessions that will be opened within this document store
store.conventions.use_optimistic_concurrency = True
with store.open_session() as session:
  is_session_using_optimistic_concurrency = session.advanced.use_optimistic_concurrency  # will return True
```

## Disable for specific document (when enabled on session)

- Optimistic concurrency can be *disabled* when **storing** a specific document,  
  even when it is *enabled* for an entire session (or globally).

- This is done by passing `None` as a change vector value to the [store](https://docs.ravendb.net/6.2/client-api/session/storing-entities.python.md) method.

```python
with store.open_session() as session:
  # Store document 'products/999'
  session.store(Product(name="Some name", Id="products/999"))
  session.save_changes()

with store.open_session() as session:
  # Enable optimistic concurrency for the session
  session.advanced.use_optimistic_concurrency = True

  # Store the same document
  # Pass 'null' as the change_vector to turn OFF optimistic concurrency for this document
  session.store(Product(name="Some Other Name"), change_vector=None, key="products/999")

  # This will NOT throw a ConcurrencyException, and the document will be saved
  session.save_changes()
```

## Enable for specific document (when disabled on session)

- Optimistic concurrency can be *enabled* when **storing** a specific document,  
  even when it is *disabled* for an entire session (or globally).

- This is done by passing an empty `str` as the change vector value to the [store](https://docs.ravendb.net/6.2/client-api/session/storing-entities.python.md) method.  
  Setting the change vector to an empty string will cause RavenDB to ensure that this document is a new one and doesn't already exist.
  A `ConcurrencyException` will be thrown if the document already exists.

- If you do not provide a change vector or if the change vector is `None`, optimistic concurrency will be disabled.

- Setting optimistic concurrency for a specific document overrides the `use_optimistic_concurrency` property from the `advanced` session operations.

```python
with store.open_session() as session:
  # Store document 'products/999'
  session.store(Product(name="Some name", Id="products/999"))
  session.save_changes()

with store.open_session() as session:
  # Disable optimistic concurrency for the session
  session.advanced.use_optimistic_concurrency = False

  # Store the same document
  # Pass empty str as the change_vector to turn ON optimistic concurrency for this document
  session.store(Product(name="Some Other Name"), key="products/999", change_vector="")

  # This will throw a ConcurrencyException, and the document will NOT be saved
  session.save_changes()
```

## See also

- [Conventions](https://docs.ravendb.net/6.2/client-api/configuration/conventions.md)
- [Transaction Support in RavenDB](https://docs.ravendb.net/6.2/client-api/faq/transaction-support.md)
