Getting Started

SQL Persistence - SQL Server dialect

Component: Sql Persistence
Target Version: NServiceBus 7.x

Supported database versions

SQL persistence supports SQL Server Version 2012. It does not work with lower versions due to the use of the THROW functionality.


Using either the System.Data.SqlClient or Microsoft.Data.SqlClient NuGet packages.

var connection = @"Data Source=.\SqlExpress;Initial Catalog=dbname;Integrated Security=True";
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
var subscriptions = persistence.SubscriptionSettings();
    connectionBuilder: () =>
        return new SqlConnection(connection);

Unicode support

SQL persistence itself supports Unicode characters, however data may become corrupted during saving if the database settings are incorrect. If Unicode support is required, follow the guidelines for each database engine. In particular set the correct character set and collation for databases storing persistence data.

Refer to the dedicated SQL Server documentation for details.

Supported name lengths

SQL persistence automatically generates names of database objects such as tables, indexes and procedures used internally. Every database engine has its own rules and limitations regarding maximum allowed name length.

SQL Server supports max. 128 characters.

Schema support

The SQL Server dialect supports multiple schemas. By default, when a schema is not specified, it uses the dbo schema when referring to database objects.

var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
var dialect = persistence.SqlDialect<SqlDialect.MsSqlServer>();

Connection sharing

When an endpoint uses SQL Persistence combined with the SQL Server Transport without the Outbox, the persistence uses the connection and transaction context established by the transport when accessing saga data. This behavior ensures exactly-once message processing behavior as the state change of the saga is committed atomically while consuming of the message that triggered it.

When using the outbox, SQL Persistence always opens its own connection. In order to force using a separate connection even when the outbox is disabled, use the following API:

var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
var dialect = persistence.SqlDialect<SqlDialect.MsSqlServer>();

SQL Always Encrypted

The SQL Server Always Encrypted feature is not supported by this version of the persister when using the SQL Server dialect. The feature was added in SQL Persistence version 6.1.