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.

SQL Server connection encryption

DataStar v3 ships with Microsoft.Data.SqlClient 6.x, which changed the default for two connection-string keys compared to the older driver bundled with v2.x:

Key	v2.x default	New driver default
Encrypt	False	Mandatory
TrustServerCertificate	False	False

Connection strings that worked under v2.x can therefore fail the TLS handshake under v3, typically against SQL Server instances that present self-signed or otherwise untrusted certificates. To smooth the upgrade, DataStar.Tools applies the v2.x defaults when the connection string sets neither key:

• If your connection string contains neither Encrypt= nor TrustServerCertificate=, DataStar.Tools appends Encrypt=False;TrustServerCertificate=True; so the connection behaves the same as under v2.x. A single Information-level log line records exactly which defaults were added.
• If you set either key explicitly, your value is used unchanged.

To force the new strict-TLS behaviour explicitly:

Server=...;Database=...;Encrypt=Mandatory;TrustServerCertificate=False;

To trust a self-signed certificate while still encrypting the connection:

Server=...;Database=...;Encrypt=Mandatory;TrustServerCertificate=True;

To match v2.x exactly (no encryption), either let the defaults apply or set both explicitly:

Server=...;Database=...;Encrypt=False;TrustServerCertificate=True;

Both Encrypt and TrustServerCertificate flow through --connection-string; no separate flags are exposed for them. In the Octopus action template, set the values in the dsr-connectionString parameter and the helper passes them through unchanged.

When a connection fails, the underlying SqlClient exception (certificate trust, authentication, name resolution, etc.) is now logged directly so the cause is visible in the deployment output, rather than a generic "Failed to connect to the Microsoft database" line as in earlier 3.0.x releases.

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.