Skip to content

DataStar.Tools

DataStar.Tools is used to deploy DataStar packages and can be integrated into tools such as Octopus Deploy.

DataStar.Tools is a DotNet 8 self contained application for automated deployments and can run on both Windows and Linux platforms.

  • Supports Oracle and SqlServer target databases.
  • Audit tables optional when creating reversal scripts.
  • Generate reversal scripts to Audit tables and/or NuGet packages
  • Can publish NuGet packages to a NuGet Repository.

Deployment Artifacts

When using DataStar.Tools with an automated deployment tool you will typically have 2 or 3 artifacts that are required for the release:

DataStar.Tools Package

This is available to download on the releases page as a zipped file or NuGet package format. This can be installed on the deployment agent, however the preferred option is to managed this as an artifact of the deployment as this avoids having to worry about upgrading agents with deployment tooling.

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. If using NuGet format you can add them under a "contents" folder within the package.

DataStar Deployment Package

A deployment package is normally created during a build phase and includes the following items:

  1. The scripts that are to be executed (including any static scripts is required)
  2. A manifest which lists the order in which the scripts should be run.
  3. A metadata JSON file containing additional build information, typically this would include as a user story reference and build version, but and any other metadata that might be useful can also be added.

DataStar.Tools

Once a build has been created it can be deployed using the DataStar.Tools utility. This support many options which might be a simple deployment, optionally 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.

DataStar.Tools supports running multiple manifests provided you can identify the work item from the manifest file name using regular expressions. See the work item parameter description to see how to use this feature. Note that each work item is processed in a separate transaction, therefore a failure in the deployment will only rollback the current work item being processed.

The scripts can be deployed using the DataStar.Tools.exe if running under Windows or under Linux running dotnet DataStar.Tools.dll , the options can be set in the appsettings.json (for example --log-level would be "LogLevel" in appsettings.json) or passed as arguments (please note these options are case sensitive):

DataStar.Tools.exe
Switch Switch String Type Description
-ad --audit-database String The name of the database where the audit tables reside. This only applies to SqlServer where the tables are held in a connected database.
-ae --audit-enabled Flag Enable writing details to the auditing tables, this assumes that you are using additional tables to hold the data in the summary, history and reversal tables.
-ah --audit-history String The name of the audit history table to be used, this is required if you have auditing enabled.
-ai --audit-initialize Flag Setting this flag will automatically create the audit tables if they don't exist.
-ao --audit-schema String The name of the database schema where the audit tables reside.
-ar --audit-reversal String The name of the audit reversal table to be used, this is required if you have auditing enabled.
-as --audit-summary String The name of the audit summary table to be used, this is required if you have auditing enabled.
-cn --command-name String The command to execute, this defaults to "release" which is the mode used to deploy scripts, "reversal" is the other supported command and can be specified if you want to generate a reversal package from data held in the audit database tables.
-cs --connection-string String The database connection string. For Oracle this can be the format specified by the ODP.NET connection and for SQL Server the SqlClient Data Provider. Note for Oracle there are separate flags to set the TNS Admin and Wallet Location.
-db --database String [Required] Specify the target database vendor (Oracle or Microsoft)
-dp --deploy-package String The name of the package to deploy if deploying from a nuget package file, this is an alternate where you don't want to unpack the files.
-ds --default-schema String The default schema for the deployment, this will be ignored if the templates contain a schema.
-en --environment-name String The name of the target database environment, this is used in logging the deployment and when creating packages when a package description is not provided.
-id --audit-id String Only required in "reversal" mode where you are generating a package from an existing deployment. In this case it identifies the audit record id in the database.
-lf --log-file String If specified the logging will be output to the specified file in addition to the console.
-lk --license-key String [Required] The software license key supplied by Absolute Technology.
-ll --log-level String If you wish to change the verbosity of the logging then you can specify a log level with this flag. For example 'debug' will enable debug logging.
-mr --manifest.regexp String The regular expression for matching the manifests, if not specified any file with a ".mf" suffix will be matched.
-od --output-directory String The output directory path for any outputs and/or artifacts such as reversal packages.
-pa --package-author String Optionally set the package author for any generated packages.
-pd --package-directory String The output directory to use for the output NuGet package when generating a set of reversal scripts.
-pf --package-file String The package filename to use for the output NuGet package when generating a set of reversal scripts. You can use the variables ${WorkItem} and ${Version} in your package name which will be substituted with the current values being processed.
-pi --package-invariant Flag Force a reversal package to be created even if no changes are applied, by default a reversal package will not be generated if the scripts did not apply a change.
-ph --package-header String If the API Key needs to be included in a specific header then this can be specified with the header details.
-pk --package-id String The package name to use for the output NuGet package when generating a set of reversal scripts.
-ps --package-summary String Optionally set the package summary for any generated packages.
-pu --package-uri String The Uri for publishing to a package repository.
-pv --package-version String The package version to use for the output NuGet package when generating a set of reversal scripts.
-px --package-api-key String The API key for publishing to the package repository.
-re --reversal-enabled Flag If set then reversal scripts will be generated, you must provide the template directory if this option is enabled.
-ri --reversal-id String Only required in "reversal" mode where you are generating a package from an existing deployment. In this case it identifies the reversal record id in the database.
-rt --rollback-transaction Flag If set then this will rollback the deployment. This can be useful when you want to see what changes would be made, before running with commit.
-st --statement-timeout Integer The timeout in seconds to apply to the executing statements. For SqlServer if you specify a zero value then the timeout will be indefinite.
-ta --tns-admin String Directory path to the Oracle TNS (Transparent Network Substrate) administrative file. This configuration hides details of the database connection string (host name, port number, and service name) from the data source definition and instead use an alias.
-td --template-directory String Directory path containing DataStar templates, this is required when generating reversal scripts.
-vn --version-number String The version number being released, this is required for all releases.
-wd --working-directory String The directory path where the deployment packages or manifests can be found.
-wi --work-item String The work item or user story reference, this is required for all releases. If you are deploying against multiple work items (i.e. you have a manifest file per user story) then you can set this to a regular expression that can be used to get the work item reference from the manifest file name. Regular expressions must be prefixed with @ - for example "@[A-Z]{2,}\\d+\" would extract the work item as US123456 from a file named 001-US123456.mf
-wl --wallet-location String Specifies the location of an Oracle Wallet. A Wallet can be used to have common credentials between different domains. When used correctly, it makes having passwords in the data source configuration unnecessary.
-ir --inverse-reversal Flag The default for Oracle is to generate a reversal with the scripts run in reverse order, however for Microsoft the default is to run in the original order. If making use of the version 2 templates it is recommended to set this flag for Microsoft so that the reversal scripts run in reverse order.

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")