Getting Started
Architecture
NServiceBus
Transports
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

SQL Persistence

Target Version: NServiceBus 8.x

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

Persistence at a glance

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

Feature
Storage TypesSagas, Outbox, Subscriptions, Timeouts
TransactionsLocal database transactions or distributed transactions when available
Concurrency controlOptimistic concurrency for correctness + pessimistic concurrency for performance
Scripted deploymentSQL scripts generated at compile time, can be promoted outside build directory.
InstallersInstallers execute the generated scripts, which can be enabled in development.

Highlights

Supported SQL implementations

NuGet Packages

The SQL Persister requires the NServiceBus.Persistence.Sql package, which contains:

  • APIs for manipulating EndpointConfiguration.
  • Runtime implementations of saga, timeouts, subscriptions, and outbox persisters.
  • Attributes used to define compile-time configuration settings.
  • [Version 4.3+] An MSBuild target that generates the required SQL installation scripts at compile time.
  • Optionally runs SQL installation scripts at endpoint startup for development purposes. See Installer Workflow.
In version 4.2 and below, The NServiceBus.Persistence.Sql.MsBuild package must also be referenced by any project that requires generating SQL installation scripts. This includes any project that contains saga classes or hosts an NServiceBus endpoint.

Other packages

  • NServiceBus.Persistence.Sql.MsBuild - In version 4.2 and below, this package must also be referenced to generate scripts. In version 4.3 and above, this package is deprecated, as the generation capability is built in to the main package.
  • NServiceBus.Persistence.Sql.ScriptBuilder - This package contains the APIs that enable the generation of SQL installation scripts using code outside of a compile context. It is not intended for general usage, and in future releases, the API may evolve in ways that do not follow semantic versioning.

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 scripts are generated by an MSBuild task at compile time. Any project containing either endpoint configuration or sagas must directly reference the SQL Persistence package. If endpoint configuration and sagas are contained in seperate projects, both projects must directly reference the SQL Persistence package and include the assembly: SqlPersistenceSettings attribute.

Troubleshooting

Looping & branching statements are not allowed

SqlPersistenceTask: Looping & branching statements are not allowed in a ConfigureHowToFindSaga method.

The ConfigureHowToFindSaga method can only contain statements that invoke ConfigureMapping<T>. Check if there is a null check or if the calling of ConfigureHowToFindSaga was done via the ?. Null-conditional operator and remove the ‘?.’ operator when present as the mapper will never be null.

Samples

Related Articles


Last modified