see on GitHub

    How to Enable Optimistic Concurrency

    • By default, optimistic concurrency checks are turned off. Changes made outside 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.

    • You can enable the optimistic concurrency for either:

      • All sessions - enable globally, at the document store level
      • A specific session - enable on a per-session basis
      • A specific document

    • 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 SaveChanges 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:

    • Note that the UseOptimisticConcurrency setting only applies to documents that have been modified by the current session. For example, if you load documents users/1-A and users/2-A in a session, make modifications only to users/1-A, and then call SaveChanges, 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 turned on, 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.

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

    Enable for specific session 

    using (IDocumentSession session = store.OpenSession())
{
    // Enable optimistic concurrency for this session
    session.Advanced.UseOptimisticConcurrency = true;

    // Save a document in this session
    Product product = new Product { Name = "Some Name" };
    session.Store(product, "products/999");
    session.SaveChanges();

    // Modify the document 'externally' by another session 
    using (IDocumentSession otherSession = store.OpenSession())
    {
        Product otherProduct = otherSession.Load<Product>("products/999");
        otherProduct.Name = "Other Name";
        otherSession.SaveChanges();
    }

    // Trying to modify the document without reloading it first will throw
    product.Name = "Better Name";
    session.SaveChanges(); // This will throw a ConcurrencyException
}

    • 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 SaveChanges() 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 

    // Enable for all sessions that will be opened within this document store
store.Conventions.UseOptimisticConcurrency = true;

using (IDocumentSession session = store.OpenSession())
{
    bool isSessionUsingOptimisticConcurrency = session.Advanced.UseOptimisticConcurrency; // will return true
}

    Disable for specific document (when enabled on session)

    • Optimistic concurrency can be turned OFF when storing a specific document,
      even when it is turned ON for an entire session (or globally).

    • This is done by passing null as a change vector value to the Store method.

    using (IDocumentSession session = store.OpenSession())
{
    // Store document 'products/999'
    session.Store(new Product { Name = "Some Name" }, id: "products/999");
    session.SaveChanges();
}

using (IDocumentSession session = store.OpenSession())
{
    // Enable optimistic concurrency for the session
    session.Advanced.UseOptimisticConcurrency = true;

    // Store the same document
    // Pass 'null' as the changeVector to turn OFF optimistic concurrency for this document
    session.Store(new Product { Name = "Some Other Name" }, changeVector: null, id: "products/999");
    
    // This will NOT throw a ConcurrencyException, and the document will be saved
    session.SaveChanges();
}

    Enable for specific document (when disabled on session)

    • Optimistic concurrency can be turned ON when storing a specific document,
      even when it is turned OFF for an entire session (or globally).

    • This is done by passing string.Empty as the change vector value to the Store 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 don't supply a 'Change Vector' or if the 'Change Vector' is null, then optimistic concurrency will be disabled.

    • Setting optimistic concurrency for a specific document overrides the UseOptimisticConcurrency property from the Advanced session operations.

    using (IDocumentSession session = store.OpenSession())
{
    // Store document 'products/999'
    session.Store(new Product { Name = "Some Name" }, id: "products/999");
    session.SaveChanges();
}

using (IDocumentSession session = store.OpenSession())
{
    // Disable optimistic concurrency for the session 
    session.Advanced.UseOptimisticConcurrency = false; // This is also the default value

    // Store the same document
    // Pass 'string.Empty' as the changeVector to turn ON optimistic concurrency for this document
    session.Store(new Product { Name = "Some Other Name" }, changeVector: string.Empty, id: "products/999");
    
    // This will throw a ConcurrencyException, and the document will NOT be saved
    session.SaveChanges();
}

    see on GitHub

    related articlesRelated Articles

    Configuration

    FAQ

    Home / Docs / Client Api / Session / Configuration / How To Enable Optimistic Concurrency