procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/sqlserver/tests/test_sqlserver_schema.py

@@ -0,0 +1,488 @@
+"""Tests for the sqlserver schema-extract / schema-diff / migrate actions.
+
+No live DB and no pyodbc: extraction runs against a FAKE cursor returning canned
+catalog rows, dispatch injects a ``conn_factory``, and the diff dir-vs-dir path
+needs no connection at all. The migrate ``list`` path uses a fake connection that
+returns canned applied rows; the apply-without-``--apply`` guard is asserted.
+"""
+from __future__ import annotations
+
+import pytest
+
+from tools._lib import dbschema
+from tools.sqlserver import main, schema
+
+
+# --- programmable fake cursor/connection ------------------------------------
+
+class FakeCursor:
+    """Replays a queue of (description, rows) results across execute() calls.
+
+    Each execute() advances to the next queued result; description/fetchall
+    reflect the most recent execute. This models pyodbc's behaviour where the
+    same cursor is reused for several queries (as schema._emit_table does).
+    """
+
+    def __init__(self, results):
+        self._results = list(results)        # list[(description, rows)]
+        self._i = -1
+        self.executed = []
+
+    def execute(self, sql, *params):
+        self.executed.append((sql, params))
+        if self._i + 1 < len(self._results):
+            self._i += 1
+
+    @property
+    def description(self):
+        if self._i < 0:
+            return None
+        return self._results[self._i][0]
+
+    def fetchall(self):
+        if self._i < 0:
+            return []
+        return list(self._results[self._i][1])
+
+    def fetchone(self):
+        rows = self.fetchall()
+        return rows[0] if rows else None
+
+    def close(self):
+        pass
+
+
+class FakeConn:
+    """Hands out a queued cursor on each .cursor() call."""
+
+    def __init__(self, cursor_queue):
+        self._queue = list(cursor_queue)
+        self.cursors = []
+        self.closed = False
+
+    def cursor(self):
+        cur = self._queue.pop(0)
+        self.cursors.append(cur)
+        return cur
+
+    def close(self):
+        self.closed = True
+
+
+def _desc(*names):
+    return [(n, None) for n in names]
+
+
+# --- a profile must exist for needs_conn actions ----------------------------
+
+@pytest.fixture
+def one_profile(tmp_path, monkeypatch):
+    from tools._lib import dbprofiles
+
+    pfile = tmp_path / "profiles.json"
+    monkeypatch.setattr(main, "PROFILES_PATH", pfile)
+    monkeypatch.setattr(dbprofiles.creds, "has", lambda *a: False)
+    monkeypatch.setattr(dbprofiles.creds, "get_optional", lambda *a: None)
+    main._store().add("default", {"server": "h", "database": "d", "username": "u"})
+    return pfile
+
+
+# ===========================================================================
+# extract_objects against a fake cursor
+# ===========================================================================
+
+# canned module rows: a proc, a scalar function, a view, a trigger, plus an
+# is_ms_shipped-style row already excluded by SQL, and an encrypted (NULL body).
+_MODULE_DESC = _desc("schema_name", "object_name", "type_code", "type_desc", "body")
+_MODULE_ROWS = [
+    ("dbo", "GetCustomer", "P ", "SQL_STORED_PROCEDURE",
+     "CREATE PROCEDURE dbo.GetCustomer AS SELECT 1\r\n"),
+    ("dbo", "fnTax", "FN", "SQL_SCALAR_FUNCTION",
+     "CREATE FUNCTION dbo.fnTax() RETURNS int AS BEGIN RETURN 1 END"),
+    ("dbo", "vCustomer", "V", "VIEW", "CREATE VIEW dbo.vCustomer AS SELECT 1 AS x"),
+    ("dbo", "trAudit", "TR", "SQL_TRIGGER", "CREATE TRIGGER dbo.trAudit ON dbo.t AFTER INSERT AS SELECT 1"),
+    ("dbo", "secret", "P", "SQL_STORED_PROCEDURE", None),   # encrypted -> NULL body
+]
+
+
+def _modules_only_conn():
+    return FakeConn([FakeCursor([(_MODULE_DESC, _MODULE_ROWS)])])
+
+
+def test_extract_modules_verbatim_and_labels():
+    recs = schema.extract_modules(_modules_only_conn())
+    by_name = {r["name"]: r for r in recs}
+    assert by_name["GetCustomer"]["type"] == "Procedures"
+    assert by_name["fnTax"]["type"] == "Functions"
+    assert by_name["vCustomer"]["type"] == "Views"
+    assert by_name["trAudit"]["type"] == "Triggers"
+    # CRLF normalised to LF, verbatim body preserved
+    assert by_name["GetCustomer"]["definition"] == "CREATE PROCEDURE dbo.GetCustomer AS SELECT 1\n"
+    # encrypted object surfaces a NOTE placeholder rather than being dropped
+    assert "definition unavailable" in by_name["secret"]["definition"]
+
+
+# --- table DDL generation ---------------------------------------------------
+
+_TABLES_DESC = _desc("object_id", "schema_name", "table_name")
+_TABLES_ROWS = [(10, "dbo", "Customer")]
+
+_COLUMNS_DESC = _desc(
+    "column_id", "column_name", "type_name", "max_length", "precision", "scale",
+    "is_nullable", "is_identity", "seed_value", "increment_value", "collation_name",
+    "computed_definition", "is_persisted", "default_definition", "default_name",
+    "is_computed",
+)
+_COLUMNS_ROWS = [
+    # Id INT IDENTITY(1,1) NOT NULL
+    (1, "Id", "int", 4, 10, 0, 0, 1, "1", "1", None, None, 0, None, None, 0),
+    # Name nvarchar(100) NOT NULL with a default
+    (2, "Name", "nvarchar", 200, 0, 0, 0, 0, None, None, "Latin1_General_CI_AS",
+     None, 0, "('x')", "DF_Customer_Name", 0),
+    # Notes nvarchar(MAX) NULL
+    (3, "Notes", "nvarchar", -1, 0, 0, 1, 0, None, None, "Latin1_General_CI_AS",
+     None, 0, None, None, 0),
+]
+
+_PK_DESC = _desc("constraint_name", "type_desc", "column_name", "is_descending_key", "key_ordinal")
+_PK_ROWS = [("PK_Customer", "CLUSTERED", "Id", 0, 1)]
+
+_INDEX_DESC = _desc("index_id", "index_name", "type_desc", "is_unique",
+                    "filter_definition", "column_name", "is_descending_key",
+                    "is_included_column", "key_ordinal")
+_INDEX_ROWS = [(2, "IX_Customer_Name", "NONCLUSTERED", 0, None, "Name", 0, 0, 1)]
+
+_FK_DESC = _desc("fk_name", "ref_schema", "ref_table", "parent_column", "ref_column",
+                 "delete_referential_action_desc", "update_referential_action_desc",
+                 "constraint_column_id")
+_FK_ROWS = [("FK_Customer_Region", "dbo", "Region", "RegionId", "Id",
+             "NO_ACTION", "NO_ACTION", 1)]
+
+_CHECK_DESC = _desc("constraint_name", "definition", "is_disabled")
+_CHECK_ROWS = []
+
+
+def _tables_conn():
+    # extract_tables: 1 cursor for the TABLES list, then one cursor reused for the
+    # five per-table queries (columns, pk, index, fk, check).
+    tables_cur = FakeCursor([(_TABLES_DESC, _TABLES_ROWS)])
+    table_detail_cur = FakeCursor([
+        (_COLUMNS_DESC, _COLUMNS_ROWS),
+        (_PK_DESC, _PK_ROWS),
+        (_INDEX_DESC, _INDEX_ROWS),
+        (_FK_DESC, _FK_ROWS),
+        (_CHECK_DESC, _CHECK_ROWS),
+    ])
+    return FakeConn([tables_cur, table_detail_cur])
+
+
+def test_extract_tables_generates_create_ddl():
+    recs = schema.extract_tables(_tables_conn())
+    assert len(recs) == 1
+    rec = recs[0]
+    assert rec["type"] == "Tables"
+    assert rec["schema"] == "dbo" and rec["name"] == "Customer"
+    ddl = rec["definition"]
+    assert "CREATE TABLE [dbo].[Customer]" in ddl
+    assert "[Id] int IDENTITY(1,1) NOT NULL" in ddl
+    assert "[Name] nvarchar(100)" in ddl                  # 200 bytes / 2 = 100 chars
+    # nvarchar(MAX), nullable, with collation between type and nullability
+    assert "[Notes] nvarchar(MAX)" in ddl
+    assert "[Notes] nvarchar(MAX) COLLATE Latin1_General_CI_AS NULL" in ddl
+    assert "CONSTRAINT [PK_Customer] PRIMARY KEY CLUSTERED ([Id])" in ddl
+    assert "CREATE NONCLUSTERED INDEX [IX_Customer_Name]" in ddl
+    assert "ADD CONSTRAINT [FK_Customer_Region] FOREIGN KEY ([RegionId])" in ddl
+    assert "REFERENCES [dbo].[Region] ([Id])" in ddl
+
+
+def test_extract_objects_types_filter_modules_only():
+    # only modules cursor needed when U is excluded
+    recs = schema.extract_objects(_modules_only_conn(), types=["P", "V"])
+    labels = {r["type"] for r in recs}
+    # Procedures + Views kept; Functions/Triggers dropped by the family filter
+    assert "Procedures" in labels and "Views" in labels
+    assert "Functions" not in labels and "Triggers" not in labels
+    assert "Tables" not in labels
+
+
+# ===========================================================================
+# schema-extract dispatch -> writes a mirror under tmp_path
+# ===========================================================================
+
+def test_dispatch_schema_extract_writes_mirror(one_profile, tmp_path):
+    out = tmp_path / "mirror"
+    conn = _modules_only_conn()
+    result = main.dispatch(
+        "schema-extract",
+        ["--profile", "default", "--types", "P,V,FN,TR", "--out", str(out)],
+        conn_factory=lambda _p: conn,
+    )
+    assert result["profile"] == "default"
+    # proc, fn, view, trigger + the encrypted "secret" proc (NULL body -> NOTE placeholder,
+    # still a record). --types P,V,FN,TR keeps all 5 module objects.
+    assert result["written"] == 5
+    assert (out / "_manifest.json").is_file()
+    proc = out / "schema" / "Procedures" / "dbo.GetCustomer.sql"
+    assert proc.is_file()
+    assert proc.read_text(encoding="utf-8").startswith("CREATE PROCEDURE")
+    assert conn.closed is True
+
+
+def test_dispatch_schema_extract_dry_run_writes_nothing(one_profile, tmp_path):
+    out = tmp_path / "mirror"
+    result = main.dispatch(
+        "schema-extract",
+        ["--profile", "default", "--types", "P", "--out", str(out), "--dry-run"],
+        conn_factory=lambda _p: _modules_only_conn(),
+    )
+    assert result["dry_run"] is True
+    assert not out.exists()
+
+
+# ===========================================================================
+# schema-diff dir-vs-dir (no DB)
+# ===========================================================================
+
+def _make_mirror(root, files):
+    schema_root = root / "schema"
+    for rel, text in files.items():
+        p = schema_root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8")
+
+
+def test_dispatch_schema_diff_dirs(tmp_path):
+    left = tmp_path / "left"
+    right = tmp_path / "right"
+    _make_mirror(left, {
+        "Procedures/dbo.A.sql": "CREATE PROC A AS SELECT 1\n",
+        "Views/dbo.Gone.sql": "CREATE VIEW Gone AS SELECT 1\n",
+    })
+    _make_mirror(right, {
+        "Procedures/dbo.A.sql": "CREATE PROC A AS SELECT 2\n",   # changed
+        "Views/dbo.New.sql": "CREATE VIEW New AS SELECT 1\n",     # added
+    })
+    result = main.dispatch("schema-diff", ["--left", str(left), "--right", str(right)])
+    assert result["summary"] == {"added": 1, "removed": 1, "changed": 1}
+    assert "schema/Views/dbo.New.sql" in result["added"]
+    assert "schema/Views/dbo.Gone.sql" in result["removed"]
+    assert result["changed"][0]["relpath"] == "schema/Procedures/dbo.A.sql"
+    assert "diff" in result["changed"][0]            # unified diff present by default
+
+
+def test_dispatch_schema_diff_no_diff_text(tmp_path):
+    left = tmp_path / "l"
+    right = tmp_path / "r"
+    _make_mirror(left, {"Procedures/dbo.A.sql": "x\n"})
+    _make_mirror(right, {"Procedures/dbo.A.sql": "y\n"})
+    result = main.dispatch(
+        "schema-diff",
+        ["--left", str(left), "--right", str(right), "--no-diff-text"],
+    )
+    assert result["changed"][0]["relpath"] == "schema/Procedures/dbo.A.sql"
+    assert "diff" not in result["changed"][0]
+
+
+def test_dispatch_schema_diff_profile_side_extracts(one_profile, tmp_path):
+    # left is a live profile (extracted via the fake cursor), right is an empty dir
+    right = tmp_path / "right"
+    (right / "schema").mkdir(parents=True)
+    result = main.dispatch(
+        "schema-diff",
+        ["--left", "profile:default", "--right", str(right), "--types", "P,V,FN,TR"],
+        conn_factory=lambda _p: _modules_only_conn(),
+    )
+    # everything in the extracted left is "removed" relative to the empty right
+    assert result["summary"]["added"] == 0
+    assert result["summary"]["removed"] >= 4
+
+
+# ===========================================================================
+# migrate
+# ===========================================================================
+
+class MigrateConn:
+    """Fake connection for migrate: ensure-table is a no-op execute, then a SELECT
+    on the tracking table returns canned applied rows."""
+
+    def __init__(self, applied_rows, exists=True):
+        self._applied_rows = applied_rows
+        self._exists = exists
+        self.executed = []
+
+    def cursor(self):
+        return self  # the conn is its own cursor for simplicity
+
+    def execute(self, sql, *params):
+        self.executed.append((sql, params))
+        self._last = sql
+
+    def fetchall(self):
+        if "SELECT migration_id" in self._last:
+            return list(self._applied_rows)
+        return []
+
+    def fetchone(self):
+        # tracking_table_exists probes sys.tables; report existence per self._exists.
+        if "sys.tables" in self._last:
+            return (1,) if self._exists else None
+        return None
+
+    def close(self):
+        pass
+
+
+def _write_migrations(d, files):
+    d.mkdir(parents=True, exist_ok=True)
+    for name, text in files.items():
+        (d / name).write_text(text, encoding="utf-8")
+
+
+def test_migrate_list_applied_and_pending(one_profile, tmp_path):
+    mig_dir = tmp_path / "migrations"
+    _write_migrations(mig_dir, {
+        "001_init.sql": "CREATE TABLE dbo.A (id int);\n",
+        "002_drop.sql": "DROP TABLE dbo.A;\n",
+    })
+    # 001 already applied (matching sha so no drift); 002 pending
+    sha001 = dbschema.sha256_file(mig_dir / "001_init.sql")
+    applied = [("001_init", sha001, "001_init.sql", "2026-01-01T00:00:00")]
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(mig_dir), "--mode", "list"],
+        conn_factory=lambda _p: MigrateConn(applied),
+    )
+    assert result["mode"] == "list"
+    assert [a["migration_id"] for a in result["applied"]] == ["001_init"]
+    assert [p["migration_id"] for p in result["pending"]] == ["002_drop"]
+    assert result["drift"] == []
+    # the pending DROP migration carries a danger warning
+    assert any("destructive" in w for w in result["pending"][0]["danger_warnings"])
+
+
+def test_migrate_list_is_read_only_even_without_tracking_table(one_profile, tmp_path):
+    """`list` must NEVER create the tracking table (read-only on production DBs)."""
+    mig_dir = tmp_path / "migrations"
+    _write_migrations(mig_dir, {"001_init.sql": "SELECT 1;\n"})
+    conn = MigrateConn([], exists=False)        # tracking table does not exist
+    result = main.dispatch(
+        "migrate", ["--profile", "default", "--dir", str(mig_dir), "--mode", "list"],
+        conn_factory=lambda _p: conn)
+    assert result["applied"] == [] and len(result["pending"]) == 1
+    assert not any("CREATE TABLE" in sql.upper() for sql, _ in conn.executed)
+
+
+def test_migrate_list_detects_drift(one_profile, tmp_path):
+    mig_dir = tmp_path / "migrations"
+    _write_migrations(mig_dir, {"001_init.sql": "SELECT 1;\n"})
+    applied = [("001_init", "deadbeef" * 8, "001_init.sql", "2026-01-01T00:00:00")]
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(mig_dir), "--mode", "list"],
+        conn_factory=lambda _p: MigrateConn(applied),
+    )
+    assert len(result["drift"]) == 1
+    assert result["drift"][0]["migration_id"] == "001_init"
+
+
+def test_migrate_apply_requires_apply_flag(one_profile, tmp_path):
+    mig_dir = tmp_path / "migrations"
+    _write_migrations(mig_dir, {"001_init.sql": "SELECT 1;\n"})
+    with pytest.raises(main.UsageError, match="--apply"):
+        main.dispatch(
+            "migrate",
+            ["--profile", "default", "--dir", str(mig_dir), "--mode", "apply"],
+            conn_factory=lambda _p: MigrateConn([]),
+        )
+
+
+def test_migrate_apply_runs_pending(one_profile, tmp_path):
+    mig_dir = tmp_path / "migrations"
+    _write_migrations(mig_dir, {
+        "001_init.sql": "CREATE TABLE dbo.A (id int);\nGO\nINSERT INTO dbo.A VALUES (1);\n",
+    })
+    conn = MigrateConn([])
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(mig_dir), "--mode", "apply", "--apply"],
+        conn_factory=lambda _p: conn,
+    )
+    assert result["applied_now"] == 1
+    assert result["results"][0]["status"] == "applied"
+    assert result["results"][0]["batches"] == 2          # GO split into 2 batches
+    # a tracking INSERT was issued
+    assert any("INSERT INTO" in sql and "__schema_migrations" in sql
+               for sql, _ in conn.executed)
+
+
+def test_migrate_apply_dry_run_does_not_record(one_profile, tmp_path):
+    mig_dir = tmp_path / "migrations"
+    _write_migrations(mig_dir, {"001_init.sql": "SELECT 1;\n"})
+    conn = MigrateConn([])
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(mig_dir),
+         "--mode", "apply", "--apply", "--dry-run"],
+        conn_factory=lambda _p: conn,
+    )
+    assert result["dry_run"] is True
+    assert result["results"][0]["status"] == "dry-run-ok"
+    # no tracking INSERT in dry-run
+    assert not any("INSERT INTO" in sql and "__schema_migrations" in sql
+                   for sql, _ in conn.executed)
+    # but a ROLLBACK was issued for the file's transaction
+    assert any("ROLLBACK" in sql for sql, _ in conn.executed)
+
+
+class BatchCursor:
+    """Fake connection + cursor for apply_migration_sql. execute() opens a batch; the
+    results that follow its first one are listed per marker found in the SQL, and an
+    Exception among them is raised when nextset() reaches it, as pyodbc does."""
+
+    def __init__(self, later_results_by_marker):
+        self._by_marker = later_results_by_marker
+        self._pending = []
+        self.executed = []
+
+    def cursor(self):
+        return self
+
+    def execute(self, sql, *params):
+        self.executed.append(sql)
+        self._pending = list(next((r for m, r in self._by_marker.items() if m in sql), []))
+
+    def nextset(self):
+        if not self._pending:
+            return False
+        nxt = self._pending.pop(0)
+        if isinstance(nxt, Exception):
+            raise nxt
+        return True
+
+    def close(self):
+        pass
+
+
+def test_apply_migration_sql_surfaces_an_error_after_a_row_count():
+    # The INSERT answers "1 row affected" first, the THROW after it. Undrained, XACT_ABORT
+    # rolled the file back on the server while the tool reported it applied.
+    conn = BatchCursor({"INSERT dbo.T": [RuntimeError("check failed (51120)")]})
+    with pytest.raises(RuntimeError, match="51120"):
+        schema.apply_migration_sql(conn, "INSERT dbo.T VALUES (1);\n;THROW 51120, 'check failed', 1;\n")
+    assert any("ROLLBACK" in sql for sql in conn.executed)
+    assert not any("COMMIT" in sql for sql in conn.executed)
+
+
+def test_apply_migration_sql_commits_after_draining_a_clean_batch():
+    conn = BatchCursor({"INSERT dbo.T": ["1 row affected"]})
+    assert schema.apply_migration_sql(conn, "INSERT dbo.T VALUES (1);\nINSERT dbo.T VALUES (2);\n") == 1
+    assert conn.executed[-1] == "IF @@TRANCOUNT > 0 COMMIT TRANSACTION;"
+
+
+def test_tracking_table_is_unicode_with_a_named_primary_key():
+    # Databases that hold only nvarchar must not get a varchar column from the tool itself, and a
+    # system-named PK (PK____schema__<hash>) differs per database and breaks a parity compare.
+    import re
+    ddl = schema._ENSURE_TABLE_SQL
+    assert not re.search(r"(?<![N\w])(VAR)?CHAR\s*\(", ddl, re.I)
+    assert "CONSTRAINT PK___schema_migrations PRIMARY KEY" in ddl

procesio_cli/tools/sqlserver/tool.yaml

@@ -0,0 +1,123 @@
+name: sqlserver
+description: Read-only SQL Server queries over pyodbc with named connection profiles. SELECT-only by default (--write to override); returns rows as JSON; schema/table introspection.
+version: 0.1.0
+runtime: python
+entrypoint: main.py
+
+# Secrets are PER-PROFILE and dynamic, so none are declared here.
+# Each profile's password lives in Windows Credential Manager under
+# agents-and-tools:sqlserver:<profile-name> and is read at runtime via
+# tools._lib.creds.get("sqlserver", <profile>). Set one with:
+#   python scripts/set-credential.py sqlserver <profile>
+# Non-secret profile config (server/database/username/driver/tls) lives in
+# this tool's profiles.json — never the password.
+secrets: []
+
+routing:
+  triggers:
+    - run a SQL Server query
+    - query a SQL Server / MSSQL database
+    - read a table from SQL Server
+    - list SQL Server tables or columns
+  primary_action: query
+  example: sqlserver query --profile default --sql "SELECT TOP 10 * FROM dbo.Customer"
+
+actions:
+  - name: profiles
+    description: List configured connection profiles (no passwords).
+    args: []
+    output_schema: '{ "count": N, "profiles": [ {name, server, database, ..., has_password} ] }'
+
+  - name: add-profile
+    description: Store a connection profile (config only; set the password separately via set-credential).
+    args:
+      - {name: name, type: string, required: true, description: Profile name (also the credential name)}
+      - {name: server, type: string, required: true, description: "Host, host\\instance, or fqdn"}
+      - {name: database, type: string, description: "Default database (optional; one profile can serve many DBs - pick per call with --database)"}
+      - {name: username, type: string, description: SQL login (omit for a trusted/Windows connection)}
+      - {name: port, type: integer, description: "TCP port (appended as server,port)"}
+      - {name: driver, type: string, description: ODBC driver name (default = newest ODBC Driver for SQL Server installed on this machine)}
+      - {name: encrypt, type: string, description: Encrypt the connection - yes or no (default yes)}
+      - {name: trust-server-certificate, type: string, description: Trust a self-signed cert - yes or no (default no)}
+      - {name: connect-timeout, type: integer, description: Connect timeout seconds (default 30)}
+      - {name: statement-timeout, type: integer, description: "Statement timeout seconds, 0=unbounded (default 300)"}
+      - {name: overwrite, type: boolean, description: Replace an existing profile}
+    output_schema: '{ "name": "...", "server": "...", "database": "...", "has_password": false, "note": "..." }'
+
+  - name: test-connection
+    description: Connect and return the masked connection string + server version (never the password).
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+    output_schema: '{ "profile": "...", "connection_string": "...PWD=***...", "server_version": "...", "connected": true }'
+
+  - name: query
+    description: Run read-only SQL (SELECT by default; --write allows non-SELECT). Params bound via ? placeholders, never interpolated.
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: sql, type: string, required: true, description: SQL statement}
+      - {name: params, type: string, description: "Parameter values as a JSON array, bound via ? placeholders"}
+      - {name: max-rows, type: integer, description: Cap rows returned (default 1000; 0=unbounded)}
+      - {name: write, type: boolean, description: Allow a non-SELECT/DDL/multi statement (off by default)}
+      - {name: database, type: string, description: Run against this database instead of the profile's}
+      - {name: no-normalize-eol, type: boolean, description: "Keep SQL line endings as-is (default: normalize to CRLF so CREATE/ALTER object definitions store consistent EOLs and SSMS does not flag inconsistent line endings)"}
+    output_schema: '{ "columns": [...], "rows": [ {...} ], "row_count": N, "truncated": false, "write": false, "eol_normalized": true }'
+
+  - name: tables
+    description: List tables and views, optionally restricted to one schema.
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: List tables from this database instead of the profile's}
+      - {name: schema, type: string, description: Restrict to one schema}
+    output_schema: '{ "profile": "...", "count": N, "tables": [ {TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE} ] }'
+
+  - name: columns
+    description: List a table's columns (name, type, nullable, length, default).
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: Read columns from this database instead of the profile's}
+      - {name: table, type: string, required: true, description: Table name (schema.table or table)}
+    output_schema: '{ "profile": "...", "table": "...", "count": N, "columns": [ {COLUMN_NAME, DATA_TYPE, IS_NULLABLE, ...} ] }'
+
+  - name: schema-extract
+    description: Mirror all DB objects to local .sql files (one per object; incremental; read-only).
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: Extract this database instead of the profile's}
+      - {name: out, type: string, description: "Mirror output directory (default ./db-mirror/<profile>)"}
+      - {name: types, type: string, description: "Comma-separated type letters to extract (P,FN,TF,IF,V,TR,U); default all"}
+      - {name: full, type: boolean, description: Wipe the mirror and re-extract everything}
+      - {name: dry-run, type: boolean, description: Report what would change without writing}
+    output_schema: '{ "profile": "...", "database": "...", "out": "...", "written": N, "unchanged": N, "removed": N, "total": N, "by_type": {}, "dry_run": false }'
+
+  - name: schema-diff
+    description: Diff two schema mirrors or live profiles (objects added/removed/changed + unified diffs). Read-only.
+    args:
+      - {name: left, type: string, required: true, description: "Mirror directory OR profile:NAME for the left side"}
+      - {name: right, type: string, required: true, description: "Mirror directory OR profile:NAME for the right side"}
+      - {name: database-left, type: string, description: Database override when --left is a profile}
+      - {name: database-right, type: string, description: Database override when --right is a profile}
+      - {name: types, type: string, description: "Comma-separated type letters to extract for profile sides (P,FN,TF,IF,V,TR,U); default all"}
+      - {name: no-diff-text, type: boolean, description: Only list added/removed/changed names (omit unified diffs)}
+    output_schema: '{ "added": [...], "removed": [...], "changed": [ {relpath, diff} ], "unchanged": N, "identical": false, "summary": {added, removed, changed} }'
+
+  - name: migrate
+    description: List or apply versioned .sql migrations (forward-only; tracking table; apply gated behind --apply). list is read-only and the default.
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: Migrate this database instead of the profile's}
+      - {name: dir, type: string, description: "Migrations directory (default ./db-migrations/<profile>)"}
+      - {name: mode, type: string, description: "list (read-only; default) or apply (writes)"}
+      - {name: dry-run, type: boolean, description: Apply each pending file in a rolled-back transaction (no persist)}
+      - {name: apply, type: boolean, description: "Required confirmation for --mode apply (this writes)"}
+      - {name: accept-drift, type: boolean, description: Proceed with apply even if applied files drifted on disk}
+    output_schema: '{ "profile": "...", "mode": "list", "applied": [...], "pending": [ {migration_id, filename, danger_warnings} ], "drift": [...], "results": [...] }'
+
+requires:
+  - name: odbc-sqlserver
+    kind: driver
+    why: >
+      pyodbc ships in the venv but the Microsoft ODBC driver does not; without it
+      every DB action fails with missing_dependency while the tool still loads.
+    check: >-
+      {python} -c "import pyodbc,sys; sys.exit(0 if [d for d in pyodbc.drivers() if 'SQL Server' in d] else 1)"
+    install: winget install --id Microsoft.msodbcsql.18 -e --silent