Skip to end of metadata
Go to start of metadata

If you haven't already:

  1. Install the ReadyRoll Visual Studio extension on your dev machine.
  2. Create a ReadyRoll project, add a migration script, and commit it to source control, see Getting started.
  3. Install the ReadyRoll Build components on your build system.

If you are using VSTS/TFS, then see Tutorial: Visual Studio Team Services.

  1. Open the configuration page for your existing continuous integration server (eg, TeamCity, Jenkins, Bamboo, etc)

  2. Add a build step to start LocalDB to use it for the shadow database:

    Command Line
    Arguments
  3. Add a build step to use MSBuild to compile either the solution or the ReadyRoll project with these properties:

    MSBuild Properties

    The target database is only used for generating the build artifacts and it will not be modified.

    If your CI server doesn't have a MSBuild task then you can execute MSBuild via a command line task:

    Command Line

    Visual Studio 2017

    If you have Visual Studio 2017 installed on your build agents, then instead use for example:  C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\MSBuild\15.0\Bin\MSBuild.exe

  4. Add variables for TargetServer, TargetUserName, TargetPassword, and TargetDatabase for a database in one of your environments, for example test, staging, or production. This database is only used for generating the build artifacts and it will not be modified.

This will create the following build artifacts:

 

Build validation

By default, during a build, the migrations and programmable objects in the project are validated using the Microsoft Transact-SQL parser.

If a shadow database is specified, then there is an additional validation step of running the migration scripts on that database.

Any validation errors will fail the build.

SkipProjectVerification
Set this to True to produce the build artifacts without performing this validation.

 

Build artifacts

There are 6 different kinds of build artifacts that can be created:

 

1. Package deployment script

A package deployment script can be deployed to any environment, either by:

  • Running the ProjectName_DeployPackage.ps1 file.  This PowerShell script can be used to execute the database deployment from a command prompt. Simply provide a value for the $DatabaseServer variable (and optionally the $DatabaseUserName and $DatabasePassword if using SQL Server Authentication to connect to your database). A set of default SQLCMD variables will be provided to the SQL script, which can be overridden as needed.
  • Alternatively, in SQL Server Management Studio (SSMS), open the ProjectName_Package.sql file and enable SQLCMD Mode (from the Query menu). Then, uncomment the SQLCMD Variables section at the beginning of the script, make any adjustment to the variables as appropriate to the target environment, and then deploy to the target server(s).

GenerateSqlPackage

Set this to True to generate the package deployment script and accompanying PowerShell script.

DatabasePackageVersion

Set this to the version number to use in the package deployment script (e.g. 3.1.4.1337). If it is not specified, then, if set, the OctoPackPackageVersion property will be used, otherwise the AssemblyInfo.cs file will be used to determine the version number.

SkipVariableValidation

By default, the PowerShell script that ReadyRoll generates (used by VSTS/TFS, Octopus Deploy, and PowerShell command line deployment) includes validation to ensure that each of the required parameters is specified. Set this to True to skip variable validation during execution of the PowerShell script at deployment time.

 

2. Octopus Deploy package

If you would like to use Octopus Deploy to deploy the database, then see Octopus Deploy.

OctopusNuSpecFileName

Overrides the default .nuspec filename for the OctoPack process, which, by default, is ProjectName.nuspec

OctoPackTargetsPath

Overrides the OctoPackTargetsPath, which, by default, is the version bundled with the ReadyRoll build components.

 

3. Preview report

If a shadow database and a target database is specified, then, by default, a preview report is generated.

SkipDeployPreview
Set this to True to skip generating a preview report.

 

4. Diff report

ℹ️️ The diff report is not available in ReadyRoll Core; it is only available in ReadyRoll Pro.

If a shadow database and a target database is specified, then a diff report is generated.

 

5. Drift report and drift correction script

ℹ️️ The drift report and drift correction script are not available in ReadyRoll Core; they are only available in ReadyRoll Pro.

If a shadow database and a target database is specified, then, by default, a drift report and a drift correction script are generated.

SkipDriftAnalysis
Set this to True to skip generating a drift report and a drift correction script.

 

6. Patch deployment script

A patch deployment script can only be run on the target database that it is generated from (or a database with an identical schema).  It only contains the migration scripts (if any) & programmable objects (if any) that haven't already been run on that database.

If a target database is specified, then, by default, a patch deployment script is generated (called ProjectName.sql).

SkipTargetPatch
Set this to True to skip generating a patch deployment script.

 

Shadow database

The shadow database is a temporary database where ReadyRoll can run your migration scripts.  By running the migration scripts on a real database, SQL Server will check that they are valid SQL with no syntax errors, missing dependencies, etc.

The shadow database can either be on LocalDB, a local instance of SQL Server Express, or any other version of SQL Server.

ShadowServer

SQL Server instance where the shadow database should be deployed.

ShadowUserName

By default, Windows Authentication is used. Set this to a username to use with SQL Server Authentication.

ShadowPassword

By default, Windows Authentication is used. Set this to a password to use with SQL Server Authentication.

ShadowDatabase

Overrides the name of the shadow database, which, by default, is ProjectName_WindowsUserName_SHADOW

 

Target database

The target database is a database in one of your environments, for example test, staging, or production.  It will not be modified unless you specify DBReSyncOnBuild and/or DBDeployOnBuild.

TargetServer

SQL Server instance where the target database is.

TargetUserName

By default, Windows Authentication is used. Set this to a username to use with SQL Server Authentication.

TargetPassword

By default, Windows Authentication is used. Set this to a password to use with SQL Server Authentication.

TargetDatabase

Overrides the name of the target database, which, by default, is ProjectName

 

Change target database

Whilst there are these options to change the target database automatically during a build, the ReadyRoll Release components should generally be used instead.

DBReSyncOnBuild

ℹ️️ Setting DBReSyncOnBuild will modify the target database schema so that it is equal to the shadow database schema.

If set to True, then a build will automatically run the drift correction script on the target database.

DBDeployOnBuild

ℹ️️ Setting DBDeployOnBuild will modify the target database.

If set to True, then a build will automatically run the patch deployment script on the target database.

 

Other options

SuppressConnectionWarnings

By default, warnings are raised at build time if the shadow database and/or target database is not specified. Set this to True to suppress these warnings.

  • No labels