Cluster Transaction - Atomic Guards

Atomic guards are created and managed by default only when the session's transaction mode is set to ClusterWide. The atomic guards are managed as follows:

• New document:
  A new atomic guard is created when successfully saving a new document.

• Existing document that doesn't have an atomic guard:
  A new atomic guard is created when modifying an existing document that does not yet have an associated atomic guard.

• Existing document that already has an atomic guard:

  • Whenever one session modifies a document that already has an associated atomic guard,
    the value of its related atomic guard increases.
    This allows RavenDB to detect that changes were made to this document.

  • If other sessions have loaded the document before the version changed,
    they will not be able to modify it if trying to save after the first session already saved it,
    and a ConcurrencyException will be thrown.

  • If the session saveChanges() fails, the entire session is rolled-back and the atomic guard is not created.
    Be sure that your business logic is written so that if a concurrency exception is thrown, your code will re-execute the entire session.

• Atomic guards are local to the database they were defined on.

• Since atomic guards are implemented as compare-exchange items,
  they are Not externally replicated to another database by any ongoing replication task.
  Learn more in why compare-exhange items are not replicated.

In the code sample below, an atomic guard is automatically created upon the creation of a new document,
and then used when two sessions compete on changing the document.

const user = {
    firstName: "John",
    lastName: "Doe"
};

// Open a cluster-wide session
const session = documentStore.openSession({
    transactionMode: "ClusterWide"
});

await session.store(user, "users/johndoe");
await session.saveChanges();
// An atomic-guard is now automatically created for the new document "users/johndoe".

// Open two more cluster-wide sessions
const session1 = documentStore.openSession({
    transactionMode: "ClusterWide"
});        
const session2 = documentStore.openSession({
    transactionMode: "ClusterWide"
});

// The two sessions will load the same document at the same time
const loadedUser1 = await session1.load("users/johndoe");
loadedUser1.name = "jindoe";

const loadedUser2 = await session2.load("users/johndoe");
loadedUser2.name = "jandoe";

// session1 will save changes first, which triggers a change in the 
// version number of the associated atomic-guard.
await session1.saveChanges();

// session2.saveChanges() will be rejected with a ClusterTransactionConcurrencyException
// since session1 already changed the atomic-guard version,
// and session2 saveChanges uses the document version that it had when it loaded the document.
await session2.saveChanges();        

After running the above example, the atomic guard that was automatically created can be viewed in the Studio,
in the Compare-Exchange view:

Atomic Guard

The generated atomic guard key name is composed of:

• The prefix rvn-atomic
• The ID of the document that it is associated with

To disable the automatic creation & usage of atomic guards in a session, set the session disableAtomicDocumentWritesInClusterWideTransaction configuration option to true.

In the sample below, the session uses no atomic guards.

// Open a cluster-wide session
const session = documentStore.openSession({
    transactionMode: "ClusterWide",
    // Disable atomic-guards
    disableAtomicDocumentWritesInClusterWideTransaction: true
});

await session.store(user, "users/johndoe");

// No atomic-guard will be created upon saveChanges
await session.saveChanges();

Atomic guards expire on the expiration of the documents they are used for and are automatically removed by a RavenDB cleanup task. You do not need to handle the cleanup yourself.