Installer Workflow

Component: Sql Persistence
NuGet Package NServiceBus.Persistence.Sql (4.1)
Target NServiceBus Version: 7.x

The following pages should be reviewed prior to this page:

Contrasting Workflows

In most cases, the automatic SQL installer scripts execution should be only enabled on developers machines. This kind of behavior can be enabled with the following code:

4.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
var isDevelopment = Environment.GetEnvironmentVariable("IsDevelopment") == "true";
if (!isDevelopment)

In this example the IsDevelopment environment variable is used to enable scripts execution on developers machines. A development machine could also be identified by checking a machine name convention, using some command line argument or incorporate another toggle mechanism that will be environment-specific.

In higher environments (especially in production) the installation should be designed as an integral part of the deployment process. In particular, it is recommended to put in place mechanisms to verify generated scripts and test them before running in production. It may be also necessary to customize certain settings (e.g. schemas) or to modify the scripts themselves for every environment.

Depending on the organization and the choice of tooling, the process can be fully automated, partially automated or even fully manual.

Development Workflow

The main purpose in this type of environment is having the "Just hit F5" experience, by automatically creating required tables in a local database (or remote database used only for development). The risk and potential impact of accidentally corrupting the database schema or existing data is minimal in this environment.

A typical workflow on developers machine consists of the following steps:

  1. In the project add references to both NServiceBus.Persistence.Sql and NServiceBus.Persistence.Sql.MsBuild packages.
  2. Build the project.
  3. During build NServiceBus.Persistence.Sql.MsBuild automatically creates scripts in the location appropriate for the Visual Studio project type, e.g. bin\Debug\NServiceBus.Persistence.Sql or bin\Debug\{target}\NServiceBus.Persistence.Sql.
  4. Start solution in Visual Studio.
  5. NServiceBus endpoint starts and executes its configuration code, including checking for toggle enabling installer execution.
  6. If enabled, SQL installer scripts are executed and the required persistence tables are created.

Higher Environment Workflow

"Higher Environment" is a general term to refer to any non-development environment. For example "Integration" or "Production".

The workflow in a higher environment will differ based on the specifics of an organizations process. For example, it's possible to allow endpoints to automatically execute scripts or to take full control and execute them using custom code.

In case of taking the full control of scripts execution, it is necessary to plug in the script execution into whatever deployment pipeline the organization has in place, for example:

  • When using Octopus deploy, the scripts would be executed in a "Step".
  • When using TeamCity, the scripts would be executed in a "Build Step".

The generated scripts do not contain all variables, because some of them are gathered only at runtime, e.g. @schema and @tablePrefix. Those variables need to be explicitly provided when scripts are executed. Installers automatically gather that information from endpoint configuration (e.g. by default the endpoint name is used as a @tablePrefix value).

Additionally, scripts assume the required databases and schemas already exist. Even when executed automatically by installers, scripts don't contain statements creating those elements, as they require additional configuration, such as appropriate security settings, taking into account redundancy and backup plans, etc.

A sample workflow in that kind of environment can consist of the following steps:

  2. Build Project.
  3. NServiceBus.Persistence.Sql.MsBuild creates scripts in bin\Debug\NServiceBus.Persistence.Sql.
  4. Scripts are copied to a deployment package along with the output assemblies.
  5. Scripts are reviewed by a DBA or QA team and approved.
  6. Scripts are executed in higher environment as part of the existing deployment pipeline. Required settings, such as schemas or table prefixes, have different values in each environment. They are passed to scripts together with other configuration settings, such as connection string.
  7. The endpoint is deployed and started.


Related Articles

Last modified