Connection Options

Component: RavenDB Persistence
NuGet Package NServiceBus.RavenDB (1.x)
Target NServiceBus Version: 4.x
Standard support for version 4.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.

The following sections outline various ways to connect to the RavenDB server. Specifying an external shared store (providing a fully configured RavenDB DocumentStore instance) is preferred so that the configuration of the DocumentStore is not obscured.

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.


By default, a DocumentStore is created that connects to http://localhost:8080 and uses the endpoint name as its database name. This default connection is used for all the persisters.

Database used

After connecting to a RavenDB server, decide which database to use. Unless NServiceBus finds a default database specified in the connection string, NServiceBus uses the endpoint name as the database name. So if the endpoint is named MyServer, the database name is MyServer. Each endpoint has a separate database unless explicitly overridden via the connection string. RavenDB automatically creates the database if it doesn't already exist.

See also How to specify endpoint name.


For all NServiceBus 3.x and 4.x versions, RavenDB is the default mechanism for NServiceBus to persist its timeout, saga and subscription data.

Configuring NServiceBus to use RavenDB for persistence can be accomplished by calling Configure.RavenPersistence(), however as this is the default configuration this call is not required.

RavenDB persistence for NServiceBus 3 to 4 uses these conventions:

  • If no master node is configured it assumes that a RavenDB server is running at http://localhost:8080, the default URL for RavenDB.
  • If a master node is configured, the URL is: http://{masternode}/:8080.
  • If a connection string named "NServiceBus/Persistence" is found, the value of the connectionString attribute is used.

If NServiceBus detects that any RavenDB related storage is used for sagas, subscriptions, timeouts, etc., it will automatically configure it. There is no need to explicitly configure RavenDB unless it is necessary to override the defaults.

Using the NServiceBus IDocumentStore for business data is not possible

The RavenDB client is merged and internalized into the NServiceBus assemblies. To use the Raven IDocumentStore for business data, reference the Raven client and set up a custom IDocumentStore.

In NServiceBus 4.x RavenDB is not ILMerged any more. It is embedded instead, using

The embedding enables client updates (but may require binding redirects). It also allows passing a custom instance of DocumentStore, thereby providing full configuration flexibility.

Overriding the defaults

In some situations the default behavior might not be desired:

  • When using RavenDB for business data as it may be necessary to share the connection string. Use the Configure.RavenPersistence(string connectionStringName) signature to tell NServiceBus to connect to the server specified in that string. The default connection string for RavenDB is RavenDB.
  • To control the database name in code, instead of via the configuration, use the Configure.RavenPersistence(string connectionStringName, string databaseName) signature. This can be useful in a multitenant scenario.


Last modified