Skip to content

Latest commit

 

History

History
129 lines (78 loc) · 5.05 KB

index.md

File metadata and controls

129 lines (78 loc) · 5.05 KB
title component versions related redirects reviewed
MongoDB Persistence
mongodb
[2,)
samples/mongodb
persistence/mongodb-tekmaven
nservicebus/messaging/databus/mongodb-tekmaven
2024-08-01

Uses the MongoDB document database for storage.

Note

NServiceBus.Storage.MongoDB supports MongoDB server versions 3.6 and higher

Persistence at a glance

For a description of each feature, see the persistence at a glance legend.

Feature
Supported storage types Sagas, Outbox, Subscriptions
Transactions Enabled and required by default
Concurrency control Pessimistic concurrency only
Scripted deployment Not supported
Installers None. Documents are created in database at runtime as needed.

Usage

Add a NuGet package reference to NServiceBus.Storage.MongoDB. Configure the endpoint to use the persistence through the following configuration API:

snippet: MongoDBUsage

Customizing the connection

By default, a MongoClient is created that connects to mongodb://localhost:27017 and uses the endpoint name as its database name.

Customize the server, port, and authentication database using the following configuration API:

snippet: MongoDBClient

Specify the database to use for NServiceBus documents using the following configuration API:

snippet: MongoDBDatabaseName

Transactions

MongoDB transactions are enabled and required by default. This allows the persister to use pessimistic locking and to update multiple saga instances and commit them atomically during message processing.

Warning

MongoDB transactions require a replica set or sharded cluster. Refer to the MongoDB transaction documentation for more information about supported configurations and required MongoDB server versions.

Note

The MongoDB persister supports transactions on shared clusters starting from version 2.1.

Disabling transactions

The following configuration API is available for compatibility with MongoDB server configurations which don't support transactions:

snippet: MongoDBDisableTransactions

Note that this disables the ability to use pessimistic locking for sagas which might result in higher contention in the database.

Shared transactions

NServiceBus supports sharing MongoDB sessions between Saga persistence, Outbox storage, and business data. The shared session can be used to persist multiple document updates atomically.

To use the shared transaction in a message handler:

snippet: MongoDBHandlerSharedTransaction

Warning

In order to participate in the shared transaction the MongoDB session must be passed into collection API calls as demonstrated above.

The shared session can also be accessed via dependency injection using the IMongoSynchronizedStorageSession interface:

snippet: MongoDBSharedTransactionDI

Warning

In order to participate in the shared transaction, the MongoDB session must be passed into collection API calls as demonstrated above.

Note

The IMongoSynchronizedStorageSession lifetime is scoped to the message processing pipeline. Do not resolve the shared session into dependencies with a Singleton lifetime.

Testing

The TestableMongoSynchronizedStorageSession class in the NServiceBus.Testing namespace has been provided to facilitate testing a handler that utilizes the shared transaction feature.

Outbox cleanup

When the outbox is enabled, the deduplication data is kept for seven days by default. To customize this time frame, use the following API:

snippet: MongoDBOutboxCleanup

Saga concurrency

When simultaneously handling messages, conflicts may occur. See below for examples of the exceptions which are thrown. Saga concurrency explains how these conflicts are handled, and contains guidance for high-load scenarios.

Starting a saga

Example exception:

MongoDB.Driver.MongoCommandException: Command insert failed: WriteConflict.

Updating or deleting saga data

Starting from version 2.2, MongoDB persistence uses exclusive locks when updating or deleting saga data. The saga persister tries to acquire an exclusive lock on the saga data for up to 60 seconds. If, within this time period, an exclusive lock cannot be acquired, a TimeoutException is thrown and regular message retry policies are applied.

Example exception:

System.TimeoutException: Unable to acquire exclusive write lock for saga on collection 'collectionName'

In versions prior to version 2.2, MongoDB persistence uses optimistic concurrency control when updating or deleting saga data.

Example exception:

MongoDB.Driver.MongoCommandException: Command update failed: WriteConflict.

include: saga-concurrency