A VS Code extension that rewrites T-SQL stored procedures into safe, read-only
debug scripts — so you can see what a procedure would do before you ever risk running
it for real.
Overview
Stored procedures are hard to reason about from a script diff alone. You can read a
CREATE PROCEDURE statement top to bottom and still not be
fully certain which rows an UPDATE will touch, or what a
nested transaction will actually commit, until it's already run.
SQL Debug Harness statically rewrites a T-SQL stored procedure so that every statement
with side effects becomes a read-only preview — runnable against a real connection,
including production-adjacent ones, without writing anything. The engine is TypeScript
and runs in-process; no Python required.
What’s new in 0.0.5
Compare: toolbar toggle highlights additions and removals between
source and debug script (banner, blanks, and non-
[DBG] comments filtered).
Activity Log: Level / Function / Message columns with color badges
and per-level filters (All / None).
Workbench preview — analyze a procedure and generate a debug harness in VS Code.
Examples
These are representative excerpts of what Generate Debug Script produces. Banner comments
and step-log lines are omitted for clarity.
Durable-table DML → SELECT preview
Real-table INSERT /
UPDATE /
DELETE become read-only previews.
Procedure parameters become one continuous
DECLARE;
AS BEGIN / outer
END are stripped.
Input
CREATE PROCEDURE dbo.usp_SimpleDml
@Id INT,
@Name NVARCHAR(100)
AS
BEGIN
INSERT INTO dbo.Items (Id, Name)
VALUES (@Id, @Name);
UPDATE dbo.Items
SET Name = @Name WHERE Id = @Id;
END
Harness
-- [DBG] Harness: was CREATE PROCEDURE dbo.usp_SimpleDml
DECLARE @Id INT = NULL, -- TODO: set test value
@Name NVARCHAR(100) = NULL; -- TODO: set test value
-- [DBG-PREVIEW] Would have executed:
SELECT N'INSERT to table dbo.Items' AS [DBG_Action],
@Id AS [@Id], @Name AS [@Name];
-- [DBG-PREVIEW] Would have executed:
SELECT N'UPDATE to table dbo.Items' AS [DBG_Action],
@Name AS [@Name]
FROM dbo.Items WHERE Id = @Id;
Temp tables stay live
#temp /
##temp (and table-variable) DML is left intact
because it does not write durable user tables. Only
dbo.Items is previewed.
Input
CREATE PROCEDURE dbo.usp_Temp
@Id INT
AS
BEGIN
CREATE TABLE #Temp (Id INT);
INSERT INTO #Temp (Id) VALUES (@Id);
INSERT INTO dbo.Items (Id) VALUES (@Id);
END
Harness
DECLARE @Id INT = NULL; -- TODO: set test value
CREATE TABLE #Temp (Id INT);
INSERT INTO #Temp (Id) VALUES (@Id);
-- [DBG-PREVIEW] Would have executed:
SELECT N'INSERT to table dbo.Items' AS [DBG_Action],
@Id AS [@Id];
Bare IF / ELSE + variable traces
When a branch is a single SET without
BEGIN…END, the harness
wraps the assignment and its default
SELECT trace so the branch stays valid.
Input
IF @Var1 >= 0
SET @Var2 = 1
ELSE
SET @Var2 = 0
Harness
IF @Var1 >= 0
BEGIN
SET @Var2 = 1
SELECT 'DBG' [NOTES], @Var2 [Var2];
END
ELSE
BEGIN
SET @Var2 = 0
SELECT 'DBG' [NOTES], @Var2 [Var2];
END
Trace styles
Controlled by spDebug.traceStyle.
Default is select;
printCombined folds multi-variable assignments
into one PRINT.
SET @A = 1;
PRINT CONCAT(N'[DBG] @A = ', CAST(@A AS NVARCHAR(4000)));
SELECT @B = 2, @C = 3;
PRINT CONCAT(
N'[DBG] @B = ', CAST(@B AS NVARCHAR(4000)),
N'; @C = ', CAST(@C AS NVARCHAR(4000))
);
Problem Statement
Reviewing or testing an unfamiliar stored procedure today usually means one of a few
uncomfortable options: manually comment out the DML and hope you caught every
statement, wrap the whole thing in a transaction and remember to roll it back, or just
not test it locally and find out in staging. None of these scale well, and all of them
rely on the reviewer not making a mistake under time pressure.
SQL Debug Harness removes the manual step — the rewrite is generated automatically,
consistently, and the same way every time.
How it works
Generating a debug script is a five-step pipeline, run entirely in-process inside the
extension (hybrid AST + text scan):
1
Prepare
Strip GO batches and deploy preamble; convert
CREATE PROCEDURE parameters into
DECLAREs with TODO placeholders.
2
Detect
Durable-table INSERT,
UPDATE,
DELETE, and TCL statements are identified, along with
constructs the tool can't safely handle. Temp tables and table variables are
noted but left live.
3
Rewrite
Durable-table DML becomes equivalent SELECT
previews. TCL is neutralized so nothing can commit. Named
EXEC calls become
PRINT stubs.
4
Trace
Declared variables get traces (SELECT by default,
or PRINT /
RAISERROR). Bare
IF /
ELSE bodies are wrapped in
BEGIN…END when needed.
5
Output
You get a rewritten script plus an Analyze panel summarizing what changed and
flagging anything the tool couldn't confidently rewrite.
Beta status & limitations
beta release
The rewrite logic is covered by fixture tests, but treat generated output as a strong
starting point — sanity-check it against your own procedures before trusting it on
anything sensitive.
Not a live debugger. No breakpoints, no step-into, no live DB
connection. Dynamic SQL, cursors, WHILE,
MERGE, and OUTPUT are flagged
rather than silently mishandled. T-SQL only for v1.
Install & quick start
Requires VS Code ^1.85. No Python or PyPI package — installing the extension is the
entire setup.
From source (VSIX)
git clone https://github.com/DeeprajDeveloper/vscode-sql-debug-harness.git
cd vscode-sql-debug-harness
npm install && npm run compile && npm run package
code --install-extension dist/sql-debug-harness.vsix
Open samples/fixtures/simple_dml.sql, then right-click →
SQL Debug Harness → Generate Debug Script.
Commands live under the SQL Debug Harness submenu, activity-bar
Workbench, and Command Palette.
SQL Debug Harness ▸
Open Workbench
Generate Debug Script
Analyze Procedure
─────────────────────
Configure Settings
Open Extension Settings
In the Workbench: Select File… or Load Active, then
Analyze / Generate / Compare / Clear. Use the Save popover for analysis
.txt, debug .sql, step log,
or open debug in an editor. Filter Activity Log levels from the log toolbar.
