Class TigerQueryEngine

Namespace

ItTiger.TigerQuery.Engine

Assembly

ItTiger.TigerQuery.dll

Parses sqlcmd-style scripts and executes their logical batches sequentially against SQL Server.

public sealed class TigerQueryEngine

Inheritance

object

TigerQueryEngine

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The engine has no console output. Messages, result sets, and batch lifecycle information are delivered through TigerQueryEngineOptions callbacks. A single engine should not be used for concurrent runs because its options and callback destinations are shared.

Callbacks are synchronous. In prepared mode the order is plan-ready, then batch-start, any messages/result sets, and batch-end for each scheduled execution. Streaming mode omits plan-ready and preserves the same per-batch order.

Both modes share one batch coordinator, so error accounting, the effective :ON ERROR policy, and the batch lifecycle behave identically. A batch attempt fails when an exception is caught for it or when SQL Server reports an error of severity 11 or higher during it — including the severity 11-16 user errors the provider delivers as informational messages instead of throwing. A failing attempt increments the failed count, ends with an unsuccessful batch-end carrying a diagnostic, and, unless the effective policy is continue-on-error, stops the run without starting any later batch. The effective policy decides whether later batches run; it does not decide the outcome. Any failed attempt makes the run's ResultCode something other than Success, and a later successful batch never clears an earlier failure.

Constructors

TigerQueryEngine(TigerQueryEngineOptions)

Initializes an engine with fixed run options.

public TigerQueryEngine(TigerQueryEngineOptions options)

Parameters

options TigerQueryEngineOptions

The parsing, execution, and callback configuration.

Exceptions

ArgumentNullException

options is null.

Methods

RunAsync(TextReader, CancellationToken)

Runs SQL read from input using the configured ExecutionMode.

public Task<ExecutionResult> RunAsync(TextReader input, CancellationToken cancellationToken = default)

Parameters

input TextReader

The script reader. The engine does not dispose it.

cancellationToken CancellationToken

A token observed during parsing and execution.

Returns

Task<ExecutionResult>

A result when execution reaches the coordinator's normal result path.

Remarks

Streaming mode opens the SQL connection before parsing batches incrementally, so earlier batches can execute before a later parser error. Prepared mode parses the complete TigerQuery/sqlcmd structure before opening the connection; parser failure therefore prevents SQL execution. Prepared mode retains every expanded logical batch for the duration of the run.

Preparation does not validate T-SQL. Connection, permission, T-SQL syntax, compilation, and runtime failures remain execution-time behavior. Parser and connection-opening exceptions escape this method.

Cancellation observed while an active provider batch operation is in the engine's batch catch path produces UserCancelled. Cancellation during parsing, preparation, connection opening, between executions, or in callbacks is propagated as OperationCanceledException.

Exceptions

ArgumentNullException

input is null.

ArgumentOutOfRangeException

CommandTimeoutSeconds is negative.

TigerQueryException

TigerQuery/sqlcmd structure is malformed.

OperationCanceledException

Cancellation is observed outside an active batch provider operation.

InvalidOperationException

The configured ExecutionMode is unsupported.

RunFromFileAsync(string, Encoding?, CancellationToken)

Opens and runs a script file using the configured execution mode.

public Task<ExecutionResult> RunFromFileAsync(string path, Encoding? encoding = null, CancellationToken cancellationToken = default)

Parameters

path string

The script file path.

encoding Encoding

The fallback encoding when no byte-order mark is detected; UTF-8 by default.

cancellationToken CancellationToken

A token observed during parsing and execution.

Returns

Task<ExecutionResult>

A result when execution reaches the coordinator's normal result path.

Remarks

Byte-order marks override encoding. The file reader is disposed after the run.

Exceptions

TigerQueryException

TigerQuery/sqlcmd structure is malformed.

OperationCanceledException

Cancellation is observed outside an active batch provider operation.

RunFromStringAsync(string, CancellationToken)

Runs a script string using the configured execution mode.

public Task<ExecutionResult> RunFromStringAsync(string script, CancellationToken cancellationToken = default)

Parameters

script string

The complete script text.

cancellationToken CancellationToken

A token observed during parsing and execution.

Returns

Task<ExecutionResult>

A result when execution reaches the coordinator's normal result path.

Exceptions

TigerQueryException

TigerQuery/sqlcmd structure is malformed.

OperationCanceledException

Cancellation is observed outside an active batch provider operation.