feat: SQL Server SQL Graph support and statement-level NOSCAN option

.gitignore

@@ -208,7 +208,7 @@ marimo/_lsp/
 __marimo__/
 
 # Project specific
-.claude/plan/
+.claude/plan*/
 .claude/tmp/
 tests/config/
 test_connection.py

changelog.d/3.added.md

@@ -0,0 +1 @@
+Add SQL Server SQL Graph support (node/edge tables, MATCH predicate, SHORTEST_PATH) and statement-level NOSCAN execution option

scripts/install-git-hooks.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# scripts/install-git-hooks.sh
+#
+# Installs an optional pre-commit hook that runs scripts/preflight.sh so a
+# broken import/lint is caught before the commit (and before a CI round-trip).
+# Bypass a single commit with: git commit --no-verify
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+HOOK=".git/hooks/pre-commit"
+if [ ! -d .git/hooks ]; then
+  echo "install-git-hooks: .git/hooks not found (not a git repo?)" >&2
+  exit 2
+fi
+
+cat > "$HOOK" <<'HOOK_BODY'
+#!/usr/bin/env bash
+# Installed by scripts/install-git-hooks.sh — runs the local pre-flight.
+# Skip with: git commit --no-verify
+exec "$(git rev-parse --show-toplevel)/scripts/preflight.sh"
+HOOK_BODY
+chmod +x "$HOOK"
+
+echo "install-git-hooks: installed $HOOK -> scripts/preflight.sh"

scripts/preflight.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# scripts/preflight.sh
+#
+# Fast local pre-flight so a trivial ImportError/lint break is caught in
+# seconds-to-a-minute instead of after a full CI round-trip.
+#
+# Steps:
+#   1. ruff check <RUFF_TARGET>   report-only by default (STRICT_LINT=1 to gate)
+#   2. import smoke               FATAL: catches broken src imports
+#   3. pytest --collect-only      FATAL: imports every test module -> ImportError
+#
+# `--collect-only` does NOT execute tests, but it does import conftest.py, so a
+# missing local DB may print connection warnings. Collection still succeeds.
+#
+# Overridable env vars:
+#   VENV=<path>            venv dir (default: .venv3.14-ubuntu26.04)
+#   IMPORT_MODULE=<module> package to import (repo-specific default below)
+#   PYTEST_TARGET=<path>   collection target (default: tests)
+#   RUFF_TARGET=<path>     lint target (default: src)
+#   STRICT_LINT=1          make ruff failures fatal (default: report-only)
+#   SKIP_LINT=1 / SKIP_IMPORT=1 / SKIP_COLLECT=1
+set -uo pipefail
+
+cd "$(dirname "$0")/.."
+
+VENV="${VENV:-.venv3.14-ubuntu26.04}"
+PY="$VENV/bin/python"
+RUFF="$VENV/bin/ruff"
+IMPORT_MODULE="${IMPORT_MODULE:-rhosocial.activerecord.backend.impl.sqlserver}"
+PYTEST_TARGET="${PYTEST_TARGET:-tests}"
+RUFF_TARGET="${RUFF_TARGET:-src}"
+
+if [ ! -x "$PY" ]; then
+  echo "preflight: venv python not found at $VENV (set VENV=...)" >&2
+  exit 2
+fi
+
+fail=0
+
+if [ "${SKIP_LINT:-0}" != "1" ]; then
+  echo "==> [1/3] ruff check $RUFF_TARGET"
+  if [ -x "$RUFF" ]; then lint_cmd=("$RUFF"); else lint_cmd=("$PY" -m ruff); fi
+  if ! "${lint_cmd[@]}" check "$RUFF_TARGET"; then
+    if [ "${STRICT_LINT:-0}" = "1" ]; then
+      echo "preflight: lint failed (STRICT_LINT=1)" >&2
+      fail=1
+    else
+      echo "preflight: lint issues found (non-fatal; set STRICT_LINT=1 to gate)"
+    fi
+  fi
+else
+  echo "==> [1/3] ruff check (skipped)"
+fi
+
+if [ "${SKIP_IMPORT:-0}" != "1" ]; then
+  echo "==> [2/3] import smoke: $IMPORT_MODULE"
+  if ! "$PY" -c "import $IMPORT_MODULE"; then
+    echo "preflight: import of '$IMPORT_MODULE' failed" >&2
+    fail=1
+  fi
+else
+  echo "==> [2/3] import smoke (skipped)"
+fi
+
+if [ "${SKIP_COLLECT:-0}" != "1" ]; then
+  echo "==> [3/3] pytest --collect-only $PYTEST_TARGET (no tests executed)"
+  log="$(mktemp)"
+  if ! PYTHONPATH=tests "$PY" -m pytest "$PYTEST_TARGET" \
+        --collect-only -q -p no:cacheprovider > "$log" 2>&1; then
+    echo "preflight: test collection failed (ImportError?):" >&2
+    grep -E "ImportError|ModuleNotFoundError|NameError|ERROR collecting" "$log" | head -30 >&2
+    fail=1
+  fi
+  rm -f "$log"
+else
+  echo "==> [3/3] pytest --collect-only (skipped)"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo ""
+  echo "preflight: FAILED — fix the above before committing/pushing."
+  exit 1
+fi
+
+echo ""
+echo "preflight: OK"

src/rhosocial/activerecord/backend/impl/sqlserver/__init__.py

@@ -5,6 +5,7 @@
 from .config import SQLServerConnectionConfig
 from .collation import SQLServerCollation
 from .dialect import SQLServerDialect
+from .options import SQLServerExecutionOptions
 from .transaction import SQLServerTransactionManager
 from .adapters import (
     SQLServerUUIDAdapter,
@@ -66,6 +67,7 @@
 __all__ = [
     "SQLServerBackend",
     "SQLServerConnectionConfig",
+    "SQLServerExecutionOptions",
     "SQLServerDialect",
     "SQLServerCollation",
     "SQLServerTransactionManager",

src/rhosocial/activerecord/backend/impl/sqlserver/alter_table_modifier.py

@@ -6,6 +6,8 @@
 (``mixins/backend_mixin`` -> ``dialect``).
 """
 
+from typing import Any, Tuple
+
 from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError
 
 
@@ -35,7 +37,7 @@ def supports_drop_constraint_if_exists(self) -> bool:
         """``DROP CONSTRAINT IF EXISTS`` is supported since SQL Server 2016."""
         return True
 
-    def format_add_column_action(self, action):
+    def format_add_column_action(self, action: Any) -> Tuple[str, tuple]:
         if getattr(action, "if_not_exists", None) is True:
             raise UnsupportedFeatureError(
                 self.name,
@@ -47,13 +49,13 @@ def format_add_column_action(self, action):
         # SQL Server ALTER TABLE ... ADD takes the column without a COLUMN literal.
         return f"ADD {column_sql}", column_params
 
-    def format_drop_column_action(self, action):
+    def format_drop_column_action(self, action: Any) -> Tuple[str, tuple]:
         name = self.format_identifier(action.column_name)
         if getattr(action, "if_exists", None) is True:
             return f"DROP COLUMN IF EXISTS {name}", ()
         return f"DROP COLUMN {name}", ()
 
-    def format_drop_table_constraint_action(self, action):
+    def format_drop_table_constraint_action(self, action: Any) -> Tuple[str, tuple]:
         name = self.format_identifier(action.constraint_name)
         if getattr(action, "if_exists", None) is True:
             result = f"DROP CONSTRAINT IF EXISTS {name}"
@@ -63,7 +65,7 @@ def format_drop_table_constraint_action(self, action):
             result += " CASCADE"
         return result, ()
 
-    def format_alter_column_action(self, action):
+    def format_alter_column_action(self, action: Any) -> Tuple[str, tuple]:
         """Dispatch an ALTER COLUMN action to a SQL Server-specific formatter.
 
         SQL Server re-specifies the full column rather than applying the
@@ -96,7 +98,7 @@ def format_alter_column_action(self, action):
             "NULL/NOT NULL, COLLATE, SPARSE, or MASKED.",
         )
 
-    def format_alter_column_type_action(self, action):
+    def format_alter_column_type_action(self, action: Any) -> Tuple[str, tuple]:
         """Format a T-SQL ALTER COLUMN type change.
 
         SQL Syntax:
@@ -137,7 +139,7 @@ def format_alter_column_type_action(self, action):
 
         return " ".join(parts), ()
 
-    def format_add_masked_action(self, action):
+    def format_add_masked_action(self, action: Any) -> Tuple[str, tuple]:
         """Format ALTER COLUMN ... ADD MASKED (dynamic data masking, 2016+).
 
         SQL Syntax:
@@ -165,7 +167,7 @@ def format_add_masked_action(self, action):
             (),
         )
 
-    def format_drop_masked_action(self, action):
+    def format_drop_masked_action(self, action: Any) -> Tuple[str, tuple]:
         """Format ALTER COLUMN ... DROP MASKED (dynamic data masking, 2016+).
 
         SQL Syntax:

src/rhosocial/activerecord/backend/impl/sqlserver/async_backend.py

@@ -9,7 +9,8 @@
 import asyncio
 import logging
 import time
-from typing import Any, Dict, List, Optional, Set, Tuple
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Dict, List, Optional, Set, Tuple
 
 from rhosocial.activerecord.backend.base import AsyncStorageBackend
 from rhosocial.activerecord.backend.base.operations import AsyncSQLOperationsMixin
@@ -261,7 +262,7 @@ async def _get_identity_columns_async(self, table_name: str) -> Set[str]:
                 await cursor.execute(
                     "SELECT c.name FROM sys.identity_columns c "
                     "JOIN sys.tables t ON c.object_id = t.object_id "
-                    "WHERE t.name = ? AND SCHEMA_NAME(t.schema_id) = 'dbo'",
+                    f"WHERE t.name = {self.dialect.p()} AND SCHEMA_NAME(t.schema_id) = 'dbo'",
                     (table_name,),
                 )
                 for row in await cursor.fetchall():
@@ -329,6 +330,21 @@ async def execute(
 
         return await self._execute_statement(sql, params, options)
 
+    @asynccontextmanager
+    async def _cursor_noscan(self, cursor: Any, noscan: Optional[bool]) -> AsyncIterator[None]:
+        if noscan is None:
+            yield
+            return
+
+        impl = cursor._impl
+        run_operation = cursor._run_operation
+        previous = await run_operation(getattr, impl, "noscan")
+        try:
+            await run_operation(setattr, impl, "noscan", noscan)
+            yield
+        finally:
+            await run_operation(setattr, impl, "noscan", previous)
+
     async def _execute_statement(
         self, sql: str, params: Optional[Tuple], options, start_time: Optional[float] = None
     ) -> QueryResult:
@@ -366,7 +382,8 @@ async def _execute_statement(
                 if identity_table is not None:
                     await self.set_identity_insert(identity_table, True)
                 try:
-                    await cursor.execute(final_sql, final_params or ())
+                    async with self._cursor_noscan(cursor, getattr(options, "noscan", None)):
+                        await cursor.execute(final_sql, final_params or ())
                 finally:
                     if identity_table is not None:
                         await self.set_identity_insert(identity_table, False)

src/rhosocial/activerecord/backend/impl/sqlserver/backend.py

@@ -10,6 +10,7 @@
 import logging
 import re
 import time
+from contextvars import ContextVar
 from typing import Any, Dict, List, Optional, Tuple, Type
 
 import pyodbc
@@ -24,6 +25,7 @@
     OperationalError,
     QueryError,
 )
+from rhosocial.activerecord.backend.options import ExecutionOptions
 from rhosocial.activerecord.backend.result import QueryResult
 from rhosocial.activerecord.backend.introspection.backend_mixin import IntrospectorBackendMixin
 from rhosocial.activerecord.backend.explain import SyncExplainBackendMixin
@@ -161,6 +163,9 @@ def __init__(self, **kwargs):
         self._connection = None
         self._transaction_manager = None
         self._default_suggestions_cache = None
+        self._execution_noscan: ContextVar[Optional[bool]] = ContextVar(
+            "sqlserver_execution_noscan", default=None
+        )
 
         self._register_sqlserver_adapters()
 
@@ -358,7 +363,7 @@ def execute(
             cursor.execute(f"SET {set_clause} ON")
             cursor.close()
             try:
-                return super().execute(statement, params, options=options)
+                return self._execute_with_options(statement, params, options)
             finally:
                 cursor = self._get_cursor()
                 cursor.execute(f"SET {set_clause} OFF")
@@ -368,7 +373,7 @@ def execute(
         if identity_table is not None:
             self.set_identity_insert(identity_table, True)
         try:
-            result = super().execute(sql, params, options=options)
+            result = self._execute_with_options(sql, params, options)
         finally:
             if identity_table is not None:
                 self.set_identity_insert(identity_table, False)
@@ -380,6 +385,27 @@ def execute(
 
         return result
 
+    def _execute_with_options(
+        self, sql: str, params: Optional[Tuple], options: ExecutionOptions
+    ) -> QueryResult:
+        token = self._execution_noscan.set(getattr(options, "noscan", None))
+        try:
+            return super().execute(sql, params, options=options)
+        finally:
+            self._execution_noscan.reset(token)
+
+    def _execute_query(self, cursor: Any, sql: str, params: Optional[Tuple]) -> Any:
+        noscan = self._execution_noscan.get()
+        if noscan is None:
+            return super()._execute_query(cursor, sql, params)
+
+        previous = cursor.noscan
+        try:
+            cursor.noscan = noscan
+            return super()._execute_query(cursor, sql, params)
+        finally:
+            cursor.noscan = previous
+
     def execute_many(self, sql: str, params_list: List[Tuple]) -> QueryResult:
         """Execute the same SQL statement multiple times with different parameters.