A Utility to create safe debuggable harness for T-SQL stored procedures

Turn SQL Server stored procedures into runnable debuggable scripts for pre-production SQL Server — DML replaced with SELECT previews, nested EXEC calls replaced with PRINT stubs, variables traced with PRINT, no writes to real tables.

Python 3.10+ CLI · analyze & generate MIT License
Install from PyPI View on GitHub

What it does ?

Not a live debugger — a static harness generator you review, then run on a dev database. Output is stamped DEBUG HARNESS — DO NOT RUN ON PRODUCTION.

analyze

Inventory DML, TRY/CATCH, loops, SET statements, and line-level detail before you generate a harness.

generate

Build a debug script: stub real-table DML with SELECT previews, replace nested EXEC calls with PRINT stubs, add variable traces, strip deploy preamble, inline parameters as DECLARE.

Enterprise-ready I/O

Auto-detect UTF-16 (SSMS Unicode) and Windows-1252 encodings. Optional --log / --log-file audit trail with function names and per-line detail.

Org-style T-SQL

Handles messy SSMS exports: multi-line IF EXISTS predicates, irregular formatting, and semicolon-optional DML. Only deploy IF EXISTS … DROP PROCEDURE blocks are stripped — in-procedure checks are kept.

How it works ?

Line scanning supplements sqlglot where TRY/CATCH and complex T-SQL hide DML from the AST. Script preparation normalizes SSMS deploy wrappers before analysis or harness generation.

Nested EXEC calls. Multi-line EXEC dbo.OtherProc @a = @a, … blocks become [DBG-EXEC] comments plus PRINT lines showing the procedure name, the full runnable EXEC … command, and runtime parameter values.
Deploy preamble vs in-procedure checks. Only SSMS-style IF EXISTS (…) DROP PROCEDURE blocks at the top of the file are removed. Nested IF EXISTS (SELECT … FROM …) inside the procedure body are preserved.
⚠️ Always review generated scripts before running on a shared server. Dynamic SQL, cursors, and encrypted procedures are not fully rewritten.

Commands Available

Command Description
analyze Structural report — DML counts, TRY/CATCH, IF/WHILE, identified statements. Use --report for a plain-text file, --plain to disable ANSI colors, --full to show zero-count sections.
generate Produce *_debug.sql harness with DML SELECT previews, EXEC PRINT stubs, and variable traces
version Print installed package version

Common options

Flag Command(s) Purpose
--trace-style print|raiserror generate Variable trace output (default: print)
--keep-comments generate Keep original -- and /* */ comments
--block-markers generate Insert [DBG] Step N before IF/WHILE
--log
--log-file		 both Timestamped audit log: [datetime] [function] [LEVEL] message. DEBUG lines list each comment strip, preamble removal, DML stub, EXEC stub, and trace injection.
--quiet
-q		 generate Suppress progress on stderr (log file still receives full detail when --log is set)
--report
--plain
--full		 analyze Write a .txt report, disable terminal colors, or include empty sections
--encoding both Force utf-8, utf-16-le, cp1252, etc.
--no-stub-dml generate Traces only; leave DML unchanged (nested EXEC calls are still replaced with PRINT stubs)

Installation and Quick Start

Requires Python 3.10+ or newer.

Step 1. Install the package

pip install sql-sp-harness

If pip is not on PATH:

pip3 install sql-sp-harness

Step 2. Verify installation (console script)

sql-sp-harness version

Or via module:

python3 -m sql_sp_harness version

Step 3. Analyze or generate a harness

sql-sp-harness analyze -i MyProc.sql
sql-sp-harness generate -i MyProc.sql -o MyProc_debug.sql

Or via module:

python3 -m sql_sp_harness analyze -i MyProc.sql
python3 -m sql_sp_harness generate -i MyProc.sql -o MyProc_debug.sql

Optional. Write a step log beside the input file

sql-sp-harness generate -i MyProc.sql -o MyProc_debug.sql --log

Console: sql-sp-harness (alias sp-harness) · Module: sql_sp_harness. Windows: add %LocalAppData%\Programs\Python\Python3x\Scripts to PATH if the console command is not found.

Limitations

Pattern Behavior
Dynamic SQL Not analyzed or rewritten
Encrypted procedures No source available
Cursors Not rewritten
DDL inside proc Not stubbed
Dynamic EXEC EXEC(@sql) and sp_executesql are not rewritten
Nested EXEC calls Replaced with [DBG-EXEC] PRINT stubs (procedure, command, parameter values)
SSMS deploy preamble IF EXISTS … DROP PROCEDURE and SET ANSI_NULLS / QUOTED_IDENTIFIER removed; in-procedure IF EXISTS kept

Not affiliated with Microsoft. “SQL Server” and T-SQL are used descriptively only.