RavenDB Persistence

NuGet Package NServiceBus.RavenDB (3.x)
Target NServiceBus Version: 5.x
Standard support for version 5.x of NServiceBus has expired. For more information see our Support Policy.
RavenDB's implementation of distributed transactions contains a bug that could cause an endpoint, in certain (rare) conditions, to lose data. If RavenDB is configured to enlist in distributed transactions, read DTC not supported for RavenDB Persistence.
Using RavenDB version 4 and higher in a cluster configuration with multiple nodes is not supported. For more information, read cluster configuration with multiple nodes not supported.

Uses the RavenDB document database for storage.

Persistence at a glance

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

Supported storage typesSagas, Outbox, Subscriptions, Timeouts
Transactionsvia IDocumentSession.SaveChanges()
Concurrency controlOptimistic concurrency, optional custom pessimistic concurrency for performance
Scripted deploymentNot supported
InstallersNone. Required indexes are created in the database as needed.

RavenDB versions

Specific versions of RavenDB Persistence are tied to a major version of NServiceBus and also designed to work with a specific version of the RavenDB client library. When releasing a new major version of NServiceBus, the corresponding RavenDB Persistence release will use the last supported version of RavenDB, so that it is never necessary to upgrade both NServiceBus and RavenDB at the same time.

NServiceBusRavenDB PersistenceRavenDB ClientPlatform
7.x6.x4.2.NET 4.7.2 / .NET Core 2.1
7.x5.0.x3.5.NET 4.5.2 / .NET Core 2.0
6.x4.2.x3.5.NET 4.5.2
6.x4.0.x3.0.NET 4.5.2
5.x3.2.x3.5.NET 4.5.2
5.x3.0.x3.0.NET 4.5.2
5.x2.x2.5.NET 4.5.2

See the NServiceBus Packages Supported Versions to see the support details for each version of RavenDB Persistence.

Connection options for RavenDB

There are a variety of options for configuring the connection to a RavenDB Server. See RavenDB Connection Options for more details.

Shared session

NServiceBus supports sharing the same RavenDB document session between Saga persistence, Outbox persistence, and business data, so that a single persistence transaction can be used to persist the data for all three concerns atomically. Shared sessions are automatically configured when an endpoint has enabled the Outbox feature or contains sagas.

To use the shared session in a message handler:

public class HandlerThatUsesSession :
    ISessionProvider sessionProvider;

    public HandlerThatUsesSession(ISessionProvider sessionProvider)
        this.sessionProvider = sessionProvider;

    public void Handle(MyMessage message)
        var doc = new MyDocument();


Although additional database operations inside a saga handler are not recommended (see warning below) the shared session can also be accessed from a saga handler:

Other than interacting with its own internal state, a saga should not access a database, call out to web services, or access other resources. See Accessing databases and other resources from a saga.

If the situation is special enough to warrant going against this recommendation, the following documentation will describe how to do so.

public class SagaThatUsesSession :
    ISessionProvider sessionProvider;

    public SagaThatUsesSession(ISessionProvider sessionProvider)
        this.sessionProvider = sessionProvider;

    public void Handle(MyMessage message)
        var document = new MyDocument();

Customizing the IDocumentSession

In this version of NServiceBus.RavenDB, the API used to customize the IDocumentSession instance is incompatible with the Outbox feature. Contact support if this poses a problem.

The creation of the RavenDB IDocumentSession instance used by NServiceBus and made available as the shared session can be customized as shown in the following snippet. Despite the name of the method, this option does not enable the shared session but only affects the customization of that session.

var myDocumentStore = new DocumentStore();
// configure documentStore properties here

var persistence = busConfiguration.UsePersistence<RavenDBPersistence>();
    getSessionFunc: headers =>
        var session = myDocumentStore.OpenSession();
        // customize session here
         return session;
When the RavenDB DocumentStore is created by the user at endpoint configuration time it's important to dispose it, by calling the Dispose() method, before shutting down the endpoint process.

The getSessionFunc function receives the incoming message headers as an argument. Message headers can be used to support multi-tenant environments customizing the shared session based on the currently processed message.

Saga correlation

As of Version 6 of NServiceBus, all correlated properties are unique by default so there is no longer a configuration setting.

One of the limitations of the RavenDB persistence is support for only one [Unique] property (a saga property which value is guaranteed to be unique across all sagas of this type). Because of that limitation advanced user can turn off the validation that ensures sagas are only being found by unique properties:

var persistence = busConfiguration.UsePersistence<RavenDBPersistence>();
This is a potentially dangerous feature that can result in multiple instances of saga being created instead of one in cases of high contention.

Viewing the data

Open a web browser and type the URL of the RavenDB server. This opens the RavenDB Studio.

Migrating timeouts

Timeouts can be migrated to the native-delay delivery implementation with the migration tool.


Related Articles

Last modified