How document versioning works

Component: MongoDB Persistence
NuGet Package NServiceBus.Storage.MongoDB (3-pre)
Target NServiceBus Version: 8.x
This page targets a pre-release version and is subject to change prior to the final release.

MongoDB provides no out-of-the-box concurrency controls. A common pattern for supporting concurrency is using a document version number (int) that is used as a filter for update statements:

UpdateDefinition<BsonDocument> updateDefinition = updateBuilder.Inc(versionFieldName, 1);

//Define other update operations on the document

var modifiedDocument = await collection.FindOneAndUpdateAsync<BsonDocument>(
    filter: document => document["_id"] == documentId && document["_version"] == currentVersion,
    update: updateDefinition,
    options: new FindOneAndUpdateOptions<BsonDocument, BsonDocument> { IsUpsert = false, ReturnDocument = ReturnDocument.After });

if (modifiedDocument == null)
    //The document was not updated because the version was already incremented.

By updating the document with a filter specifying the expected current version value of the document, no update will be made if another process has incremented the version before the current process is able to. This package relies on this pattern to ensure only one process/thread can update the saga at a time.

This pattern requires an element in the BsonDocument to store the current version value. Instead of requiring the user provide this as a property of their saga data type, this package uses the MongoDB client's BSON serializer to add a version element to the serialized saga data as it is initially created and stored in the collection. When the saga data serialized BsonDocument is later fetched, the version element's current value is retrieved before deserializing to the saga data type. The current value is then retained for the lifetime of saga message processing and is used to create the update filter.

By default, the BsonDocument element is named _version.

Related Articles

Last modified