Skip to content

Commit 12342f0

Browse files
sharpjssharpjs
committed
Add help for Get-SqlMigrations.
1 parent 06b5a88 commit 12342f0

2 files changed

Lines changed: 211 additions & 4 deletions

File tree

‎PSql.Deploy/Commands/GetSqlMigrationsCommand.cs‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ namespace PSql.Deploy.Commands;
1919
public sealed class GetSqlMigrationsCommand : AsyncPSCmdlet
2020
{
2121
/// <summary>
22-
/// <b>-Path:</b> TODO
22+
/// <b>-Path:</b> Path to a directory containing database source code in
23+
/// the layout expected by PSql.Deploy. The default is the current
24+
/// directory.
2325
/// </summary>
2426
[Parameter(
2527
ParameterSetName = "Path",
@@ -40,10 +42,10 @@ public sealed class GetSqlMigrationsCommand : AsyncPSCmdlet
4042
#endif
4143

4244
/// <summary>
43-
/// <b>-Target:</b> TODO
45+
/// <b>-Target:</b> Object specifying how to connect to the database.
4446
/// </summary>
4547
/// <remarks>
46-
/// Target | SqlContext | string
48+
/// string | SqlContext | SqlTargetDatabase
4749
/// </remarks>
4850
[Parameter(
4951
ParameterSetName = "Target",
@@ -55,7 +57,9 @@ public sealed class GetSqlMigrationsCommand : AsyncPSCmdlet
5557
public SqlTargetDatabase? Target { get; set; }
5658

5759
/// <summary>
58-
/// <b>-MinimumName:</b> TODO
60+
/// <b>-MinimumName:</b> Minimum name of migration to return, or
61+
/// <see langword="null"/> to to return all migrations registered on the
62+
/// target database. The default is <see langword="null"/>.
5963
/// </summary>
6064
[Parameter(ParameterSetName = "Target")]
6165
[AllowNull, AllowEmptyString]

‎PSql.Deploy/en-US/PSql.Deploy.dll-help.xml‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
<?xml version="1.0" encoding="utf-8" ?>
2+
<helpItems schema="maml"
3+
xmlns="http://msh"
4+
xmlns:maml="http://schemas.microsoft.com/maml/2004/10"
5+
xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10"
6+
xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
7+
<!--
8+
Copyright Subatomix Research Inc.
9+
SPDX-License-Identifier: MIT
10+
11+
Documentation:
12+
https://learn.microsoft.com/en-us/powershell/scripting/developer/help/how-to-create-the-cmdlet-help-file
13+
-->
14+
15+
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
16+
<!-- Connect-Sql -->
17+
18+
<command:command>
19+
20+
<command:details>
21+
<command:name>Get-SqlMigrations</command:name>
22+
<command:verb>Get</command:verb>
23+
<command:noun>SqlMigrations</command:noun>
24+
<maml:description>
25+
<maml:para>Lists database schema migrations.</maml:para>
26+
</maml:description>
27+
</command:details>
28+
29+
<maml:description>
30+
<maml:para>
31+
The Get-SqlMigrations cmdlet retrieves a list of database schema migrations from either a filesystem location or a target database.
32+
</maml:para>
33+
<maml:para>
34+
When used with the -Path parameter, this cmdlet lists the migrations defined within the specified source directory. The source directory must conform to the following layout:
35+
</maml:para>
36+
<maml:para>
37+
foo\ The source directory: a set of migrations and
38+
│ seeds for one database. The name can vary.
39+
│
40+
├─ Migrations\ Migrations for one database.
41+
│ │
42+
│ ├─ v1.2.3\ One migration. The name can vary.
43+
│ │ │
44+
│ │ ├─ _Main.sql Top-level script for the migration. It can
45+
│ │ │ include other files with the :r directive.
46+
│ │ ├─ FileA.sql Example file included by _Main.sql.
47+
│ │ ├─ FileB.sql Example file included by _Main.sql.
48+
│ │ └─ ... More files, subdirectories, etc.
49+
│ │
50+
│ └─ ... More migrations.
51+
│
52+
├─ Seeds/ Content seeds for the database (optional).
53+
│
54+
└─ ... PSql.Deploy does not care about other files or
55+
directories present in the source directory.
56+
</maml:para>
57+
<maml:para>
58+
Each subdirectory of {source-directory}\Migrations containing a _Main.sql file is presumed to be a migration. The name of the subdirectory is the name of the migration. Migration discovery is not recursive; only one level of subdirectories is examined. Migration order is by case-insensitive ordinal comparison of the migration names.
59+
</maml:para>
60+
<maml:para>
61+
Migrations named _Begin or _End, if present, are special pseudo-migrations intended for setup and teardown scripts. They execute during every migration application session, before and after any other migrations, respectively.
62+
</maml:para>
63+
<maml:para>
64+
When used with the -Target parameter, this cmdlet lists the migrations already applied to the target database. The optional -MinimumName parameter excludes applied migrations with names lesser/earlier than the specified name.
65+
</maml:para>
66+
<maml:para>
67+
For each migration discovered, this cmdlet outputs a Migration object with Name, Path, and other properties.
68+
</maml:para>
69+
</maml:description>
70+
71+
<command:syntax>
72+
73+
<!-- ParameterSetName: Path -->
74+
<command:syntaxItem>
75+
<maml:name>Get-SqlMigrations</maml:name>
76+
<command:parameter required="false" position="0" pipelineInput="True (ByValue)" globbing="false">
77+
<maml:name>Path</maml:name>
78+
<command:parameterValue required="true">string</command:parameterValue>
79+
</command:parameter>
80+
</command:syntaxItem>
81+
82+
<!-- ParameterSetName: Target -->
83+
<command:syntaxItem>
84+
<maml:name>Get-SqlMigrations</maml:name>
85+
<command:parameter required="true" position="0" pipelineInput="True (ByValue)" globbing="false">
86+
<maml:name>Target</maml:name>
87+
<command:parameterValue required="true">string | PSql.SqlContext | PSql.Deploy.SqlTargetDatabase</command:parameterValue>
88+
</command:parameter>
89+
<command:parameter required="false" position="named" pipelineInput="False" globbing="false">
90+
<maml:name>MinimumName</maml:name>
91+
<command:parameterValue required="true">string</command:parameterValue>
92+
</command:parameter>
93+
</command:syntaxItem>
94+
95+
</command:syntax>
96+
97+
<command:parameters>
98+
99+
<!-- -Path -->
100+
<command:parameter required="false" position="0" pipelineInput="True (ByValue)" globbing="false" aliases="PSPath">
101+
<maml:name>Path</maml:name>
102+
<maml:description>
103+
<maml:para>Path to a directory containing database source code in the layout expected by PSql.Deploy. The default is the current directory.</maml:para>
104+
</maml:description>
105+
<command:parameterValue required="true">string</command:parameterValue>
106+
<dev:type>
107+
<maml:name>System.String</maml:name>
108+
</dev:type>
109+
<dev:defaultValue>$PWD</dev:defaultValue>
110+
</command:parameter>
111+
112+
<!-- -Target -->
113+
<command:parameter required="true" position="0" pipelineInput="True (ByValue)" globbing="false" aliases="none">
114+
<maml:name>Target</maml:name>
115+
<maml:description>
116+
<maml:para>Object specifying how to connect to the database. Accepts the following types of object:</maml:para>
117+
<maml:para><!-- blank line --></maml:para>
118+
<maml:list>
119+
<maml:listItem>
120+
<maml:para>string a SqlClient connection string</maml:para>
121+
</maml:listItem>
122+
<maml:listItem>
123+
<maml:para>PSql.SqlContext returned by the PSql New-SqlContext cmdlet</maml:para>
124+
</maml:listItem>
125+
<maml:listItem>
126+
<maml:para>PSql.Deploy.SqlTargetDatabase obtained by casting or construction</maml:para>
127+
</maml:listItem>
128+
</maml:list>
129+
</maml:description>
130+
<command:parameterValue required="true">string | PSql.SqlContext | PSql.Deploy.SqlTargetDatabase</command:parameterValue>
131+
<dev:type>
132+
<maml:name>System.String | PSql.SqlContext | PSql.Deploy.SqlTargetDatabase</maml:name>
133+
</dev:type>
134+
<dev:defaultValue>None</dev:defaultValue>
135+
</command:parameter>
136+
137+
<!-- -MinimumName -->
138+
<command:parameter required="false" position="named" pipelineInput="False" globbing="false">
139+
<maml:name>MinimumName</maml:name>
140+
<maml:description>
141+
<maml:para>Minimum name of migration to return, or $null to to return all migrations registered on the target database. The default is $null.</maml:para>
142+
</maml:description>
143+
<command:parameterValue required="true">string</command:parameterValue>
144+
<dev:type>
145+
<maml:name>System.String</maml:name>
146+
</dev:type>
147+
<dev:defaultValue>$null</dev:defaultValue>
148+
</command:parameter>
149+
150+
</command:parameters>
151+
152+
<command:inputTypes>
153+
<command:inputType>
154+
<dev:type>
155+
<maml:name>string</maml:name>
156+
</dev:type>
157+
<maml:description>
158+
<maml:para>A SqlClient connection string specifying how to connect to a target database.</maml:para>
159+
</maml:description>
160+
</command:inputType>
161+
<command:inputType>
162+
<dev:type>
163+
<maml:name>PSql.SqlContext</maml:name>
164+
</dev:type>
165+
<maml:description>
166+
<maml:para>An object specifying how to connect to a target database. Obtain via the New-SqlContext cmdlet.</maml:para>
167+
</maml:description>
168+
</command:inputType>
169+
<command:inputType>
170+
<dev:type>
171+
<maml:name>PSql.Deploy.SqlTargetDatabase</maml:name>
172+
</dev:type>
173+
<maml:description>
174+
<maml:para>An object specifying how to connect to a target database. Obtain by casting a string or SqlContext, via a [PSql.Deploy.SqlTargetDatabase]::new(...) construtor, or from the Targets property of a database group object returned by the New-SqlTargetDatabaseGroup cmdlet.</maml:para>
175+
</maml:description>
176+
</command:inputType>
177+
</command:inputTypes>
178+
179+
<command:returnValues>
180+
<command:returnValue>
181+
<dev:type>
182+
<maml:name>PSql.Deploy.Migrations.Migration</maml:name>
183+
</dev:type>
184+
<maml:description>
185+
<maml:para>A database schema migration.</maml:para>
186+
</maml:description>
187+
</command:returnValue>
188+
</command:returnValues>
189+
190+
<maml:relatedLinks>
191+
<maml:navigationLink>
192+
<maml:linkText>PSql:</maml:linkText>
193+
<maml:uri>https://github.com/sharpjs/PSql</maml:uri>
194+
</maml:navigationLink>
195+
<maml:navigationLink>
196+
<maml:linkText>PSql.Deploy:</maml:linkText>
197+
<maml:uri>https://github.com/sharpjs/PSql.Deploy</maml:uri>
198+
</maml:navigationLink>
199+
</maml:relatedLinks>
200+
201+
</command:command>
202+
203+
</helpItems>

0 commit comments

Comments
 (0)