DataStar.CmdLine [Deprecated]¶
Please Note: DataStar.CmdLine is deprecated.
It has been replaced by the DataStar.Tools utility.
Using DataStar Command Line¶
DataStar.CmdLine is a utility that can be used within your automated deployment steps to generate and save reversal scripts and deploy your built deployment packages. In order to use the DataStar.CmdLine outside of the Azure Dev Ops Tasks you will typically have 2 or 3 artifacts that are required for the release:
- The DataStar Command Line binaries and Powershell Scripts.
- The DataStar component templates (only required if using the reversal feature)
- The built deployment package.
DataStar Command Line Package¶
This is shipped with the main DataStar application, alternatively it is available via the Azure Dev Ops Marketplace packaged as a VSIX file. This can be installed into Azure Dev Ops or Team Foundation to provide access to a packaged task or alternatively unzipped to extract the DataStar.CmdLine binaries.
DataStar Component Templates¶
If you are using the DataStar Reversal Feature then you will need to package up the templates used to generate the components so that they can be used to generate the reversal scripts.
Command Line Deployment Mode¶
When a deployment file is created the information in the deployment is used to create a build. The build includes the versions of the files specified in the deployment file extracted from your version control system and a manifest file which contains a list of the relative file paths to be executed in the order listed. Typically the build is automated via you build system (for example Team Foundation Server).
Once a build has been created it can be deployed using the DataStar.CmdLine utility. This support many options which might be a simple deployment, writing an audit history to the target database and / or generating reversal scripts. If reversal is enabled then the deployment utility will generate an extract of the components immediately before executing the scripts which can then be used for a subsequent reversal of the changes.
The scripts can be deployed using the DataStar.CmdLine.exe utility, the options are show below (please note these options are case sensitive):
Switch | Switch String | Type | Description |
---|---|---|---|
-D | --deployment | Flag | Flag to indicate that you wish to run in deployment mode. |
-S | --DataSource | String | The SQL SERVER server and instance. |
-d | --InitialCatalog | String | The database name. |
-U | --Username | String | The username (if using password authentication) |
-P | --Password | String | The password (if using password authentication) |
-m | --ManifestDir | String | The deployment manifest directory. |
-A | --Artifacts | String[] | List of artifacts (manifests) to deploy, this defaults to wildcard. |
-W | --WorkItem | Integer | The work item (used for auditing purposes) |
-V | --Version | Integer | The version number (used for auditing purposes) |
-x | --Reversal | Boolean | Enable generation of reversal scripts (defaults to false) |
-T | --TemplateDir | String | The directory to the DataStar templates (the is required if generating compensation scripts) |
-C | --Commit | Boolean | Commit the changes to the database (defaults to true) |
-O | --OutputDir | String | The out put directory path (where compensation scripts are generated) |
-k | --key | String | The DataStar license key. |
-b | --Debug | Flag | Enable debug level logging. |
-t | --Trace | Flag | Enable trace level logging |
Flag = No value expected after the switch
String = Argument after the switch is expected to be a string
Integer = Argument after the switch is expected to be an integer
Boolean = Argument after the switch is expected to be a Boolean ("true" or "false")
Executing With PowerShell¶
The DataStar command line tools are supplied with some utility PowerShell scripts which can either be used directly or customized if required. An example of executing the reversal using the DataStar.CmdLine.ps1 is shown below:
DataStar.CmdLine.ps1
-BasePath "$(Basepath)"
-ModeSwitch "$(ModeSwitch)"
-ManifestDir "$(ManifestDir)"
-DataSource "$(DataSource)"
-Database "$(Database)"
-Username "$(DatabaseUser)"
-Password "$(DatabasePassword)"
-OutputDir "$(OutputDirectory)"
-TemplateDir "$(TemplateDirectory)"
-WorkItem "$(WorkItem)"
-Version "$(Version)"
-LicenseKey "$(LicenseKey)"
-WithReversal
Command Line Reversal Mode¶
When deploying your changes to an environment, DATASTAR can generate a the reversal scripts from the database you are deploying to and store these in audit tables in the database or to an output directory. The advantage of the reversal scrips is they provide the ability to revert the changes without having to prepare and maintain rollback scripts which may be out of date by the time you deploy.
If you have generated the reversal scripts in the database you can use the DataStar.CmdLine.exe utility to extract these scripts and execute, the options are show below (please note these options are case sensitive):
Switch | Switch String | Type | Description |
---|---|---|---|
-R | --reverse | Flag | Flag to indicate that you wish to run in reverse mode. |
-S | --DataSource | String | The SQL SERVER server and instance. |
-d | --InitialCatalog | String | The database name. |
-U | --Username | String | The username (if using password authentication) |
-P | --Password | String | The password (if using password authentication) |
-m | --ManifestDir | String | The deployment manifest directory. |
-W | --WorkItem | Integer | The work item (used for auditing purposes) |
-V | --Version | Integer | The version number (used for auditing purposes) |
-x | --Reversal | Boolean | Enable generation of reversal scripts (defaults to false) |
-T | --TemplateDir | String | The directory to the DataStar templates (the is required if generating compensation scripts) |
-C | --Commit | Boolean | Commit the changes to the database (defaults to true) |
-O | --OutputDir | String | The out put directory path (where reversal scripts are generated) |
-k | --key | String | The DataStar license key. |
-b | --Debug | Flag | Enable debug level logging. |
-t | --Trace | Flag | Enable trace level logging |
Flag = No value expected after the switch
String = Argument after the switch is expected to be a string
Integer = Argument after the switch is expected to be an integer
Boolean = Argument after the switch is expected to be a Boolean ("true" or "false")
Executing With PowerShell¶
The DataStar command line tools are supplied with some utility PowerShell scripts which can either be used directly or customized if required. An example of executing the reversal using the DataStar.CmdLine.ps1 is shown below:
DataStar.CmdLine.ps1
-BasePath "$(BasePath)"
-ModeSwitch "$(ModeSwitch)"
-ManifestDir "$(Manifests)"
-DataSource "$(DataSource)"
-Database "$(Database)"
-Username "$(DatabaseUser)"
-Password "$(DatabasePassword)"
-OutputDir "$(OutputDirectory)"
-TemplateDir "$(TemplateDirectory)"
-WorkItem "$(WorkItem)"
-Version "$(Version)"
-LicenseKey "$(LicenseKey)"
-WithReversal
Command Line Deployment History Mode¶
If you have enabled the database audit table and the optional reversal table, then the deployment logs and reversal scripts will be logged to the database. This data is stored as base 64 binary zipped files. This data can be extracted in two ways as described below.
Database Extract¶
If you are using SQL SERVER 2016 or above then you can select the data directly from the database as shown below:
Command Line Extract¶
The data cab be extracted using the DataStar.CmdLine.exe utility, the options are show below (please note these options are case sensitive):
DataStar.CmdLine.exe --history --DataSource "SERVER01\SQLSERVER" --InitialCatalog "DEV" --WorkItem 574632 --Reversal true --OutputDir "C:\Output"
Switch | Switch String | Type | Description | Required |
---|---|---|---|---|
-H | --history | Flag | Flag to indicate that you wish to extract the audit history. | Yes |
-S | --DataSource | String | The SQL SERVER server and instance. | Yes |
-d | --InitialCatalog | String | The database name. | No |
-U | --Username | String | The username (if using password authentication) | No |
-P | --Password | String | The password (if using password authentication) | No |
-W | --WorkItem | Integer | The work item (not required if History Id specified), this automatically select most recent entry for the Work Item. | No |
-x | --Reversal | Boolean | Extract the reversal scripts (defaults to false) | No |
-l | --LogOutput | Boolean | Extract the log output (defaults to true) | No |
-O | --OutputDir | String | The out put directory path. | Yes |
-r | --HistoryId | Integer | The audit history id of the record to extract (not required if the WorkItem is specified) | No |
Flag = No value expected after the switch
String = Argument after the switch is expected to be a string
Integer = Argument after the switch is expected to be an integer
Boolean = Argument after the switch is expected to be a Boolean("true" or "false")