SQL Persistence

NuGet Package NServiceBus.Persistence.Sql (3.x)
Target NServiceBus Version: 6.x

Stores NServiceBus data in various relational database engines, without the need for an intermediate ORM, using only a configured DbConnection.


Supported SQL implementations

NuGet Packages

The SQL Persister consists of several NuGet packages.


This packages adds to the MSBuild pipeline and generates the required SQL installation scripts at compile time. It does this by interrogating types (in the target assembly) and attributes (from the NServiceBus.Persistence.Sql NuGet package) to infer what scripts to create. It is required for any project where those SQL installation scripts are required. For saga scripts, this is any project that contains saga classes. For timeouts, subscriptions, and outbox scripts, it is the endpoint hosting project. This package has a dependency on the NServiceBus.Persistence.Sql NuGet package.


This package contains several parts:

  • APIs for manipulating EndpointConfiguration.
  • Runtime implementations of saga, timeouts, subscriptions, and outbox persisters.
  • Attributes used to define compile-time configuration settings. These attributes are interrogated by the NServiceBus.Persistence.Sql.MsBuild NuGet Package when generating SQL installation scripts.
  • Optionally runs SQL installation scripts at endpoint startup for development purposes. See Installer Workflow.


This package contains the APIs that enable the generation of SQL installation scripts using code, i.e. without using the NServiceBus.Persistence.Sql.MsBuild NuGet package.

NServiceBus.Persistence.Sql.ScriptBuilder is not ready for general usage. It was made public and deployed to NuGet primarily to enable the generation of documentation in a repeatable way. For example, it is used to generate the SQL scripts in the MS SQL Server Scripts, MySql Scripts, Oracle Scripts, and PostgreSQL Scripts pages. In future releases, the API may evolve in ways that do not follow semantic versioning. This can be discussed in more detail in the Particular Software discussion forum.

Script creation

SQL installation scripts are created as a compile-time output alongside a project's binary outputs. Additionally, these scripts can be promoted to a directory under source control so that differences can be easily tracked and analyzed. To learn more, see Controlling Script Generation.

The script generation process uses an MSBuild task to create the scripts at compile time. As a result, SQL Persistence must be a direct dependency to the project where scripts need to be generated.


Related Articles

Last modified