This details some of the conventions used in SQL Change Automation deployments by examining the project artifacts; specifically the T-SQL file that is generated when you perform a Build in Visual Studio or using Invoke-DatabaseBuild. The deployment script contains a concatenated list of all the scripts from your SQL Change Automation project.

Output script header

The first thing you will see when you open the deployment script is the SqlCmd header:

----====================================================================================================================
---- SQLCMD Variables

:setvar DatabaseName "AdventureWorks"
:setvar Configuration "Debug"
:setvar OctopusEnvironmentName "DEV"
:setvar ReportFolder "\\bigsan01\reports\"
----====================================================================================================================

:on error exit -- Instructs SQLCMD to abort execution as soon as an erroneous batch is encountered

GO

SqlCmd is a SQL Server utility with a unique scripting syntax that provides us with two key advantages over deploying with plain old T-SQL:

• The :on error exit directive ensures that, if any statement within the script raises an unhandled exception, execution is immediately halted at the current batch (rather than simply continuing to the next batch after GO)
• Support for variables which can be passed via the sqlcmd.exe command-line tool. Those variables can be used throughout your scripts using the $(VariableName) syntax

XACT_ABORT to control execution flow

The next thing you’ll notice is the use of the SET XACT_ABORT ON predicate. According to MSDN:

When SET XACT_ABORT is ON, if a Transact-SQL statement raises a run-time error, the entire transaction is terminated and rolled back. When SET XACT_ABORT is OFF, in some cases only the Transact-SQL statement that raised the error is rolled back and the transaction continues processing.

To avoid the need to add excessive amounts of error-handling logic to your scripts, we explicitly set this predicate ON as part of the build and prevent you from setting it to OFF within migrations and programmable objects/additional scripts (unless the Custom transaction-handling mode is used; see below disabling automatic transaction handling).

In spite of there being no automatic transaction handling for the files contained within the pre-deployment and post-deployment folders, SQL Change Automation also sets XACT_ABORT to the ON setting within these scripts for consistency of deployment behavior. However, as some features of the T-SQL language (such as the sp_fulltext_load_thesaurus_file statement) require this setting to be OFF, it may be necessary to include a SET XACT_ABORT OFF statement in the header of your pre/post deployment scripts. Note that, for these types of scripts, it is not necessary to include the Custom header metadata described further below.

Putting it together

The combination of SqlCmd and XACT_ABORT ensures that, if an exception occurs at any point during deployment, the execution is halted and the connection dropped at the current statement. 

Additionally, scripts that have been executed thus far will be rolled back:

:setvar DatabaseName "AdventureWorks"

:on error exit -- Instructs SQLCMD to abort execution as soon as an erroneous batch is encountered

SET XACT_ABORT ON;
BEGIN TRANSACTION;

------------------ BEGIN MIGRATION: "0016_20131129-1641_User.sql" --------------------
CREATE TABLE t1
    (a INT NOT NULL PRIMARY KEY);

INSERT INTO t1 VALUES (1);
INSERT INTO t1 VALUES (2);
GO
------------------- END MIGRATION: "0016_20131129-1641_User.sql" ---------------------
INSERT [$(DatabaseName)].[dbo].[__MigrationLog] ([migration_id], [script_checksum], [script_filename], [complete_dt], [applied_by], [deployed])
VALUES (CAST ('d9a91eef-2db8-4911-868b-b29d3d86bae0' AS UNIQUEIDENTIFIER), '82E9FEA4D0637C8F09DC4D67F4EEC0ED2F706AED8ADFDFA845FFE06188EDE75A', '0016_20131129-1641_User.sql', SYSDATETIME(), SYSTEM_USER, 1);
GO

------------------------ BEGIN PROGRAMMABLE OBJECT: "dbo.v1.sql" ----------------------------
IF OBJECT_ID('[dbo].[v1]') IS NULL
  EXEC('CREATE VIEW [dbo].[v1] AS SELECT 1 AS Dummy'); -- PLACEHOLDER ONLY - Specify object parameters/body within the ALTER statement
GO
  
ALTER VIEW [dbo].[v1]
  AS SELECT a, b FROM [t1] -- Will fail because `[b]` is an invalid column 
GO
------------------------- END PROGRAMMABLE OBJECT: "dbo.v1.sql" -----------------------------
INSERT  [$(DatabaseName)].[dbo].[__MigrationLog] ([migration_id], [script_checksum], [script_filename], [complete_dt], [applied_by], [deployed])
VALUES  (CAST ('0fa6126b-1e3b-438e-8915-72954309cce6' AS UNIQUEIDENTIFIER), 'B352156857D4BCA92A1DD2931642CECC43FBEB86C5BE305339A28F79EE9002FD', 'dbo.v1.sql', SYSDATETIME(), SYSTEM_USER, 1); -- This line will not be reached due to the error in "dbo.v1.sql"
GO

COMMIT TRANSACTION; -- This line will not be reached due to the error in "dbo.v1.sql"

One thing conspicuously missing here is a ROLLBACK statement at any point. This is because a rollback is implicit in the use of the XACT_ABORT predicate: when an unhandled error occurs, SQL Server immediately performs a rollback and raises an error to the client (in our case, sqlcmd.exe).

Controlling execution flow with TRY/CATCH blocks

For the most part, we hope that the structure we’ve added around your migrations means you’ll never need to worry about how transactions are handled. However there are some use cases for which you might want to exercise greater control over the flow of execution.

For example, say you want to write some details of an error to a log table. Typically, your log records would simply be rolled-back along with your other changes when an error occurs.

But with a TRY/CATCH block, you have the ability to capture exceptions that are raised within your batch and issue a ROLLBACK yourself. For example:

:setvar DatabaseName "AdventureWorks"

:on error exit

SET XACT_ABORT ON;
BEGIN TRANSACTION;

------------------ BEGIN MIGRATION: "0016_20131129-1641_User.sql" --------------------
CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY);

BEGIN TRY
  INSERT INTO t1 VALUES (1);
  INSERT INTO t1 VALUES (1); -- Will fail because ID=1 already exists in the table
END TRY
BEGIN CATCH
  IF @@TRANCOUNT > 0 
      ROLLBACK TRANSACTION; -- We must roll-back because our transaction is doomed at this point

  BEGIN TRANSACTION
      IF OBJECT_ID('error_log') IS NULL
          CREATE TABLE error_log (id INT IDENTITY(1, 1) PRIMARY KEY, msg NVARCHAR(MAX));

      INSERT INTO error_log (msg) VALUES (ERROR_MESSAGE());
  COMMIT TRANSACTION
  RAISERROR(N'An error occurred. Halting deployment.', 16, 127, N'UNKNOWN') WITH NOWAIT;
END CATCH
------------------- END MIGRATION: "0016_20131129-1641_User.sql" ---------------------
GO
INSERT  [$(DatabaseName)].[dbo].[__MigrationLog] ([migration_id], [script_checksum], [script_filename], [complete_dt], [applied_by], [deployed])
VALUES  (CAST ('d9a91eef-2db8-4911-868b-b29d3d86bae0' AS UNIQUEIDENTIFIER), '06D29866BEE2749E96C842DDE120CBBA96624D4B2882AFFD97AA8298994AD9A9', '0016_20131129-1641_User.sql', SYSDATETIME(), SYSTEM_USER, 1); -- This line will not be reached due to the error in the above migration
GO

COMMIT TRANSACTION; -- This line will not be reached due to the error in the above migration

This code will raise an exception at line 13, causing the prior operations in the batch to be rolled-back. However the new row in the error_log will persist even after the script is halted (via the RAISERROR), because it occurs in a separate transaction to the statements within the TRY block.

How are syntax errors handled?

SQL Change Automation runs all of your migrations through the T-SQL compiler during project build, so provided your statements are not being executed as dynamic SQL (for example, using EXEC / sp_execute), you should not receive syntax errors at deployment time.

However testing your SQL Change Automation project by doing a full deploy to a test server is still the most foolproof way of validating your T-SQL migrations.