Skip to content

Add SQLCMD mode auto-detection for query execution - #2848

Draft
Benjin Dubishar (Benjin) wants to merge 2 commits into
mainfrom
dev/benjin/sqlcmdAutoDetect
Draft

Benjin Dubishar (Benjin) wants to merge 2 commits into
mainfrom
dev/benjin/sqlcmdAutoDetect

Conversation

@Benjin

@Benjin Benjin Dubishar (Benjin) commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds optional auto-detection of SQLCMD syntax for query execution. When enabled, STS checks the text being executed and runs that execution in SQLCMD mode if it contains SQLCMD syntax. Otherwise it runs normally. The decision applies only to that execution run.

Contract

  • Request: ExecuteRequestParamsBase.AutoDetectSqlCmdMode (bool?, JSON autoDetectSqlCmdMode). It applies to query/executeDocumentSelection, query/executeString and query/executedocumentstatement.
    • SQLCMD mode is on if isSqlCmdMode is true, or if it is omitted and the query execution settings enable SQLCMD mode.
    • Otherwise, including when isSqlCmdMode is explicitly false, STS inspects the text being executed (document, selection or statement) when autoDetectSqlCmdMode is true.
    • When the flag is absent or false, behavior is unchanged.
  • Response: ExecuteRequestResult.IsSqlCmdMode (bool, JSON isSqlCmdMode) reports whether the execution actually runs in SQLCMD mode, whether it was requested, enabled in settings or auto-detected. Clients that ignore the field are unaffected.

Detection (SqlCmdSyntaxDetector.ContainsSqlCmdSyntax, in ManagedBatchParser)

  • SQLCMD commands are recognized with the existing batch parser Lexer: :setvar, :r, :on error, :connect, :!!, :exit, :out, and the other recognized commands. Because it reuses the lexer, commands inside string literals or comments, ::fn_... and GO [n] are not detected.
  • $(identifier) variable references are detected in code, [...] and "...", but not inside single-quoted string literals or comments.
  • Malformed scripts, such as an unterminated string, are treated as not SQLCMD and are left to the regular parser to report.
  • A cheap pre-check runs first: the lexer runs only if some line starts (after optional whitespace) with : or the script contains $(. The lexer only recognizes commands at that position, so results are unchanged, but scripts whose colons are all mid-line (time literals, comments, :: calls) skip the full lex.

Performance

Detection cost compared with the batch parse Query already does (BatchParserWrapper.GetBatches). Overhead is relative to the parse that actually runs: regular mode for a/b, SQLCMD mode for c/d. Release build, Apple M4 Pro, .NET 10; median of 11–101 warmed-up runs.

Case 1 KB 10 KB 100 KB 1 MB 5 MB
a: no : or $( 0.1 µs (0.7%) 1.0 µs (0.9%) 9.7 µs (0.9%) 99 µs (0.9%) 0.51 ms (0.8%)
b: mid-line : only, not SQLCMD 0.4 µs (2.2%) 1.8 µs (1.7%) 20 µs (1.9%) 187 µs (1.5%) 1.01 ms (1.6%)
c: :setvar on line 1 0.2 µs (1.0%) 0.8 µs (0.6%) 6.9 µs (0.6%) 69 µs (0.5%) 0.33 ms (0.5%)
d1: :setvar only at the end 15 µs (76%) 87 µs (74%) 0.86 ms (73%) 8.9 ms (71%) 42.7 ms (62%)
d2: $(var) only at the end 15 µs (30%) 86 µs (61%) 0.84 ms (78%) 8.5 ms (73%) 42.2 ms (72%)

The 1 KB scripts for b, c and d are about 2 KB, because one generated block is bigger than 1 KB. Case c was measured before the final reorder of the pre-check, so line-1 SQLCMD should now cost less than shown. Without the pre-check, case b cost 62–82% (43.6 ms at 5 MB). Case d still needs a full lex, but only for scripts that really are SQLCMD and are only run in SQLCMD mode because of autoDetectSqlCmdMode. The parse itself takes about 12–14 ms per MB.

Client counterpart: vscode-mssql adds a new auto value for mssql.query.defaultSqlCmdMode. It sends the autoDetectSqlCmdMode request flag and reads the isSqlCmdMode result field.

Code Changes Checklist

  • New or updated unit tests added
  • All existing tests pass (dotnet test)
  • Code follows contributing guidelines
  • Logging/telemetry updated if relevant
  • No protocol or behavioral regressions

Validation:

  • dotnet test --filter "FullyQualifiedName~SqlCmdSyntaxDetectorTests|FullyQualifiedName~QueryExecution.Execution.ServiceIntegrationTests" in test/Microsoft.SqlTools.ServiceLayer.UnitTests: passed (75/75)
  • dotnet test --no-build --filter "FullyQualifiedName~ServiceLayer.UnitTests.QueryExecution|FullyQualifiedName~EditData" in test/Microsoft.SqlTools.ServiceLayer.UnitTests: passed (753/753), run on the first commit
  • Not run: the full dotnet test suite, integration tests, and end-to-end testing with vscode-mssql.

Reviewers: Please read our reviewer guidelines

Adds an optional autoDetectSqlCmdMode flag to execute requests. When SQLCMD
mode isn't otherwise enabled, STS inspects the text being executed and runs
that execution in SQLCMD mode if it contains SQLCMD syntax. The execute
response now reports isSqlCmdMode for the run.
…esent

SQLCMD commands are only recognized at a colon that starts a line, and variable
references always contain $(. Checking for these first avoids a full lex for
scripts that only contain mid-line colons (time literals, comments, :: calls).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant