NServiceBus.Stores NServiceBus data in various relational database engines, without the need for an intermediate ORM, using only a configured DbConnection.
Highlights
- Supports multiple database engines.
- No ORM dependency: can be used with Entity Framework, Dapper, etc.
- Independent tables for each endpoint. No "noisy neighbor" problems.
- Generates DDL scripts at compile time in the build output directory.
- Generated scripts can be promoted outside the build directory and:
- Added to source control.
- Compared using a diff viewer.
- Inspected by DBAs.
- Treated as first-class citizens in operations workflows for installation and deployment.
- Sagas are:
- Stored using Json.NET to serialize complex data structures, with no need to manage complex table structures.
- Built to be version-aware with support for data evolution.
- Built to allow changing the
CorrelationIdover time.
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 script generation process uses an MSBuild task to create the scripts at compile time. As a result, the SQL Persistence package must be a direct dependency in the project containing the configuration and sagas where scripts need to be generated. If the endpoint configuration is in a separate project from the Sagas, both will need to add SQL Persistence and the file containing the
assembly: SqlPersistenceSettings attribute in order to have the scripts generate as intended.
