ItTiger.TigerSqlCmd 0.8.3

TigerQuery

<img src="docs/assets/TigerQuery256.png" alt="TigerQuery Logo" width="80"/>

TigerQuery is a lightweight SQL script engine and parser with familiar sqlcmd and SSMS SqlCmd-mode scripting, plus SqlCmdEx: an extended mode for applications and automation that protects host-provided variables from script-level :setvar overrides.

It powers tiger-sqlcmd, a modern CLI for executing complex .sql scripts with repeatable batches, variable injection, and advanced scripting features.

Documentation

Read the published TigerQuery documentation.

🧠 Philosophy

TigerQuery is not a clone of sqlcmd.
It’s a deliberate reimplementation — compatible where it matters, safer where it should be, and documented with precision.

Unlike sqlcmd or SSMS, TigerQuery:

• Has a dedicated, composable parser
• Tracks batch structure and execution metadata
• Is fully test-covered and intentionally divergent where appropriate

✨ Features

• ✅ Familiar :setvar, $(var), :on error, and GO [n] handling, including sqlcmd-compatible stop-on-error for severity 11-16 server errors
• ✅ SqlCmdEx protected host variables for automation and embedded tooling
• ✅ Fully async parser and execution engine
• ✅ Tracks exact line/column metadata per batch
• ✅ Structured error handling via TigerQueryException
• ✅ Differentiates between sqlcmd, sqlcmdex, and normal modes
• ✅ Easily embeddable in CLI tools or .NET apps

🔐 SqlCmdEx: protected variables for applications

SqlCmdEx is TigerQuery’s extended scripting mode for applications and automation. It keeps familiar sqlcmd script syntax while allowing the host application to provide protected variables that scripts cannot override with :setvar.

Variable names are matched case-insensitively. For example, this script tries to replace TargetDatabase:

:setvar TargetDatabase ScriptDatabase
PRINT 'Deploying $(TargetDatabase)';
GO

The host can protect its value by selecting SqlCmdEx:

using System;
using System.Collections.Generic;
using ItTiger.TigerQuery;
using ItTiger.TigerQuery.Engine;

const string script = """
    :setvar TargetDatabase ScriptDatabase
    PRINT 'Deploying $(TargetDatabase)';
    GO
    """;

var options = new TigerQueryEngineOptions
{
    ConnectionString =
        "Server=localhost;Database=master;Integrated Security=true;TrustServerCertificate=true",
    Mode = SqlCmdMode.SqlCmdEx,
    Variables = new Dictionary<string, string>
    {
        ["TargetDatabase"] = "HostDatabase"
    },
    OnMessage = (message, _) => Console.WriteLine(message.Text)
};

await new TigerQueryEngine(options).RunFromStringAsync(script);
// PRINT reports: Deploying HostDatabase

This is useful for deployment automation, test orchestration, code generation, database provisioning, and applications that inject environment or project values into reusable scripts without allowing accidental overrides.

See SqlCmd and SqlCmdEx in the hosted documentation for the detailed precedence rules.

Prepared and streaming execution

SqlCmdEx works with both execution modes. Streaming is the memory-efficient default; prepared execution parses the complete TigerQuery/sqlcmd structure before opening the SQL connection. Mode selection and execution timing are independent choices.

See prepared versus streaming execution for the trade-offs.

🧪 Tests = Documentation

TigerQuery uses a structured unit test suite to document:

• 🔍 Known compatibility issues
• 💡 Intentional differences from sqlcmd or SSMS
• 🧪 Parser edge cases, whitespace behavior, comment handling
• 🧠 Design decisions that prioritize clarity over legacy quirks

See:

• SqlCmdParserKnownIssues
• SqlCmdParserIntentionalDifferences

🚀 Quickstart with tiger-sqlcmd

tiger-sqlcmd run -c local -m sqlcmdex -f script.sql

Here, local is a saved connection managed with tiger-sqlcmd connections. The run command supports -v name=value for variables, --verbosity, --log-level, and more. Route result sets to TigerQuery's built-in CSV writer with -o/--output:

tiger-sqlcmd run -c local -f script.sql -o results.csv

Use --output-mode FilePerResultSet for generated per-result-set files, -e/--error-output for SQL errors, and --out-behavior to choose whether :Out also redirects normal messages. See the result output routing feature guide for the complete CLI, API, CSV, overwrite, naming, encoding, and partial-file contract.

Choosing a connection store

Saved connections live in a per-user JSON store shared across Tiger tools. A single run can point somewhere else — a scratch store, a CI workspace, a container mount — without touching that default:

tiger-sqlcmd connections list --tq-connection-store-file /tmp/scratch.json
export TIGERQUERY_CONNECTION_STORE_FILE=/workspace/runtime/connections.json

The command-line option wins over the environment variable, which wins over the application default. A store path that is supplied but unusable fails the run rather than quietly falling back, so a mistyped CI path can never send a job to a developer's personal store. The option is app-wide in meaning but still an option, so write it after the command path and any positionals; use --tq-connection-store-file=<path> when the path begins with -. See selecting the connection store.

📦 Installation

NuGet packages

dotnet add package ItTiger.TigerQuery

dotnet add package ItTiger.TigerQuery.Core

dotnet add package ItTiger.TigerQuery.CliCore

tiger-sqlcmd CLI

Install the tiger-sqlcmd .NET tool globally:

dotnet tool install --global ItTiger.TigerSqlCmd

For a repository-local installation, create or reuse a tool manifest and install the same package locally:

dotnet new tool-manifest
dotnet tool install --local ItTiger.TigerSqlCmd
dotnet tool run tiger-sqlcmd --help

Update or remove the global tool with:

dotnet tool update --global ItTiger.TigerSqlCmd
dotnet tool uninstall --global ItTiger.TigerSqlCmd

For a local manifest, replace --global with --local. A Windows installer is also distributed through GitHub releases. See the release guide for local package and installer builds and validation.

🔧 Status

TigerQuery v0.8.3 is a snapshot release — not issue-free, but stable, tested, and ready to use.

It is meant as a transparent, inspectable tool — bugs and all.
The test suite tracks known issues, documents differences, and protects your upgrade path.

🛡️ Copyright & Project Sponsor

<p align="left"> <img src="docs/assets/ItTiger-head.png" alt="IT Tiger Logo" width="120"/> </p>

TigerQuery is an open-source project by IT Tiger
🔗 Project page: https://www.ittiger.net/projects/tigerquery/
🔗 https://www.ittiger.net/