db-agent-kit 0.2.0__py3-none-any.whl

db_agent/engines/sqlserver/cli.py

@@ -0,0 +1,265 @@
+"""Command line: db-agent sqlserver <inventory|ssrs|validate|report|version>."""
+
+from __future__ import annotations
+
+import functools
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Any, Callable, Optional
+
+import typer
+import yaml
+
+from . import SUPPORTED_SQL_SERVER, __version__, classify, outputs, report as report_mod, risks as risks_mod, ssrs as ssrs_mod, usage as usage_mod, validate as validate_mod
+from . import inventory as inventory_mod
+from .db import ConnectionConfig, DatabaseError, SafeConnection
+from .guard import GuardError, QueryGuard
+
+app = typer.Typer(add_completion=False, no_args_is_help=True, help="Read-only inventory of SQL Server and SSRS reports before an upgrade or a move to Power BI.")
+
+# ---- shared options -----------------------------------------------------------------------------
+Server = Annotated[Optional[str], typer.Option("--server", envvar="DBAGENT_SQL_SERVER", help="SQL Server host name or address.")]
+Port = Annotated[int, typer.Option("--port", envvar="DBAGENT_SQL_PORT", help="TCP port.")]
+Database = Annotated[Optional[str], typer.Option("--database", envvar="DBAGENT_SQL_DATABASE", help="Database to connect to.")]
+User = Annotated[Optional[str], typer.Option("--user", envvar="DBAGENT_SQL_USER", help="SQL login. The password comes from DBAGENT_SQL_PASSWORD or a hidden prompt.")]
+Driver = Annotated[str, typer.Option("--driver", help="pymssql (default) or odbc (Windows authentication, Entra ID).")]
+Trusted = Annotated[bool, typer.Option("--trusted", help="Windows authentication. Needs --driver odbc.")]
+Encrypt = Annotated[bool, typer.Option("--encrypt/--no-encrypt", help="Encrypt the connection.")]
+TrustCert = Annotated[bool, typer.Option("--trust-server-certificate", help="Accept a self-signed server certificate (odbc driver).")]
+Out = Annotated[Path, typer.Option("--out", help="Folder for all output files.")]
+Format = Annotated[str, typer.Option("--format", help="Comma list of: md, json, xlsx, html.")]
+
+
+def _formats(value: str) -> set[str]:
+    chosen = {f.strip().lower() for f in value.split(",") if f.strip()}
+    bad = chosen - set(outputs.FORMATS)
+    if bad:
+        raise typer.BadParameter(f"unknown format(s): {', '.join(sorted(bad))}. Choose from {', '.join(outputs.FORMATS)}.")
+    return chosen
+
+
+def _password(user: str | None, trusted: bool, env: str = "DBAGENT_SQL_PASSWORD", label: str = "SQL Server") -> str | None:
+    if trusted or not user:
+        return None
+    pw = os.environ.get(env)
+    if pw is None:
+        pw = typer.prompt(f"Password for {user} on {label}", hide_input=True)
+    return pw
+
+
+def _config(server, port, database, user, driver, trusted, encrypt, trust_cert) -> ConnectionConfig:
+    if not server:
+        raise typer.BadParameter("--server is required (or set DBAGENT_SQL_SERVER).")
+    if driver not in ("pymssql", "odbc"):
+        raise typer.BadParameter("--driver must be pymssql or odbc.")
+    if trusted and driver != "odbc":
+        raise typer.BadParameter("--trusted (Windows authentication) needs --driver odbc.")
+    if not trusted and not user:
+        raise typer.BadParameter("--user is required unless --trusted is used.")
+    return ConnectionConfig(server=server, port=port, database=database or "", user=user, password=_password(user, trusted),
+                            driver=driver, trusted=trusted, encrypt=encrypt, trust_server_certificate=trust_cert)
+
+
+def parse_conn_spec(spec: str, env_prefix: str, label: str) -> ConnectionConfig:
+    """server=host,port=1433,database=db,user=u,driver=odbc,trusted=yes,encrypt=no,trust_cert=yes
+
+    The password is never part of the spec: set <env_prefix>_PASSWORD or you will be asked."""
+    kv: dict[str, str] = {}
+    for part in spec.split(","):
+        if not part.strip():
+            continue
+        k, sep, v = part.partition("=")
+        if not sep:
+            raise typer.BadParameter(f"{label}: expected key=value pairs, got {part!r}")
+        kv[k.strip().lower()] = v.strip()
+    if "password" in kv or "pwd" in kv:
+        raise typer.BadParameter(f"{label}: do not put the password on the command line. Set {env_prefix}_PASSWORD or wait for the prompt.")
+    unknown = set(kv) - {"server", "port", "database", "user", "driver", "trusted", "encrypt", "trust_cert"}
+    if unknown:
+        raise typer.BadParameter(f"{label}: unknown key(s): {', '.join(sorted(unknown))}")
+    yes = lambda v: v.lower() in ("1", "true", "yes")  # noqa: E731
+    trusted = yes(kv.get("trusted", "no"))
+    user = kv.get("user")
+    return ConnectionConfig(
+        server=kv.get("server", ""), port=int(kv.get("port", 1433)), database=kv.get("database", ""), user=user,
+        password=_password(user, trusted, f"{env_prefix}_PASSWORD", label), driver=kv.get("driver", "pymssql"), trusted=trusted,
+        encrypt=yes(kv.get("encrypt", "yes")), trust_server_certificate=yes(kv.get("trust_cert", "no")),
+    )
+
+
+def _guarded(fn: Callable[..., Any]) -> Callable[..., Any]:
+    @functools.wraps(fn)
+    def run(*a: Any, **kw: Any) -> Any:
+        try:
+            return fn(*a, **kw)
+        except (DatabaseError, GuardError, ValueError, FileNotFoundError) as exc:
+            typer.secho(f"Error: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(1)
+
+    return run
+
+
+def _say(msg: str) -> None:
+    typer.echo(msg, err=True)
+
+
+def _done(written: list[str], out: Path) -> None:
+    typer.echo(f"Wrote to {out}:")
+    for w in written:
+        typer.echo(f"  {w}")
+
+
+# ---- commands -------------------------------------------------------------------------------------
+@app.command()
+@_guarded
+def inventory(
+    server: Server = None, port: Port = 1433, database: Database = None, user: User = None, driver: Driver = "pymssql",
+    trusted: Trusted = False, encrypt: Encrypt = True, trust_server_certificate: TrustCert = False,
+    out: Out = Path("db-agent-sqlserver-output"), format: Format = "md,json,xlsx,html",
+    databases: Annotated[Optional[str], typer.Option("--databases", help="Comma list of databases to read. Default: all user databases.")] = None,
+    include_system: Annotated[bool, typer.Option("--include-system", help="Also read master, model, msdb, tempdb.")] = False,
+    target: Annotated[int, typer.Option("--target", help="Upgrade target: 2019 or 2022.")] = 2022,
+    code: Annotated[bool, typer.Option("--code/--no-code", help="Save stored procedure and function code to modules.json.")] = True,
+) -> None:
+    """Inventory a SQL Server: version, databases, objects and upgrade risks. Metadata only."""
+    fmts = _formats(format)
+    if target not in (2019, 2022):
+        raise typer.BadParameter("--target must be 2019 or 2022")
+    cfg = _config(server, port, database, user, driver, trusted, encrypt, trust_server_certificate)
+    inv = inventory_mod.collect(cfg, [d.strip() for d in databases.split(",")] if databases else None, include_system, QueryGuard(), _say)
+    risks = [r.as_dict() for r in risks_mod.assess(inv, 15 if target == 2019 else 16)]
+    out.mkdir(parents=True, exist_ok=True)
+    written = outputs.write_inventory(out, inv, risks, fmts, code)
+    if "html" in fmts:
+        written += report_mod.write_report(out)
+    outputs.order_workbook(out)
+    _done(written, out)
+    by = {s: sum(1 for r in risks if r["severity"] == s) for s in ("high", "medium", "low")}
+    typer.echo(f"{len(inv['objects'])} database(s) read. Risks: {by['high']} high, {by['medium']} medium, {by['low']} low.")
+    if inv["warnings"]:
+        typer.echo(f"{len(inv['warnings'])} item(s) could not be collected (see inventory.md).")
+
+
+@app.command()
+@_guarded
+def ssrs(
+    server: Server = None, port: Port = 1433, database: Database = None, user: User = None, driver: Driver = "pymssql",
+    trusted: Trusted = False, encrypt: Encrypt = True, trust_server_certificate: TrustCert = False,
+    out: Out = Path("db-agent-sqlserver-output"), format: Format = "md,json,xlsx,html",
+    reportserver_db: Annotated[Optional[str], typer.Option("--reportserver-db", help="Name of the ReportServer database on --server.")] = None,
+    rdl_folder: Annotated[Optional[Path], typer.Option("--rdl-folder", help="Folder with .rdl (and .rsd, .rds) files.")] = None,
+    usage_csv: Annotated[Optional[Path], typer.Option("--usage-csv", help="Execution log exported to CSV (ExecutionLog3 columns).")] = None,
+    subscriptions_csv: Annotated[Optional[Path], typer.Option("--subscriptions-csv", help="Folder mode: subscriptions (ItemPath, DeliveryExtension, DataDriven).")] = None,
+    config: Annotated[Optional[Path], typer.Option("--config", help="Classification rules YAML (see src/db_agent/engines/sqlserver/data/classification.yaml).")] = None,
+    as_of: Annotated[Optional[str], typer.Option("--as-of", help="Count 90 and 365 days back from this date (YYYY-MM-DD). Default today.")] = None,
+    data_database: Annotated[Optional[str], typer.Option("--data-database", help="Database the reports query. Used to list the tables behind stored procedures.")] = None,
+) -> None:
+    """Inventory SSRS reports and classify each as move, review or retire."""
+    fmts = _formats(format)
+    if bool(reportserver_db) == bool(rdl_folder):
+        raise typer.BadParameter("give exactly one of --reportserver-db or --rdl-folder")
+    cfg_rules = classify.load_config(config)
+    when = datetime.strptime(as_of, "%Y-%m-%d") if as_of else None
+    out.mkdir(parents=True, exist_ok=True)
+    usage = usage_mod.load_csv(usage_csv, when) if usage_csv else None
+    if rdl_folder:
+        if not rdl_folder.is_dir():
+            raise FileNotFoundError(f"folder not found: {rdl_folder}")
+        res = ssrs_mod.from_folder(rdl_folder, usage, cfg_rules, subscriptions_csv)
+    else:
+        scfg = _config(server, port, reportserver_db, user, driver, trusted, encrypt, trust_server_certificate)
+        with SafeConnection(scfg, QueryGuard()) as conn:
+            if usage is None:
+                try:
+                    usage = usage_mod.load_executionlog(conn)
+                except DatabaseError as exc:
+                    _say(f"Usage not read from ExecutionLog3 ({str(exc)[:120]}). Reports will not be classified retire.")
+            res = ssrs_mod.from_reportserver(conn, usage, cfg_rules)
+    if data_database and server:
+        _resolve_procs(res, _config(server, port, data_database, user, driver, trusted, encrypt, trust_server_certificate))
+    written = outputs.write_ssrs(out, res, fmts)
+    if "html" in fmts:
+        written += report_mod.write_report(out)
+    outputs.order_workbook(out)
+    _done(written, out)
+    c = res["classification_counts"]
+    typer.echo(f"{res['report_count']} report(s): move {c.get('move', 0)}, review {c.get('review', 0)}, retire {c.get('retire', 0)}.")
+
+
+def _resolve_procs(res: dict[str, Any], cfg: ConnectionConfig) -> None:
+    q = "SELECT DISTINCT d.referenced_schema_name AS s, d.referenced_entity_name AS n FROM sys.sql_expression_dependencies d WHERE d.referencing_id = OBJECT_ID(%s)"
+    with SafeConnection(cfg, QueryGuard()) as conn:
+        for r in res["reports"]:
+            for proc in r["procedures"]:
+                try:
+                    rows = conn.query(q, (proc,))
+                except DatabaseError:
+                    continue
+                found = [f"{x['s'] + '.' if x['s'] else ''}{x['n']}" for x in rows if x["n"]]
+                r["tables"] = sorted(set(r["tables"]) | set(found), key=str.lower)
+    from collections import Counter
+
+    res["table_usage"] = Counter(t for r in res["reports"] for t in r["tables"]).most_common()
+
+
+@app.command()
+@_guarded
+def validate(
+    source: Annotated[str, typer.Option("--source", help="server=HOST,database=DB,user=U[,port=1433,driver=pymssql,trusted=no,encrypt=yes,trust_cert=no]. Password: DBAGENT_SOURCE_PASSWORD.")],
+    target: Annotated[str, typer.Option("--target", help="Same form. Password: DBAGENT_TARGET_PASSWORD.")],
+    reports: Annotated[Path, typer.Option("--reports", help="reports.csv written by the ssrs command (reports.json must be next to it).")],
+    params: Annotated[Optional[Path], typer.Option("--params", help="YAML with parameter values: defaults: {Name: value}; reports: {/path: {Name: value}}.")] = None,
+    allow_exec: Annotated[bool, typer.Option("--allow-exec", help="Also run datasets that call stored procedures.")] = False,
+    timeout: Annotated[int, typer.Option("--timeout", help="Seconds per query.")] = 60,
+    max_rows: Annotated[int, typer.Option("--max-rows", help="Skip a dataset that returns more rows than this.")] = 1_000_000,
+    out: Out = Path("db-agent-sqlserver-output"), format: Format = "md,json,xlsx,html",
+) -> None:
+    """Run each 'move' report's queries on the old and new server and compare counts and totals."""
+    fmts = _formats(format)
+    src, tgt = parse_conn_spec(source, "DBAGENT_SOURCE", "--source"), parse_conn_spec(target, "DBAGENT_TARGET", "--target")
+    src.query_timeout = tgt.query_timeout = timeout
+    sidecar = reports.with_name("reports.json")
+    if not sidecar.exists():
+        raise FileNotFoundError(f"{sidecar} not found. Run `ssrs` first; validate needs the dataset queries it saved.")
+    import json
+
+    data = json.loads(sidecar.read_text(encoding="utf-8"))
+    overrides = yaml.safe_load(params.read_text()) if params else {}
+    rows = validate_mod.validate_reports(data["reports"], src, tgt, overrides or {}, allow_exec, max_rows, _say)
+    out.mkdir(parents=True, exist_ok=True)
+    written = outputs.write_validation(out, rows, fmts)
+    if (out / "inventory.json").exists() or (out / "reports.json").exists():
+        pass
+    if "html" in fmts and (out / "reports.json").exists():
+        written += report_mod.write_report(out)
+    outputs.order_workbook(out)
+    _done(written, out)
+    counts: dict[str, int] = {}
+    for r in rows:
+        counts[r["status"]] = counts.get(r["status"], 0) + 1
+    typer.echo("Validation: " + (", ".join(f"{k} {v}" for k, v in sorted(counts.items())) or "nothing to compare"))
+    if counts.get("fail"):
+        raise typer.Exit(2)
+
+
+@app.command()
+@_guarded
+def report(out: Out = Path("db-agent-sqlserver-output")) -> None:
+    """Combine inventory, ssrs and validate outputs found in --out into summary.html and the workbook."""
+    if not out.is_dir() or not any((out / f).exists() for f in ("inventory.json", "reports.json", "validation.json")):
+        raise FileNotFoundError(f"nothing to report in {out}. Run inventory, ssrs or validate first.")
+    _done(report_mod.write_report(out), out)
+
+
+@app.command()
+def version() -> None:
+    """Print the version and the SQL Server versions it supports."""
+    typer.echo(f"db-agent {__version__}")
+    typer.echo(f"Supported: {SUPPORTED_SQL_SERVER}")
+    typer.echo("Python " + sys.version.split()[0])
+
+
+if __name__ == "__main__":
+    app()

db_agent/engines/sqlserver/data/classification.yaml

@@ -0,0 +1,29 @@
+# Default rules for classifying SSRS reports as move, review or retire.
+# Copy this file, edit it, and pass it with --config.
+
+# A report with no runs in this many days is "retire" ... but only if the usage log
+# reaches back at least this far. SSRS keeps only 60 days of log by default, so a short
+# log makes the answer "review", never "retire".
+retire_after_days: 365
+min_log_window_days: 365
+
+# Fewer runs than this in the last 365 days sends a report to review (it may be retire later).
+low_usage_runs_365: 6
+
+# More than this share of runs ending in an error sends a report to review.
+error_rate_review: 0.5
+
+# More expressions than this (formulas that start with "=") sends a report to review.
+complex_expression_threshold: 150
+
+# Features that send a report to review. Set to false to ignore one.
+review_if:
+  custom_code: true
+  custom_assemblies: true
+  subreports: true
+  drillthrough: true
+  complex_subscription: true
+  parse_failure: true
+  non_sql_data_source: true
+  unresolved_shared_dataset: true
+  stored_procedure_dataset: false

db_agent/engines/sqlserver/db.py

@@ -0,0 +1,183 @@
+"""The only module that talks to a SQL Server driver.
+
+Nothing else in the package may import pymssql or pyodbc (a test enforces this). Every
+statement goes through SafeConnection.query() or .stream(), which call the QueryGuard first.
+Passwords are held in memory only, hidden from repr(), and scrubbed from error messages.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from .guard import QueryGuard
+
+
+@dataclass
+class ConnectionConfig:
+    server: str
+    port: int = 1433
+    database: str = ""
+    user: str | None = None
+    password: str | None = field(default=None, repr=False)
+    driver: str = "pymssql"  # pymssql | odbc
+    trusted: bool = False  # Windows auth, odbc only
+    encrypt: bool = True
+    trust_server_certificate: bool = False
+    login_timeout: int = 15
+    query_timeout: int = 60
+
+    def with_database(self, database: str) -> "ConnectionConfig":
+        copy = ConnectionConfig(**{**self.__dict__})
+        copy.database = database
+        return copy
+
+    def __repr__(self) -> str:  # never show the password
+        return (
+            f"ConnectionConfig(server={self.server!r}, port={self.port}, database={self.database!r}, "
+            f"user={self.user!r}, driver={self.driver!r}, trusted={self.trusted})"
+        )
+
+
+ODBC_PREFERENCE = ("ODBC Driver 18 for SQL Server", "ODBC Driver 17 for SQL Server", "ODBC Driver 13.1 for SQL Server",
+                   "ODBC Driver 13 for SQL Server", "ODBC Driver 11 for SQL Server")
+
+
+def odbc_driver_name(installed: list[str]) -> str:
+    """Newest installed Microsoft ODBC driver for SQL Server. Client machines often have only 17 or 13.
+    Override with DBAGENT_ODBC_DRIVER."""
+    import os
+
+    forced = os.environ.get("DBAGENT_ODBC_DRIVER")
+    if forced:
+        return forced
+    for name in ODBC_PREFERENCE:
+        if name in installed:
+            return name
+    raise DatabaseError("no Microsoft ODBC driver for SQL Server found; install ODBC Driver 18 (or 17)")
+
+
+class DatabaseError(Exception):
+    """A driver or connection error, with secrets removed from the message."""
+
+
+def scrub(text: str, secrets: list[str | None]) -> str:
+    for s in secrets:
+        if s:
+            text = text.replace(s, "***")
+    return text
+
+
+class SafeConnection:
+    def __init__(self, cfg: ConnectionConfig, guard: QueryGuard | None = None):
+        self.cfg = cfg
+        self.guard = guard or QueryGuard()
+        self._conn: Any = None
+
+    # -- connection ---------------------------------------------------------------------------
+    def _connect(self) -> Any:
+        cfg = self.cfg
+        try:
+            if cfg.driver == "pymssql":
+                import pymssql
+
+                kwargs: dict[str, Any] = dict(
+                    server=cfg.server,
+                    port=str(cfg.port),
+                    user=cfg.user,
+                    password=cfg.password,
+                    database=cfg.database or "",
+                    login_timeout=cfg.login_timeout,
+                    timeout=cfg.query_timeout,
+                    appname="db-agent",
+                    read_only=True,  # ApplicationIntent=ReadOnly
+                    autocommit=False,
+                )
+                kwargs["encryption"] = "require" if cfg.encrypt else "off"
+                return pymssql.connect(**kwargs)
+            if cfg.driver == "odbc":
+                import pyodbc
+
+                parts = [
+                    f"DRIVER={{{odbc_driver_name(pyodbc.drivers())}}}",
+                    f"SERVER={cfg.server},{cfg.port}",
+                    "ApplicationIntent=ReadOnly",
+                    "APP=db-agent",
+                    f"Encrypt={'yes' if cfg.encrypt else 'no'}",
+                    f"TrustServerCertificate={'yes' if cfg.trust_server_certificate else 'no'}",
+                ]
+                if cfg.database:
+                    parts.append(f"DATABASE={cfg.database}")
+                if cfg.trusted:
+                    parts.append("Trusted_Connection=yes")
+                else:
+                    parts += [f"UID={cfg.user}", "PWD={" + str(cfg.password).replace("}", "}}") + "}"]
+                return pyodbc.connect(";".join(parts), timeout=cfg.login_timeout, autocommit=False)
+        except Exception as exc:  # noqa: BLE001
+            msg = scrub(f"could not connect to {cfg.server}: {exc}", [cfg.password])
+            if "certificate" in msg.lower() and "trust" in msg.lower():
+                msg += " Hint: the server uses a certificate this machine does not trust. Add --trust-server-certificate (odbc driver) or --no-encrypt."
+            raise DatabaseError(msg) from None
+        raise DatabaseError(f"unknown driver {cfg.driver!r}")
+
+    @property
+    def conn(self) -> Any:
+        if self._conn is None:
+            self._conn = self._connect()
+        return self._conn
+
+    def close(self) -> None:
+        if self._conn is not None:
+            try:
+                self._conn.rollback()
+                self._conn.close()
+            finally:
+                self._conn = None
+
+    def __enter__(self) -> "SafeConnection":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- queries ------------------------------------------------------------------------------
+    def _cursor(self, sql: str, params: Any) -> Any:
+        self.guard.check(sql)  # raises GuardError before anything reaches the server
+        cur = self.conn.cursor()
+        try:
+            cur.execute(sql, params) if params is not None else cur.execute(sql)
+        except Exception as exc:  # noqa: BLE001
+            cur.close()
+            self.conn.rollback()
+            raise DatabaseError(scrub(str(exc), [self.cfg.password])) from None
+        return cur
+
+    def query(self, sql: str, params: Any = None) -> list[dict[str, Any]]:
+        """Run a guarded SELECT and return all rows as dicts. For metadata-sized results only."""
+        cur = self._cursor(sql, params)
+        try:
+            cols = [d[0] for d in cur.description or []]
+            return [dict(zip(cols, row)) for row in cur.fetchall()]
+        finally:
+            cur.close()
+            self.conn.rollback()
+
+    def stream(self, sql: str, params: Any = None, chunk: int = 5000) -> Iterator[tuple[list[str], list[tuple]]]:
+        """Run a guarded SELECT and yield (columns, rows) chunks. Used by validate so rows are
+        folded into counts and totals as they arrive and are never kept."""
+        cur = self._cursor(sql, params)
+        try:
+            cols = [d[0] for d in cur.description or []]
+            while True:
+                rows = cur.fetchmany(chunk)
+                if not rows:
+                    break
+                yield cols, rows
+        finally:
+            cur.close()
+            self.conn.rollback()
+
+
+def config_from_env(prefix: str = "DBAGENT_SQL") -> dict[str, str | None]:
+    return {k: os.environ.get(f"{prefix}_{k.upper()}") for k in ("server", "port", "database", "user", "password")}

db_agent/engines/sqlserver/guard.py

@@ -0,0 +1,190 @@
+"""The query guard. Every statement sent to any SQL Server passes through check().
+
+Policy: one statement only. SELECT, or WITH ... SELECT, or EXEC of a stored procedure that
+the caller explicitly allowed (validate --allow-exec). Anything else is refused, and so is
+anything we cannot parse (fail closed).
+
+Two independent checks must both pass:
+  1. A text check on a sanitized copy (strings, comments and quoted names blanked out).
+  2. A sqlglot parse (tsql dialect) with an AST walk.
+"""
+
+from __future__ import annotations
+
+import re
+
+import sqlglot
+from sqlglot import exp
+
+
+class GuardError(Exception):
+    """The statement is not allowed. The message never contains the statement text."""
+
+
+_DENY_WORDS = (
+    "INTO INSERT UPDATE DELETE MERGE DROP ALTER CREATE TRUNCATE GRANT REVOKE DENY "
+    "BACKUP RESTORE SHUTDOWN KILL DBCC RECONFIGURE USE SET DECLARE WAITFOR BULK "
+    "OPENROWSET OPENQUERY OPENDATASOURCE OPENXML READTEXT WRITETEXT UPDATETEXT "
+    "EXEC EXECUTE SP_EXECUTESQL BEGIN COMMIT ROLLBACK GOTO RETURN PRINT RAISERROR THROW"
+).split()
+_DENY_RE = re.compile(r"\b(" + "|".join(_DENY_WORDS) + r")\b", re.IGNORECASE)
+_XP_RE = re.compile(r"\bxp_\w*", re.IGNORECASE)
+_FOUR_PART_RE = re.compile(r"[\w@#$]+(?:\.[\w@#$]*){3,}")
+_PLACEHOLDER_RE = re.compile(r"%\((\w+)\)s")
+_GO_RE = re.compile(r"^\s*GO\s*$", re.IGNORECASE | re.MULTILINE)
+
+_EXEC_RE = re.compile(
+    r"^\s*EXEC(?:UTE)?\s+(?P<proc>[\w\.\[\]]+)\s*(?P<args>.*?)\s*;?\s*$", re.IGNORECASE | re.DOTALL
+)
+_EXEC_ARGS_RE = re.compile(r"^(@\w+\s*=\s*%\(\w+\)s(\s*,\s*@\w+\s*=\s*%\(\w+\)s)*)?$")
+
+
+def _mask(segment: str) -> str:
+    return "".join(ch if ch == "\n" else " " for ch in segment)
+
+
+def sanitize(sql: str, preserve_length: bool = False, keep_strings: bool = False) -> str:
+    """Blank out string literals, quoted names and comments so keywords inside them are ignored.
+
+    Default mode: bracketed and double-quoted names become a plain word (_q_) so dotted chains
+    still count, strings become '' and comments a space.
+    preserve_length=True: every blanked character becomes a space (newlines kept), so offsets
+    and line numbers in the result match the original text.
+    """
+    out: list[str] = []
+    i, n = 0, len(sql)
+    while i < n:
+        c = sql[i]
+        two = sql[i : i + 2]
+        start = i
+        if two == "/*":
+            depth = 1
+            i += 2
+            while i < n and depth:
+                if sql[i : i + 2] == "/*":
+                    depth += 1
+                    i += 2
+                elif sql[i : i + 2] == "*/":
+                    depth -= 1
+                    i += 2
+                else:
+                    i += 1
+            out.append(_mask(sql[start:i]) if preserve_length else " ")
+        elif two == "--":
+            while i < n and sql[i] != "\n":
+                i += 1
+            out.append(_mask(sql[start:i]) if preserve_length else " ")
+        elif c == "'":
+            i += 1
+            while i < n:
+                if sql[i] == "'":
+                    if sql[i : i + 2] == "''":
+                        i += 2
+                        continue
+                    break
+                i += 1
+            i += 1
+            out.append(sql[start:i] if keep_strings else (_mask(sql[start:i]) if preserve_length else "''"))
+        elif c == "[":
+            i += 1
+            while i < n:
+                if sql[i] == "]":
+                    if sql[i : i + 2] == "]]":
+                        i += 2
+                        continue
+                    break
+                i += 1
+            i += 1
+            out.append(_mask(sql[start:i]) if preserve_length else "_q_")
+        elif c == '"':
+            i += 1
+            while i < n and sql[i] != '"':
+                i += 1
+            i += 1
+            out.append(_mask(sql[start:i]) if preserve_length else "_q_")
+        else:
+            out.append(c)
+            i += 1
+    return "".join(out)
+
+
+def _normalize_proc(name: str) -> str:
+    return name.replace("[", "").replace("]", "").strip().lower()
+
+
+_BAD_NODES = tuple(
+    getattr(exp, n)
+    for n in (
+        "Into", "Insert", "Update", "Delete", "Merge", "Create", "Drop", "Alter", "Command",
+        "Set", "Use", "TruncateTable", "Grant", "Revoke", "Transaction", "Commit", "Rollback",
+        "Declare", "Execute", "Copy", "LoadData", "Pragma",
+    )
+    if hasattr(exp, n)
+)
+_ROOT_OK = tuple(getattr(exp, n) for n in ("Select", "Union", "Subquery", "SetOperation") if hasattr(exp, n))
+
+
+class QueryGuard:
+    def __init__(self, allowed_procs: set[str] | None = None):
+        self.allowed_procs = {_normalize_proc(p) for p in (allowed_procs or set())}
+
+    def allow_proc(self, name: str) -> None:
+        self.allowed_procs.add(_normalize_proc(name))
+
+    def check(self, sql: str) -> None:
+        """Raise GuardError unless sql is allowed. Returns None when allowed."""
+        if not isinstance(sql, str) or not sql.strip():
+            raise GuardError("empty statement")
+        first_word = re.match(r"\s*(\w+)", sql)
+        if first_word and first_word.group(1).upper() in ("EXEC", "EXECUTE"):
+            self._check_exec(sql)
+            return
+        # Bound parameters (%(name)s) are values the driver sends separately. Check the statement
+        # in its @name form, which the parser understands. '%%' is the driver's escape for '%'.
+        sql = sql.replace("%%", "\x00")
+        sql = _PLACEHOLDER_RE.sub(r"@\1", sql).replace("%s", "@p").replace("\x00", "%")
+        clean = sanitize(sql)
+        if _GO_RE.search(clean):
+            raise GuardError("batch separator GO is not allowed")
+        body = clean.strip().rstrip(";").strip()
+        if ";" in body:
+            raise GuardError("more than one statement")
+        first = re.match(r"\s*(\w+)", body)
+        word = first.group(1).upper() if first else ""
+        if word not in ("SELECT", "WITH"):
+            raise GuardError(f"only SELECT is allowed, got {word or 'unknown'}")
+        hit = _DENY_RE.search(body)
+        if hit:
+            raise GuardError(f"keyword not allowed: {hit.group(1).upper()}")
+        if _XP_RE.search(body):
+            raise GuardError("extended stored procedures are not allowed")
+        if _FOUR_PART_RE.search(body):
+            raise GuardError("four-part names (linked servers) are not allowed")
+        self._check_ast(sql)
+
+    def _check_ast(self, sql: str) -> None:
+        try:
+            trees = sqlglot.parse(sql, read="tsql")
+        except Exception as exc:  # noqa: BLE001 - any parser failure means refuse
+            raise GuardError("could not verify the statement is read-only (parse failed)") from exc
+        trees = [t for t in trees if t is not None]
+        if len(trees) != 1:
+            raise GuardError("more than one statement")
+        tree = trees[0]
+        if not isinstance(tree, _ROOT_OK):
+            raise GuardError("statement is not a SELECT")
+        for node in tree.walk():
+            if isinstance(node, _BAD_NODES):
+                raise GuardError(f"statement part not allowed: {type(node).__name__}")
+
+    def _check_exec(self, sql: str) -> None:
+        m = _EXEC_RE.match(sql)
+        if not m:
+            raise GuardError("EXEC form not recognised")
+        proc = _normalize_proc(m.group("proc"))
+        if proc not in self.allowed_procs:
+            raise GuardError("stored procedure is not on the allowed list")
+        if not _EXEC_ARGS_RE.match(m.group("args").strip()):
+            raise GuardError("EXEC arguments must be named parameters (@name=%(name)s)")
+        if _XP_RE.search(proc) or proc.startswith("xp_") or ".xp_" in proc:
+            raise GuardError("extended stored procedures are not allowed")