Skip to content

Commit bcbe149

Browse files
sharpjssharpjs
committed
WIP: Documentation.
1 parent 12342f0 commit bcbe149

2 files changed

Lines changed: 144 additions & 1 deletion

File tree

‎PSql.Deploy/PSql.Deploy.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<PropertyGroup>
99
<Description>Database migration and seeding system for SQL Server and Azure SQL Database.</Description>
1010
<GenerateDependencyFile>false</GenerateDependencyFile>
11-
<PowerShellItemIncludes>$(PowerShellItemIncludes);**/*.sql</PowerShellItemIncludes>
11+
<PowerShellItemIncludes>$(PowerShellItemIncludes);**/*.txt</PowerShellItemIncludes>
1212
</PropertyGroup>
1313

1414
<ItemGroup>

‎PSql.Deploy/en-US/about_PSql_Deploy.help.txt‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
about_PSql_Deploy
2+
=================
3+
4+
SHORT DESCRIPTION
5+
6+
PSql.Deploy is a migration and seeding system for SQL Server and Azure SQL
7+
Database.
8+
9+
10+
LONG DESCRIPTION
11+
12+
The PSql.Deploy module provides cmdlets to deal with two core concepts:
13+
migrations and seeds. A migration is a SQL script that modifies the schema of
14+
a target database. A seed is a SQL script that populates a target database
15+
with data. Together, migrations and seeds provide a mechanism to perform
16+
database deployments in a controlled and repeatable manner.
17+
18+
Source Directory Structure
19+
20+
PSql.Deploy expects migrations and seeds to have a specific filesystem layout.
21+
22+
src\ The source directory: a set of migrations and
23+
│ seeds for one database design. The name can vary.
24+
│
25+
├─ Migrations\ Migrations. Required only if there are any migrations.
26+
│ │
27+
│ ├─ 0001\ One migration. The name can vary.
28+
│ │ │
29+
│ │ ├─ _Main.sql Top-level script for the migration. It can
30+
│ │ │ include other files with the :r directive.
31+
│ │ ├─ FileA.sql Example file included by _Main.sql.
32+
│ │ ├─ FileB.sql Example file included by _Main.sql.
33+
│ │ └─ ... More files, subdirectories, etc.
34+
│ │
35+
│ └─ ... More migrations.
36+
│
37+
├─ Seeds\ Seeds. Required only if there are any seeds.
38+
│ │
39+
│ ├─ TestData\ One seed. The name can vary.
40+
│ │ │
41+
│ │ ├─ _Main.sql Top-level script for the migration. It can
42+
│ │ │ include other files with the :r directive.
43+
│ │ ├─ FileA.sql Example file included by _Main.sql.
44+
│ │ ├─ FileB.sql Example file included by _Main.sql.
45+
│ │ └─ ... More files, subdirectories, etc.
46+
│ │
47+
│ └─ ... More migrations.
48+
│
49+
└─ ... PSql.Deploy does not care about other files or
50+
directories present in the source directory.
51+
52+
See the sections below for more details about migrations and seeds.
53+
54+
55+
Migrations
56+
----------
57+
58+
A migration is a SQL script that modifies the schema of a target database.
59+
60+
Each subdirectory of {source-directory}\Migrations containing a _Main.sql file
61+
is a migration. The name of the subdirectory is the name of the migration.
62+
63+
PSql.Deploy's Invoke-SqlMigrations cmdlet applies (runs) each migration exactly
64+
once per target database to evolve the database's schema from its current
65+
version to the next version. After applying a migration, the cmdlet records
66+
the migration's state in a table in the target database so that future
67+
deployments to the database will skip that migration.
68+
69+
When multiple migrations are present in the source directory but not yet
70+
applied to a target database, The Invoke-SqlMigrations cmdlet applies them in a
71+
specific order: from least to greatest by case-insensitive ordinal comparison
72+
of the migrations' names. It is therefore important to choose a migration
73+
naming scheme carefully to fit the development workflow of the database. See
74+
below for examples of migration naming schemes.
75+
76+
:: Phases
77+
78+
To facilitate zero- and low-downtime deployments, PSql.Deploy splits deployment
79+
into three logical phases: Pre, Core, and Post. Each phase represents a
80+
different moment within a deployment process. Each SQL statement within a
81+
migration executes in exactly one of these phases. One migration can contain
82+
statements for multiple phases.
83+
84+
The three phases are:
85+
86+
- Pre
87+
This phase occurs before deployment of the workloads that use the target
88+
database, perhaps while previously deployed workloads are still running.
89+
Migration statements in this phase should make the database compatible with
90+
the upcoming workload deployment retaining compatibility with the existing
91+
workloads.
92+
93+
- Core
94+
This phase occurs at some arbitrary point between the Pre and Post phases.
95+
PSql.Deploy interprets statements within this phase as requiring downtime,
96+
explicitly breaking a zero-downtime deployment schenario.
97+
98+
- Post
99+
This phase occurs after deployment of the workloads that use the target
100+
database, while those workloads are running. Migration statements in this
101+
phase should finalize or clean up after the changes made in earlier phases
102+
while retaining compatibility with the deployed workloads.
103+
104+
Deployments for which downtime is not a concern can use any phase, with Core
105+
being the easiest to use.
106+
107+
:: Migration Naming Schemes
108+
109+
Here are some example migration naming schemes:
110+
111+
- Numeric, zero-padded: 0001, 0002, 0003, ...
112+
Pros: simple
113+
Cons: requires coordination if multiple people author migrations
114+
concurrently; requires new scheme if next number exceeds planned width
115+
Best for: solo projects or teams with a single migration author where the
116+
versioning scheme is unknown or subject to change
117+
118+
- Version, zero-padded: v01.00.00, v01.00.01, v01.01.00, v02.00.00, ...
119+
Pros: descriptive; aligned with versioning
120+
Cons: requires coordination if multiple people author migrations
121+
concurrently; tricky if a version number exceeds planned width
122+
Best for: solo projects or teams with a single migration author where the
123+
versioning scheme is known and unlikely to change
124+
125+
- Date and description: 2025-08-15-Initial, 2025-08-18-AddUsersTable, ...
126+
Pros: descriptive; requires less coordination for multiple authors
127+
Cons: need to keep migration name up-to-date during authoring
128+
Best for: teams with multiple migration authors
129+
130+
- Date and work item number: 2025-08-15-00042, 2025-08-18-00123, ...
131+
Pros: requires less coordination for multiple authors
132+
Cons: need to keep migration name up-to-date during authoring; requires
133+
knowing work item numbers
134+
Best for: teams with multiple migration authors where it is useful to
135+
associate migrations with work items, pull requests, etc.
136+
137+
138+
Seeds
139+
-----
140+
141+
A seed is a SQL script that populates a target database with data.
142+
143+
TODO: Describe seeds here.

0 commit comments

Comments
 (0)