Complete about file for migrations.

Author: sharpjs

PSql.Deploy/en-US/about_PSql_Deploy_Migrations.help.txt

@@ -3,12 +3,16 @@ about_PSql_Deploy_Migrations
 
 SHORT DESCRIPTION
 
-A migration is a SQL script that evolves a target database's schema from its
-current version to the next version.
+A PSql.Deploy migration is a T-SQL script that evolves a target SQL Server or
+Azure SQL database's schema from its current version to the next version.  The
+Invoke-SqlMigrations cmdlet applies outstanding migrations to one or more
+target databases.
 
 
 LONG DESCRIPTION
 
+:: Source Directory Structure ::
+
 PSql.Deploy expects migrations to have a specific filesystem layout.
 
 src\                    The source directory: a set of migrations and
@@ -32,10 +36,63 @@ src\                    The source directory: a set of migrations and
  └─ ...                 PSql.Deploy does not care about other files or
                           directories present in the source directory.
 
+Given an arbitrary source directory, PSql.Deploy expects to find migrations in
+a Migrations subdirectory.  Within the Migrations directory, each subdirectory
+containing a _Main.sql file is an individual migration.  The name of the
+subdirectory determines the name of the migration.  A migration name must be a
+valid directory name but is otherwise unrestricted.
+
+The _Main.sql file is the entry point for the migration.  The file is a T-SQL
+script with a few extensions to support modularity.
+
+
+:: Migration Script SQLCMD Support ::
+
+PSql.Deploy migration scripts support a limited set of SQLCMD directives.
+Migrations may use these directives to organize code into multiple files, to
+separate SQL batches, and to replace hard-coded values with variables.
+
+    GO
+        Ends the current SQL batch and begins a new one.
+
+    $(<name>)
+        Replaced by the value of the SQLCMD variable <name>.
+
+    :r <file>
+        Replaced by the contents of the specified file.  The path is relative
+        to the current PowerShell directory ($PWD or Get-Location), matching
+        SQLCMD.EXE behavior.
+
+        To enable inclusion relative to the migration, PSql.Deploy predefines
+        the SQLCMD variable 'Path' as the full path of the directory containing
+        the _Main.sql file.  Thus the directive
+
+          :r $(Path)\Foo.sql
+
+        includes the file Foo.sql from the same directory as _Main.sql.
+
+        The path may be enclosed within double quotes.  This is mandatory if
+        the path contains spaces, tabs, or double quotes.  To include a double
+        quote in the path, use two double quotes.  Examples:
+
+          :r "$(Path)\My Script.sql"
+          :r "$(Path)/My ""Special"" Script.sql"
 
-Each subdirectory of {source-directory}\Migrations containing a _Main.sql file
-is a migration.  The name of the subdirectory is the name of the migration.
-The _Main.sql file is the entry point for the migration.
+        Note that Windows does not support tabs or double quotes in file names.  
+
+    :setvar <name> <value>
+        Sets the SQLCMD variable <name> to the spacified <value>.
+
+        The value may be enclosed within double quotes.  This is mandatory if
+        the value contains spaces, tabs, or double quotes.  To include a double
+        quote in the value, use two double quotes.
+
+          :setvar MyVar MyValue
+          :setvar MyVar "My Value"
+          :setvar MyVar "My ""Special"" Value"
+
+
+:: How Migrations Work ::
 
 PSql.Deploy's Invoke-SqlMigrations cmdlet applies (runs) each migration exactly
 once per target database.  After applying a migration, the cmdlet records the
@@ -86,7 +143,8 @@ to a prior state, then author a new migration that makes the necessary changes,
 or restore the database from a backup.  Use automated testing to find migration
 problems early, before they reach production.
 
-Phases
+
+:: Phases ::
 
 To facilitate zero- and low-downtime deployments, PSql.Deploy splits deployment
 into three logical phases: Pre, Core, and Post.  Each phase represents a
@@ -116,7 +174,8 @@ Post
     phase should finalize or clean up after the changes made in earlier phases
     while retaining compatibility with the deployed workloads.
 
-Dependencies
+
+:: Dependencies ::
 
 PSql.Deploy enables one migration to declare a dependency on another migration.
 The Invoke-SqlMigrations cmdlet handles a dependency in one of two ways.  If
@@ -129,7 +188,8 @@ dependency and preserve the guarantees that the cmdlet makes about the order of
 migration statements.  Note that this makes dependency resolution incompatible
 with zero-downtime deployment scenarios, because Core entails downtime.
 
-Ordering Guarantees
+
+:: Ordering Guarantees ::
 
 The Invoke-SqlMigrations cmdlet makes the following guarantees about the order
 of migration statement execution:
@@ -184,7 +244,8 @@ Yield this order operations:
 5 │             │                          ^^^ Pre      Core │           Post │
     Time──>                                    ^^^
 
-Magic Comments
+
+:: Magic Comments ::
 
 A migration may contain 'magic comments', which are special comments that the
 Invoke-SqlMigrations cmdlet interprets as directives.  The cmdlet supports the
@@ -202,7 +263,8 @@ following magic comments:
 --# REQUIRES: <migration-name> ...
     Declares a dependency on one or more migrations.
 
-Example Migration Naming Schemes
+
+:: Example Migration Naming Schemes ::
 
 Here are some example migration naming schemes:
 
@@ -232,21 +294,31 @@ Here are some example migration naming schemes:
     Best for: teams with multiple migration authors where it is useful to
       associate migrations with work items, pull requests, etc.
 
-Squashes
+
+:: Squashes ::
 
 A long-lived project with frequent schema changes will accumulate a large
 number of migrations over time.  For such projects, it is sometimes useful to
 delete old migrations and instead use a create script that creates a database
-already migrated to that poitn in time.  This is known as a 'squash'.  Create
-scripts are outside the scope of PSql.Deploy, but PSql.Deploy supports squashes
+already migrated to that point in time.  This is known as a 'squash'.  Create
+scripts are beyond the scope of PSql.Deploy, but PSql.Deploy supports squashes
 by not caring about completed migrations that are no longer present in the
 source directory.  Nevertheless, there are two rules that must be oserved when
 performing a squash:
 
 1. The oldest unsquashed migration must be same age or older than the oldest
      backup that is likely to be restored.
 
-1. The oldest unsquashed migration must be same age or older than the create
+2. The oldest unsquashed migration must be same age or older than the create
      script.
 
-TODO: Describe this better when more brain cells are available.
+Failure to observe these rules can cause restore-and-migrate or
+create-and-migrate operations to miss migrations, causing later migrations to
+fail or leaving the schema in an unexpected state.
+
+:: See Also ::
+
+- about_PSql_Deploy
+- Get-SqlMigrations
+- Invoke-SqlMigrations
+- https://github.com/sharpjs/PSql.Deploy