tsql-fabric-debugger 0.3.2__py3-none-any.whl

tsql_fabric_debugger/__init__.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""tsql-fabric-debugger — step-by-step debugger for T-SQL procedures on Fabric Warehouse.
+
+The Fabric Warehouse has no T-SQL debugger: no breakpoints, no watch, no way
+to run half a procedure. This library solves that without touching the .sql:
+it parses the procedure in memory, slices the body into steps and preserves
+variable state between them (DECLARE + re-injection + statement + capture
+batch). Everything runs inside a transaction with ROLLBACK by default.
+
+Quick start:
+
+    from tsql_fabric_debugger import TSQLDebugger
+    dbg = TSQLDebugger("prd_load.sql", params={"@year": 2015},
+                       server="<endpoint>.datawarehouse.fabric.microsoft.com",
+                       database="my_warehouse")
+    dbg.list_steps(); dbg.step(); dbg.step_into(); dbg.show_vars()
+    dbg.close()   # ROLLBACK
+
+Batch mode: run_procedure(...). Scripts without CREATE PROCEDURE: run_script(...).
+"""
+
+from .connection import connect, fetch_source, kill_orphan_sessions
+from .engine import TSQLDebugger
+from .runner import diff_logs, run_procedure, run_script, summarize
+
+__version__ = "0.3.2"
+__all__ = ["TSQLDebugger", "connect", "fetch_source", "kill_orphan_sessions", "list_procedures", "diff_logs", "run_procedure", "run_script", "summarize", "__version__"]
+
+
+def __getattr__(name):
+    # lazy so `python -m tsql_fabric_debugger.introspect` does not trigger a
+    # runpy "found in sys.modules" RuntimeWarning from an eager import here
+    if name == "list_procedures":
+        from .introspect import list_procedures
+        return list_procedures
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tsql_fabric_debugger/cli.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""CLI: `tsql-debug file.sql` runs a whole procedure with a step-by-step log.
+
+Examples:
+    tsql-debug prd_load.sql --server X.datawarehouse.fabric.microsoft.com \\
+        --database my_warehouse --param @year=2015
+    tsql-debug load.sql --param @code='00123' --commit --csv log.csv --log-level full
+
+For interactive debugging (step/step_into/show_vars), use the TSQLDebugger
+class in a notebook, IPython or `python -i`.
+"""
+
+import argparse
+import re
+import sys
+
+from . import __version__
+from .parser import find_procedure, read_sql_file
+from .runner import count_errors, run_procedure, run_script, save_log_csv
+from .scanner import scan
+
+_INT_RE = re.compile(r"-?(0|[1-9]\d*)")
+_FLOAT_RE = re.compile(r"-?(0|[1-9]\d*)\.\d+")
+
+
+def _parse_param(raw):
+    """'@name=value' -> ('@name', value).
+
+    Quoted values ('...' or "...") are always strings — the way to keep
+    leading zeros, pass the literal word NULL, or force '1e5' as text.
+    Unquoted: NULL -> None; strict int/float (no leading zeros, no
+    scientific notation, no nan/inf); everything else stays a string.
+    """
+    if "=" not in raw:
+        raise argparse.ArgumentTypeError(f"Invalid parameter: {raw!r} (use @name=value)")
+    name, value = raw.split("=", 1)
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        return name, value[1:-1]
+    if value.upper() == "NULL":
+        return name, None
+    if _INT_RE.fullmatch(value):
+        return name, int(value)
+    if _FLOAT_RE.fullmatch(value):
+        return name, float(value)
+    return name, value
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="tsql-debug",
+        description="Runs a Fabric Warehouse T-SQL procedure step by step, "
+                    "with ROLLBACK at the end by default.",
+        epilog="Exit codes: 0 = no step errored; 1 = at least one step recorded an "
+               "ERROR (even when the procedure's own CATCH handled it); "
+               "2 = usage or file error.",
+    )
+    ap.add_argument("sql_file", nargs="?",
+                    help=".sql file with the CREATE PROCEDURE (or a loose script)")
+    ap.add_argument("--server", help="Warehouse SQL endpoint (or env FABRIC_TSQL_SERVER)")
+    ap.add_argument("--database", help="Warehouse name (or env FABRIC_TSQL_DATABASE)")
+    ap.add_argument("--param", action="append", type=_parse_param, default=[],
+                    metavar="@NAME=VALUE",
+                    help="test value for a parameter (repeatable); quote the value "
+                         "('00123') to force a string")
+    ap.add_argument("--commit", action="store_true",
+                    help="persist the effects (default: ROLLBACK at the end)")
+    ap.add_argument("--csv", metavar="FILE", help="save the execution log as CSV")
+    ap.add_argument("--log-level", choices=["simple", "full"], default="simple")
+    ap.add_argument("--step-timeout", type=int, metavar="SECONDS",
+                    help="per-step query timeout")
+    ap.add_argument("--kill-orphans", action="store_true",
+                    help="instead of running a file: KILL leftover debugger "
+                         "sessions (sleeping, open transaction, idle 15+ min) "
+                         "whose locks block other sessions — combine with "
+                         "--min-idle to change the threshold")
+    ap.add_argument("--min-idle", type=int, default=900, metavar="SECONDS",
+                    help="idle threshold for --kill-orphans (default 900)")
+    ap.add_argument("--lock-timeout", type=int, metavar="SECONDS",
+                    help="fail a lock-blocked step fast instead of hanging")
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    args = ap.parse_args(argv)
+
+    if args.kill_orphans:
+        from .connection import kill_orphan_sessions
+        kill_orphan_sessions(args.server, args.database,
+                             min_idle_seconds=args.min_idle)
+        return 0
+    if not args.sql_file:
+        ap.error("sql_file is required (or use --kill-orphans)")
+
+    import signal
+    # a polite kill (SIGTERM) must roll the warehouse session back: SystemExit
+    # lets run_procedure/run_script finally-blocks close the connection
+    try:
+        signal.signal(signal.SIGTERM, lambda *_: sys.exit(143))
+    except ValueError:
+        pass                     # not the main thread (embedded use)
+
+    try:
+        sql_text = read_sql_file(args.sql_file)
+    except FileNotFoundError:
+        print(f"tsql-debug: file not found: {args.sql_file}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"tsql-debug: cannot read {args.sql_file}: {exc}", file=sys.stderr)
+        return 2
+
+    if find_procedure(scan(sql_text)) is not None:
+        df = run_procedure(sql_text=sql_text, params=dict(args.param),
+                           server=args.server, database=args.database,
+                           commit=args.commit, save_csv=args.csv,
+                           log_level=args.log_level, step_timeout=args.step_timeout,
+                           lock_timeout=args.lock_timeout)
+    else:
+        print("[WARNING] no CREATE PROCEDURE found — running as a loose script "
+              "(--param and --log-level do not apply on this path).")
+        df = run_script(sql_text=sql_text, server=args.server, database=args.database,
+                        commit=args.commit, lock_timeout=args.lock_timeout)
+        if args.csv:
+            save_log_csv(df, args.csv)
+
+    return 1 if count_errors(df) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tsql_fabric_debugger/connection.py

@@ -0,0 +1,147 @@
+# -*- coding: utf-8 -*-
+"""Authenticated connection to the Fabric Warehouse (Entra ID).
+
+Two token chains, resolved automatically:
+1. Inside a Fabric notebook: the notebook's own token (notebookutils).
+2. Anywhere else (local machine, CI): AzureCliCredential — the same
+   `az login` you already use. Requires the `[local]` extra (azure-identity)
+   and the ODBC Driver 18 for SQL Server installed.
+
+Server and database can be passed as parameters or through the
+FABRIC_TSQL_SERVER and FABRIC_TSQL_DATABASE environment variables.
+"""
+
+import os
+import struct
+
+TOKEN_SCOPE = "https://database.windows.net/.default"
+SERVER_ENV = "FABRIC_TSQL_SERVER"
+DATABASE_ENV = "FABRIC_TSQL_DATABASE"
+
+
+ACCESS_TOKEN_ENV = "FABRIC_TSQL_ACCESS_TOKEN"
+
+
+def _get_token():
+    # A caller (e.g. the VS Code extension) can hand us a database access token
+    # via the environment so each short-lived process does not pay the Azure
+    # CLI cold start again — the biggest part of "connect" latency.
+    env_token = os.environ.get(ACCESS_TOKEN_ENV)
+    if env_token:
+        return env_token
+    try:
+        return notebookutils.credentials.getToken(TOKEN_SCOPE)  # noqa: F821
+    except NameError:
+        from azure.identity import AzureCliCredential
+        return AzureCliCredential().get_token(TOKEN_SCOPE).token
+
+
+def kill_orphan_sessions(server: str | None = None, database: str | None = None,
+                         min_idle_seconds: int = 900, echo=print) -> list:
+    """KILL leftover debugger sessions so their locks stop blocking everyone.
+
+    A debugger process that dies without close() (SIGKILL, crashed kernel,
+    killed test run) leaves its warehouse session sleeping with the debug
+    transaction OPEN — schema locks included, which blocks OBJECT_DEFINITION
+    and DDL for every other session until the server notices the dead TCP
+    connection (minutes). This finds sessions tagged by this library
+    (program_name 'tsql-fabric-debugger'), sleeping with an open transaction
+    and idle for at least min_idle_seconds, and KILLs them: the server rolls
+    their transaction back, releasing the locks.
+
+    CAUTION: an interactive debug someone left paused looks exactly like an
+    orphan. The default threshold (15 minutes) is a compromise — raise it on
+    shared warehouses, or only run this when you know no one is mid-debug.
+    Returns the killed session ids.
+    """
+    conn = connect(server, database, autocommit=True)
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            "SELECT session_id FROM sys.dm_exec_sessions "
+            "WHERE program_name = 'tsql-fabric-debugger' "
+            "  AND session_id <> @@SPID AND status = 'sleeping' "
+            "  AND open_transaction_count > 0 "
+            "  AND DATEDIFF(second, COALESCE(last_request_end_time, login_time), "
+            "               SYSUTCDATETIME()) >= ?;", (int(min_idle_seconds),))
+        orphans = [r[0] for r in cur.fetchall()]
+        killed = []
+        for sid in orphans:
+            try:
+                cur.execute(f"KILL {int(sid)};")
+                killed.append(sid)
+                echo(f"orphan debugger session {sid} killed — its transaction "
+                     "was rolled back by the server.")
+            except Exception as exc:
+                echo(f"session {sid} not killed: {exc}")
+        if not orphans:
+            echo("no orphan debugger sessions found.")
+        return killed
+    finally:
+        conn.close()
+
+
+def fetch_source(proc_name: str, server: str | None = None,
+                 database: str | None = None) -> str:
+    """Fetch the deployed source of a procedure straight from the warehouse.
+
+    Opens a short-lived autocommit session, reads OBJECT_DEFINITION and closes.
+    A name without schema resolves to dbo. Raises ValueError when the object
+    does not exist or the caller lacks VIEW DEFINITION permission.
+    """
+    conn = connect(server, database, autocommit=True)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT OBJECT_DEFINITION(OBJECT_ID(?));", (proc_name,))
+        row = cur.fetchone()
+        source = row[0] if row else None
+    finally:
+        conn.close()
+    if not source:
+        raise ValueError(f"{proc_name}: source not available "
+                         "(missing object or no VIEW DEFINITION permission).")
+    return source
+
+
+def connect(server: str | None = None, database: str | None = None,
+            autocommit: bool = True, lock_timeout: int | None = None):
+    """Open an authenticated (Entra ID) connection. One session = one debug.
+
+    lock_timeout (seconds): when set, a statement that waits for a lock this
+    long fails with SQL error 1222 instead of blocking forever. It does NOT
+    prevent an orphaned session from holding locks — only the server can reap
+    that — but it turns "hangs indefinitely behind an orphan" into an
+    immediate, actionable error. Applies to the whole session.
+    """
+    import pyodbc
+
+    server = server or os.environ.get(SERVER_ENV)
+    database = database or os.environ.get(DATABASE_ENV)
+    if not server or not database:
+        raise ValueError(
+            "Provide server and database (or set the "
+            f"{SERVER_ENV} and {DATABASE_ENV} environment variables)."
+        )
+
+    token = _get_token()
+    token_bytes = token.encode("utf-16-le")
+    token_struct = struct.pack(f"<I{len(token_bytes)}s", len(token_bytes), token_bytes)
+    SQL_COPT_SS_ACCESS_TOKEN = 1256
+
+    # APP= makes the debugger identifiable in sys.dm_exec_sessions.program_name
+    # during a blocking investigation; LoginTimeout bounds the connect phase
+    # (step_timeout only covers command execution).
+    conn = pyodbc.connect(
+        f"DRIVER={{ODBC Driver 18 for SQL Server}};"
+        f"SERVER={server};DATABASE={database};Encrypt=yes;"
+        f"APP=tsql-fabric-debugger;LoginTimeout=30;",
+        attrs_before={SQL_COPT_SS_ACCESS_TOKEN: token_struct},
+        autocommit=autocommit,
+    )
+    if lock_timeout is not None:
+        # a session option: must run outside pyodbc's parameterized path so it
+        # persists for the session (sp_prepexec would revert it per batch)
+        cur = conn.cursor()
+        cur.execute(f"SET LOCK_TIMEOUT {int(lock_timeout) * 1000};")
+        cur.close()
+    return conn