DataStar.Tools

DataStar.Tools is the CLI that deploys DataStar packages against a target database. It's a self-contained .NET application that runs on Windows or Linux, so any build agent that can run .NET can run it.

What it does:

• Deploys scripts from a manifest against Oracle or SQL Server.
• Optionally writes an audit trail (summary, history, and reversal tables) to the target database.
• Optionally generates reversal (rollback) scripts, either into the audit tables or as a NuGet package.
• Optionally publishes reversal packages to a NuGet repository.

Deployment artefacts

A typical release uses two or three artefacts:

• DataStar.Tools package. The CLI itself. Published on the releases page as a zip or a NuGet package. Install it once on the agent, or (recommended) deploy it as a release artefact so the deployment pulls in the right version.
• Component templates. Required if reversal is enabled. Package the templates as a NuGet package (under a contents folder is fine) so the CLI can regenerate reversal scripts.
• Deployment package. Produced by the build. Contains the scripts to run, a manifest listing the run order, and a metadata.json with build information (typically a work-item reference and version).

Running the CLI

On Windows, run DataStar.Tools.exe. On Linux, run dotnet DataStar.Tools.dll. Every flag can also be set as a property in appsettings.json, where the key is the PascalCase form of the long flag (so --log-level becomes LogLevel).

DataStar.Tools.exe [options]

Flags are case-sensitive. Multiple manifests can be processed in one run: see --work-item for the regular-expression form that extracts a work-item reference from each manifest filename. Each work item is processed in its own transaction, so a failure rolls back only the current work item, not earlier ones in the batch.

Flag reference

Target database

Switch	Long name	Type	Description
-db	--database	String	Required. Target database vendor: Oracle or Microsoft.
-cs	--connection-string	String	The database connection string. Oracle uses the ODP.NET format; SQL Server uses the SqlClient format. Oracle users should also consider --tns-admin and --wallet-location.
-en	--environment-name	String	Name of the target environment. Used in logging and as a default when a package description is not supplied.
-ds	--default-schema	String	Default schema for the deployment. Ignored if the templates specify a schema.
-ta	--tns-admin	String	Directory containing the Oracle TNS admin files. Lets the connection string use a TNS alias instead of host / port / service.
-wa	--wallet-location	String	Path to an Oracle Wallet. Used for shared credentials, so passwords don't appear in connection strings.

Deployment mode and manifest

Switch	Long name	Type	Description
-cn	--command-name	String	The command to execute. Defaults to release (run a deployment). Use reversal to generate a reversal package from existing audit data.
-wd	--working-directory	String	Directory containing the deployment packages or manifests.
-wi	--work-item	String	Work item or user-story reference. Required for all releases. For a batch of manifests, set this to a regex (prefixed with @) that extracts the work item from the filename. For example, "@[A-Z]{2,}\\d+" extracts US123456 from 001-US123456.mf.
-vn	--version-number	String	Version number being released. Required for all releases.
-mr	--manifest.regexp	String	Regex for matching manifest files. Defaults to any file with a .mf suffix.
-dp	--deploy-package	String	Name of a NuGet package to deploy, if you want to deploy directly from the package rather than from unpacked files.

Audit tables

Switch	Long name	Type	Description
-ae	--audit-enabled	Flag	Write deployment details to the audit tables (summary, history, reversal).
-ah	--audit-history	String	Name of the audit history table. Required when auditing is enabled.
-ar	--audit-reversal	String	Name of the audit reversal table. Required when auditing is enabled.
-as	--audit-summary	String	Name of the audit summary table. Required when auditing is enabled.
-ao	--audit-schema	String	Schema where the audit tables live.
-ad	--audit-database	String	Database holding the audit tables. SQL Server only, for when audit tables are in a different database from the target.
-ai	--audit-initialize	Flag	Create the audit tables automatically if they don't already exist.

Reversal and packaging

Switch	Long name	Type	Description
-re	--reversal-enabled	Flag	Generate reversal scripts alongside the deployment. Requires --template-directory.
-td	--template-directory	String	Directory containing the DataStar component templates. Required when --reversal-enabled is set.
-ir	--inverse-reversal	Flag	Run reversal scripts in reverse order. Oracle's default; recommended for SQL Server when using v2 templates.
-id	--audit-id	String	In reversal mode, identifies the audit history record to generate a package from.
-ri	--reversal-id	String	In reversal mode, identifies the reversal record to generate a package from.
-pd	--package-directory	String	Output directory for the generated reversal package.
-pf	--package-file	String	Output filename for the reversal package. Supports ${WorkItem} and ${Version} substitutions.
-pi	--package-invariant	Flag	Generate a reversal package even when no changes were applied. Off by default.
-pk	--package-id	String	Package id for the generated reversal NuGet package.
-pv	--package-version	String	Package version for the generated reversal NuGet package.
-pa	--package-author	String	Package author for the generated reversal NuGet package.
-ps	--package-summary	String	Package summary for the generated reversal NuGet package.
-pu	--package-uri	String	URI to publish the reversal package to.
-px	--package-api-key	String	API key for the package repository.
-ph	--package-header	String	Header name for the API key, if the repository expects something other than the default.

Connection and runtime

Switch	Long name	Type	Description
-st	--statement-timeout	Integer	Per-statement timeout in seconds. 0 means no timeout on SQL Server.
-rt	--rollback-transaction	Flag	Roll back the deployment after running it. Useful for dry-run verification before a real release.

Logging and output

Switch	Long name	Type	Description
-lf	--log-file	String	Also write logs to this file, in addition to the console.
-ll	--log-level	String	Log verbosity. For example, debug enables debug logging.
-od	--output-directory	String	Output directory for artefacts such as reversal packages.

Licence

Switch	Long name	Type	Description
-lk	--license-key	String	Required. The software licence key supplied by Absolute Technology.

Flag value types

Type	Meaning
Flag	No value expected after the switch.
String	A string argument follows the switch.
Integer	An integer argument follows the switch.
Boolean	true or false follows the switch.