diff --git a/src/pt_snap_cli/api.py b/src/pt_snap_cli/api.py index 620cf50..6075a41 100644 --- a/src/pt_snap_cli/api.py +++ b/src/pt_snap_cli/api.py @@ -15,6 +15,7 @@ ImportMetadataService, QueryService, ) +from pt_snap_cli.core.context_cache import ContextCache @dataclass @@ -34,14 +35,31 @@ def __init__( self, db_path: Path | None = None, device_id: int | None = None, + *, + context_cache: ContextCache | None = None, ) -> None: self._config = Config() self._db_path = db_path self._device_id = device_id self._focus_service = FocusService(self._config) - self._query_service = QueryService(self._focus_service) + # Share one context cache across the analyzer so that long-lived + # analyzers (e.g. the MCP server singleton) reuse a single + # SQLite connection and skip schema validation on every query. + # Explicit ``is not None`` because an empty cache is falsy via + # ``__len__`` and would be silently replaced otherwise. + self._context_cache = context_cache if context_cache is not None else ContextCache() + self._query_service = QueryService(self._focus_service, context_cache=self._context_cache) self._metadata_service = ImportMetadataService() + @property + def context_cache(self) -> ContextCache: + """Return the :class:`ContextCache` this analyzer uses.""" + return self._context_cache + + def invalidate_context_cache(self, db_path: Path | str | None = None) -> None: + """Drop a cached context (or every cached context when ``db_path`` is None).""" + self._context_cache.invalidate(db_path) + def get_focus(self) -> FocusState: state = self._focus_service.get_focus( explicit_db_path=self._db_path, diff --git a/src/pt_snap_cli/context.py b/src/pt_snap_cli/context.py index 66beda6..51e224f 100644 --- a/src/pt_snap_cli/context.py +++ b/src/pt_snap_cli/context.py @@ -25,14 +25,30 @@ class Context: """Database context manager for PyTorch memory snapshot analysis. Manages SQLite database connections in read-only mode with schema validation. + + By default the underlying SQLite connection is opened and closed for every + ``connect()`` context. Pass ``persistent=True`` to keep the connection + alive across calls so that long-lived owners (e.g. a ``ContextCache`` + shared by an MCP server) can avoid the per-query open/close cost. + Persistent contexts still close their connection when ``close()`` is + invoked explicitly. """ - def __init__(self, db_path: str | Path, devices: list[int] | None = None): + def __init__( + self, + db_path: str | Path, + devices: list[int] | None = None, + *, + persistent: bool = False, + ): """Initialize context with database path. Args: db_path: Path to the SQLite database file. devices: Optional list of device IDs to filter. + persistent: When True, the connection stays open after each + ``connect()`` call so it can be reused. The caller is + responsible for invoking ``close()`` to release it. Raises: DatabaseNotFoundError: If database file does not exist. @@ -40,7 +56,9 @@ def __init__(self, db_path: str | Path, devices: list[int] | None = None): """ self.db_path = Path(db_path) self._devices = devices + self._persistent = persistent self._conn: sqlite3.Connection | None = None + self._connect_depth = 0 self._device_ids: list[int] | None = None if not self.db_path.exists(): @@ -108,27 +126,37 @@ def cursor(self) -> sqlite3.Cursor: def connect(self) -> Generator[sqlite3.Connection, None, None]: """Context manager for database connection. - Opens database in read-only mode for safe analysis. + Opens database in read-only mode for safe analysis. When the + context was constructed with ``persistent=True`` the underlying + SQLite connection remains open after the context exits and is + reused by subsequent ``connect()`` calls until ``close()`` is + invoked explicitly. Yields: SQLite connection object. """ - if self._conn is not None: - yield self._conn - return + if self._conn is None: + # Keep the colon in Windows drive prefixes while encoding SQLite URI metacharacters. + encoded_path = quote(self.db_path.as_posix(), safe="/:") + uri = f"file:{encoded_path}?mode=ro" + self._conn = sqlite3.connect(uri, uri=True) + self._conn.row_factory = sqlite3.Row - # Keep the colon in Windows drive prefixes while encoding SQLite URI metacharacters. - encoded_path = quote(self.db_path.as_posix(), safe="/:") - uri = f"file:{encoded_path}?mode=ro" - self._conn = sqlite3.connect(uri, uri=True) - self._conn.row_factory = sqlite3.Row + self._connect_depth += 1 try: yield self._conn finally: - self.close() + if self._connect_depth > 0: + self._connect_depth -= 1 + if not self._persistent and self._connect_depth == 0: + self.close() def close(self) -> None: - """Close the database connection.""" + """Close the database connection. + + Safe to call multiple times and on already-closed contexts. + """ if self._conn is not None: self._conn.close() self._conn = None + self._connect_depth = 0 diff --git a/src/pt_snap_cli/core/context_cache.py b/src/pt_snap_cli/core/context_cache.py new file mode 100644 index 0000000..176ed38 --- /dev/null +++ b/src/pt_snap_cli/core/context_cache.py @@ -0,0 +1,121 @@ +"""LRU cache for read-only SQLite ``Context`` instances. + +The cache exists so that long-lived owners (e.g. the MCP server, which keeps +a single :class:`SnapshotAnalyzer` alive across many tool calls) can reuse a +single :class:`pt_snap_cli.context.Context` -- and its persistent read-only +SQLite connection -- instead of paying the cost of ``dictionary`` schema +validation, device discovery, and a fresh ``sqlite3.connect`` URI handshake on +every query. + +Entries are keyed by the resolved absolute path of the database file and +stamped with a file signature at the time of insertion. On lookup the cache +compares the current signature to the cached value and evicts the entry on +mismatch, so a database that is replaced on disk (for example, by +``pt-snap import``) is re-opened automatically even when the replacement has +the same mtime. Callers can also force a refresh with +:meth:`ContextCache.invalidate`. +""" + +from __future__ import annotations + +import sqlite3 +from collections import OrderedDict +from pathlib import Path +from typing import TYPE_CHECKING + +from pt_snap_cli.context import Context, DatabaseNotFoundError + +if TYPE_CHECKING: + pass + +FileSignature = tuple[int, int, int] + + +class ContextCache: + """LRU cache of :class:`Context` instances keyed by absolute db path.""" + + def __init__(self, maxsize: int = 4) -> None: + if maxsize <= 0: + raise ValueError("maxsize must be positive") + self._maxsize = maxsize + # Insertion order doubles as LRU recency (oldest first). + self._entries: OrderedDict[Path, tuple[Context, FileSignature]] = OrderedDict() + + @property + def maxsize(self) -> int: + return self._maxsize + + def __len__(self) -> int: + return len(self._entries) + + def get(self, db_path: Path | str) -> Context: + """Return a cached or freshly opened :class:`Context` for ``db_path``. + + On a hit the cached entry is promoted to most-recently-used. On a + miss -- or when the file's signature has changed -- a new persistent + context is created and stored, evicting the oldest entry once the + cache is full. + + Raises: + DatabaseNotFoundError: If ``db_path`` does not exist on disk. + """ + key = Path(db_path).expanduser().resolve() + if not key.exists(): + raise DatabaseNotFoundError(f"Database not found: {key}") + + # Probe metadata first so a missing/inaccessible file raises + # consistently whether the cache is hit or missed. + current_signature = self._file_signature(key) + + cached = self._entries.get(key) + if cached is not None: + ctx, cached_signature = cached + if cached_signature == current_signature: + self._entries.move_to_end(key) + return ctx + self._safe_close(ctx) + del self._entries[key] + + ctx = Context(key, persistent=True) + self._entries[key] = (ctx, current_signature) + self._evict_if_needed() + return ctx + + def invalidate(self, db_path: Path | str | None = None) -> None: + """Drop a single cached entry or every entry when ``db_path`` is None.""" + if db_path is None: + while self._entries: + _, (ctx, _) = self._entries.popitem(last=False) + self._safe_close(ctx) + return + key = Path(db_path).expanduser().resolve() + cached = self._entries.pop(key, None) + if cached is not None: + self._safe_close(cached[0]) + + def close(self) -> None: + """Drop every cached entry and close the underlying connections.""" + self.invalidate() + + def _evict_if_needed(self) -> None: + while len(self._entries) > self._maxsize: + _, (ctx, _) = self._entries.popitem(last=False) + self._safe_close(ctx) + + @staticmethod + def _safe_close(ctx: Context) -> None: + try: + ctx.close() + except sqlite3.Error: + # Already-closed connections are fine; other sqlite errors are + # best-effort cleanup, never worth masking the real exception. + pass + + @staticmethod + def _file_signature(path: Path) -> FileSignature: + """Return metadata that changes when a database is replaced in place.""" + stat = path.stat() + return (stat.st_mtime_ns, stat.st_ino, stat.st_size) + + +__all__ = ["ContextCache"] diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index af4d018..c23f654 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -5,6 +5,7 @@ from typing import Any from pt_snap_cli.context import Context, DatabaseNotFoundError, SchemaVersionError +from pt_snap_cli.core.context_cache import ContextCache from pt_snap_cli.core.errors import ( DatabaseMissingError, DatabaseSchemaError, @@ -30,8 +31,29 @@ class QueryService: - def __init__(self, focus_service: FocusService | None = None) -> None: + def __init__( + self, + focus_service: FocusService | None = None, + *, + context_cache: ContextCache | None = None, + ) -> None: self._focus_service = focus_service or FocusService() + # Cache Context instances across calls so long-lived owners (MCP + # server, SnapshotAnalyzer) skip the per-call schema validation and + # SQLite connect/close handshake. See ContextCache for the LRU and + # mtime invalidation semantics. + self._context_cache = context_cache if context_cache is not None else ContextCache() + self._executor: QueryExecutor | None = None + self._executor_context: Context | None = None + + @property + def context_cache(self) -> ContextCache: + """Return the :class:`ContextCache` backing this service.""" + return self._context_cache + + def invalidate_context_cache(self, db_path: Path | str | None = None) -> None: + """Drop a cached context (or all of them when ``db_path`` is None).""" + self._context_cache.invalidate(db_path) def list_templates( self, @@ -112,12 +134,15 @@ def execute_query( ctx = self._validated_context(resolved.db_path) target_device = self._resolve_device_id(ctx, resolved.device_id, device_id) - executor = QueryExecutor( - ctx, template_dir=Path(__file__).parent.parent / "query" / "templates" - ) + executor = self._get_executor(ctx) try: - rows = executor.execute_template(template, params or {}, device_id=target_device) + rows = executor.execute_template( + template, params or {}, device_id=target_device, max_rows=max_rows + ) + total = len(rows) + if max_rows is not None and max_rows > 0 and len(rows) == max_rows: + total = executor.count_template(template, params or {}, device_id=target_device) except ExecutorTemplateRenderError as exc: raise TemplateRenderError(str(exc)) from exc except ExecutorQueryExecutionError as exc: @@ -125,18 +150,22 @@ def execute_query( raise TemplateNotFoundError(f"Template '{template}' not found") from exc raise QueryExecutionError(str(exc)) from exc - if max_rows is None or max_rows <= 0: - limited_rows = rows - else: - limited_rows = rows[:max_rows] - return QueryResult( - total=len(rows), - returned=len(limited_rows), + total=total, + returned=len(rows), device_id=target_device, - rows=limited_rows, + rows=rows, ) + def _get_executor(self, ctx: Context) -> QueryExecutor: + """Reuse the executor while its cached database context remains valid.""" + if self._executor is None or self._executor_context is not ctx: + self._executor = QueryExecutor( + ctx, template_dir=Path(__file__).parent.parent / "query" / "templates" + ) + self._executor_context = ctx + return self._executor + def _resolve_device_id( self, ctx: Context, @@ -163,7 +192,7 @@ def _resolve_device_id( def _validated_context(self, db_path: Path) -> Context: try: - return Context(db_path) + return self._context_cache.get(db_path) except DatabaseNotFoundError as exc: raise DatabaseMissingError(str(exc)) from exc except (SchemaVersionError, sqlite3.DatabaseError) as exc: diff --git a/src/pt_snap_cli/query/executor.py b/src/pt_snap_cli/query/executor.py index db77221..303f32f 100644 --- a/src/pt_snap_cli/query/executor.py +++ b/src/pt_snap_cli/query/executor.py @@ -2,15 +2,24 @@ from __future__ import annotations +import re import warnings from pathlib import Path from typing import Any -from jinja2 import Environment, StrictUndefined, TemplateSyntaxError +from jinja2 import Environment, StrictUndefined, Template, TemplateSyntaxError from pt_snap_cli.context import Context from pt_snap_cli.query.config import QueryConfig, QueryTemplate +# Match a trailing numeric LIMIT clause (with optional OFFSET) at the end of a SQL string. +# Numeric limits let the executor tighten template-owned caps when the caller provides +# a smaller max_rows value. +_TRAILING_LIMIT_RE = re.compile( + r"\bLIMIT\s+(?P-?\d+)(?P\s+OFFSET\s+\d+)?(?P\s*;?\s*)$", + re.IGNORECASE | re.DOTALL, +) + class QueryExecutionError(Exception): """Raised when query execution fails.""" @@ -45,10 +54,53 @@ def __init__( undefined=StrictUndefined, autoescape=False, ) + # Cache of compiled Jinja templates keyed by template name so that + # long-lived executors (e.g. the MCP server) avoid re-parsing + # identical template bodies on every query. + self._compiled_cache: dict[tuple[str, str], Template] = {} if self._template_dir and self._template_dir.exists(): self._load_templates() + def _compiled_template(self, template: QueryTemplate) -> Template: + """Return the cached compiled Jinja template for ``template``. + + Compiles and caches on first access so repeat renders skip the + ``Environment.from_string`` parse step. + """ + cache_key = (template.name, template.query) + cached = self._compiled_cache.get(cache_key) + if cached is not None: + return cached + try: + compiled = self._env.from_string(template.query) + except TemplateSyntaxError as e: + raise TemplateRenderError(f"Template syntax error in '{template.name}': {e}") from e + self._compiled_cache[cache_key] = compiled + return compiled + + def _apply_limit(self, sql: str, limit: int) -> str: + """Tighten a trailing numeric LIMIT or append one when absent.""" + match = _TRAILING_LIMIT_RE.search(sql) + if match is None: + return self._append_limit(sql, limit) + + existing_limit = int(match.group("limit")) + effective_limit = limit if existing_limit < 0 else min(existing_limit, limit) + if effective_limit == existing_limit: + return sql + + offset = match.group("offset") or "" + suffix = match.group("suffix") or "" + return f"{sql[:match.start()]}LIMIT {effective_limit}{offset}{suffix}" + + def _append_limit(self, sql: str, limit: int) -> str: + """Append a ``LIMIT`` clause to ``sql`` when one is not present.""" + trimmed = sql.rstrip() + if trimmed.endswith(";"): + trimmed = trimmed[:-1].rstrip() + return f"{trimmed} LIMIT {int(limit)}" + def _load_templates(self) -> None: """Load all YAML templates from template directory.""" if not self._template_dir: @@ -66,6 +118,7 @@ def render( template: QueryTemplate, params: dict[str, Any], device_id: int | None = None, + max_rows: int | None = None, ) -> str: """Render SQL template with parameters. @@ -73,6 +126,13 @@ def render( template: Query template to render. params: Parameters for template rendering. device_id: Optional device ID for device-specific tables. + max_rows: Optional upper bound on returned rows. When positive, + the value is pushed down to SQL as a ``LIMIT`` clause and + also injected as the ``limit`` template variable so + templates that already expose a ``LIMIT {{ limit }}`` + parameter stay consistent. When the rendered SQL already + ends with a ``LIMIT`` (e.g. from ``top_n`` or another + template-defined cap), no second ``LIMIT`` is appended. Returns: Rendered SQL string. @@ -88,14 +148,26 @@ def render( render_context["device_trace_table"] = f"trace_entry_{device_id}" render_context["device_block_table"] = f"block_{device_id}" + effective_limit: int | None = None + if max_rows is not None and max_rows > 0: + template_limit = render_context.get("limit") + if isinstance(template_limit, int) and template_limit >= 0: + effective_limit = min(template_limit, max_rows) + else: + effective_limit = max_rows + render_context["limit"] = effective_limit + + jinja_template = self._compiled_template(template) try: - jinja_template = self._env.from_string(template.query) - return jinja_template.render(render_context) - except TemplateSyntaxError as e: - raise TemplateRenderError(f"Template syntax error in '{template.name}': {e}") from e + rendered_sql = jinja_template.render(render_context) except Exception as e: raise TemplateRenderError(f"Failed to render template '{template.name}': {e}") from e + if effective_limit is not None: + rendered_sql = self._apply_limit(rendered_sql, effective_limit) + + return rendered_sql + def execute( self, sql: str, @@ -125,12 +197,26 @@ def execute( except Exception as e: raise QueryExecutionError(f"Query execution failed: {e}") from e + def count(self, sql: str) -> int: + """Count the rows produced by a rendered query without materializing them.""" + query = sql.strip().rstrip(";").rstrip() + count_sql = f"SELECT COUNT(*) FROM ({query}) AS pt_snap_count" + try: + with self._context.connect() as conn: + cursor = conn.cursor() + cursor.execute(count_sql) + row = cursor.fetchone() + return int(row[0]) if row is not None else 0 + except Exception as e: + raise QueryExecutionError(f"Query execution failed: {e}") from e + def execute_template( self, name: str, params: dict[str, Any] | None = None, device_id: int | None = None, config_name: str | None = None, + max_rows: int | None = None, ) -> list[dict[str, Any]]: """Execute a named template query. @@ -139,6 +225,7 @@ def execute_template( params: Parameters for template rendering. device_id: Optional device ID to filter results. config_name: Optional config name if multiple configs loaded. + max_rows: Optional row limit pushed down to SQL when positive. Returns: List of result rows as dictionaries. @@ -151,13 +238,31 @@ def execute_template( if template is None: raise QueryExecutionError(f"Template not found: {name}") - sql = self.render(template, params or {}, device_id) + sql = self.render(template, params or {}, device_id, max_rows=max_rows) if device_id is not None and device_id not in self._context.device_ids: return [] return self.execute(sql) + def count_template( + self, + name: str, + params: dict[str, Any] | None = None, + device_id: int | None = None, + config_name: str | None = None, + ) -> int: + """Count rows returned by a named template without materializing them.""" + template = self._find_template(name, config_name) + if template is None: + raise QueryExecutionError(f"Template not found: {name}") + + if device_id is not None and device_id not in self._context.device_ids: + return 0 + + sql = self.render(template, params or {}, device_id) + return self.count(sql) + def execute_on_all_devices( self, name: str, diff --git a/src/pt_snap_cli/query/templates/business/leak_detection.yaml b/src/pt_snap_cli/query/templates/business/leak_detection.yaml index 89f6e3e..b7fae1d 100644 --- a/src/pt_snap_cli/query/templates/business/leak_detection.yaml +++ b/src/pt_snap_cli/query/templates/business/leak_detection.yaml @@ -12,12 +12,18 @@ queries: default: 0 required: false description: Minimum leak size in bytes + limit: + type: int + default: -1 + required: false + description: Maximum rows to return (-1 for unlimited). Mirrored from the caller-side ``max_rows`` for SQL pushdown. query: | SELECT id, address, size, allocEventId FROM {{ device_block_table }} WHERE size >= {{ min_size }} AND (allocEventId >= 0 AND (freeEventId IS NULL OR freeEventId < 0)) ORDER BY size DESC + LIMIT {{ limit|int }} output_schema: - column: id type: int @@ -26,4 +32,4 @@ queries: - column: size type: int - column: allocEventId - type: int \ No newline at end of file + type: int diff --git a/src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml b/src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml index f4fb399..78fcd19 100644 --- a/src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml +++ b/src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml @@ -17,6 +17,11 @@ queries: default: 0 required: false description: Minimum total size in bytes + limit: + type: int + default: -1 + required: false + description: Maximum rows to return (-1 for unlimited). Mirrored from the caller-side ``max_rows`` for SQL pushdown. query: | SELECT callstack, @@ -30,6 +35,7 @@ queries: HAVING alloc_count >= {{ min_count }} AND total_size >= {{ min_size }} ORDER BY total_size DESC + LIMIT {{ limit|int }} output_schema: - column: callstack type: str diff --git a/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml b/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml index 10a203a..764095b 100644 --- a/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml +++ b/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml @@ -15,35 +15,42 @@ queries: default: null required: false description: End event ID for range filtering + # Uses two CTEs to converge the peak computation to a single scan of the + # filtered range. ``filtered`` applies the optional ``start_id`` / + # ``end_id`` predicate once and is reused by ``peaks`` (aggregate scan) + # and by the outer MIN(id) subqueries so the result is bit-identical to + # the original nested-subquery form for every start_id/end_id + # combination, including the null/null default. query: | + WITH filtered AS ( + SELECT id, allocated, active, reserved + FROM {{ device_trace_table }} + WHERE 1=1 + {% if start_id is not none %}AND id >= {{ start_id|int }}{% endif %} + {% if end_id is not none %}AND id <= {{ end_id|int }}{% endif %} + ), peaks AS ( + SELECT + MAX(allocated) AS peak_allocated, + MAX(active) AS peak_active, + MAX(reserved) AS peak_reserved + FROM filtered + ) SELECT - (SELECT MAX(allocated) FROM {{ device_trace_table }} - {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} - ) as peak_allocated, - (SELECT MIN(id) FROM {{ device_trace_table }} - WHERE allocated = (SELECT MAX(allocated) FROM {{ device_trace_table }} - {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} - ) - {% if start_id is not none %}AND id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}AND id <= {{ end_id|int }}{% endif %} - ) as peak_allocated_event_id, - (SELECT MAX(active) FROM {{ device_trace_table }} - {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} - ) as peak_active, - (SELECT MIN(id) FROM {{ device_trace_table }} - WHERE active = (SELECT MAX(active) FROM {{ device_trace_table }} - {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} - ) - {% if start_id is not none %}AND id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}AND id <= {{ end_id|int }}{% endif %} - ) as peak_active_event_id, - (SELECT MAX(reserved) FROM {{ device_trace_table }} - {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} - ) as peak_reserved, - (SELECT MIN(id) FROM {{ device_trace_table }} - WHERE reserved = (SELECT MAX(reserved) FROM {{ device_trace_table }} - {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} - ) - {% if start_id is not none %}AND id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}AND id <= {{ end_id|int }}{% endif %} - ) as peak_reserved_event_id + (SELECT peak_allocated FROM peaks) AS peak_allocated, + ( + SELECT MIN(id) FROM filtered + WHERE allocated = (SELECT peak_allocated FROM peaks) + ) AS peak_allocated_event_id, + (SELECT peak_active FROM peaks) AS peak_active, + ( + SELECT MIN(id) FROM filtered + WHERE active = (SELECT peak_active FROM peaks) + ) AS peak_active_event_id, + (SELECT peak_reserved FROM peaks) AS peak_reserved, + ( + SELECT MIN(id) FROM filtered + WHERE reserved = (SELECT peak_reserved FROM peaks) + ) AS peak_reserved_event_id output_schema: - column: peak_allocated type: int @@ -56,4 +63,4 @@ queries: - column: peak_reserved type: int - column: peak_reserved_event_id - type: int + type: int \ No newline at end of file diff --git a/tests/core/test_context_cache.py b/tests/core/test_context_cache.py new file mode 100644 index 0000000..cf9617f --- /dev/null +++ b/tests/core/test_context_cache.py @@ -0,0 +1,190 @@ +"""Tests for the LRU Context cache that powers connection reuse.""" + +from __future__ import annotations + +import os +import sqlite3 +from pathlib import Path + +import pytest + +from pt_snap_cli.context import Context, DatabaseNotFoundError, SchemaVersionError +from pt_snap_cli.core.context_cache import ContextCache + + +def _make_db(tmp_path: Path, name: str = "sample.db") -> Path: + db_path = tmp_path / name + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute("CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY, size INTEGER)") + conn.execute("INSERT INTO trace_entry_0 (size) VALUES (1), (2), (3)") + conn.commit() + conn.close() + return db_path + + +def _make_invalid_db(tmp_path: Path, name: str = "invalid.db") -> Path: + db_path = tmp_path / name + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE other (id INTEGER PRIMARY KEY)") + conn.commit() + conn.close() + return db_path + + +class TestContextCache: + def test_get_creates_context(self, tmp_path: Path) -> None: + db_path = _make_db(tmp_path) + cache = ContextCache(maxsize=4) + + ctx = cache.get(db_path) + + assert isinstance(ctx, Context) + assert ctx.db_path == db_path.resolve() + assert ctx.device_ids == [0] + assert len(cache) == 1 + + def test_get_returns_cached_context_on_second_call(self, tmp_path: Path) -> None: + db_path = _make_db(tmp_path) + cache = ContextCache(maxsize=4) + + first = cache.get(db_path) + second = cache.get(db_path) + + assert first is second + assert len(cache) == 1 + + def test_get_raises_for_missing_file(self, tmp_path: Path) -> None: + cache = ContextCache(maxsize=4) + missing = tmp_path / "missing.db" + + with pytest.raises(DatabaseNotFoundError): + cache.get(missing) + + # A failed get must not leave a stale entry behind. + assert len(cache) == 0 + + def test_get_propagates_schema_errors(self, tmp_path: Path) -> None: + bad_db = _make_invalid_db(tmp_path) + cache = ContextCache(maxsize=4) + + with pytest.raises(SchemaVersionError): + cache.get(bad_db) + + def test_same_mtime_replacement_refreshes_cached_context(self, tmp_path: Path) -> None: + """Replacing a database with the same mtime must refresh its context.""" + db_path = _make_db(tmp_path) + cache = ContextCache(maxsize=4) + first = cache.get(db_path) + original_stat = db_path.stat() + + replacement = tmp_path / "same-mtime.db" + conn = sqlite3.connect(str(replacement)) + conn.execute( + "CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)" + ) + conn.execute("CREATE TABLE trace_entry_1 (id INTEGER PRIMARY KEY, size INTEGER)") + conn.commit() + conn.close() + os.utime(replacement, ns=(original_stat.st_atime_ns, original_stat.st_mtime_ns)) + os.replace(replacement, db_path) + + second = cache.get(db_path) + + assert second is not first + assert second.device_ids == [1] + + def test_invalidate_path_drops_entry(self, tmp_path: Path) -> None: + db_path = _make_db(tmp_path) + cache = ContextCache(maxsize=4) + ctx = cache.get(db_path) + assert len(cache) == 1 + + cache.invalidate(db_path) + + assert len(cache) == 0 + # Re-fetching creates a new Context. + new_ctx = cache.get(db_path) + assert new_ctx is not ctx + + def test_invalidate_all_drops_every_entry(self, tmp_path: Path) -> None: + db1 = _make_db(tmp_path, "a.db") + db2 = _make_db(tmp_path, "b.db") + cache = ContextCache(maxsize=4) + cache.get(db1) + cache.get(db2) + assert len(cache) == 2 + + cache.invalidate() + assert len(cache) == 0 + + def test_lru_eviction(self, tmp_path: Path) -> None: + cache = ContextCache(maxsize=2) + db_a = _make_db(tmp_path, "a.db") + db_b = _make_db(tmp_path, "b.db") + db_c = _make_db(tmp_path, "c.db") + + ctx_a = cache.get(db_a) + ctx_b = cache.get(db_b) + + # Touching db_a promotes it; inserting db_c should evict db_b. + ctx_a_again = cache.get(db_a) + cache.get(db_c) + + assert ctx_a is ctx_a_again + assert len(cache) == 2 + # db_b was evicted: a fresh fetch must return a brand new Context. + ctx_b_new = cache.get(db_b) + assert ctx_b_new is not ctx_b + + def test_maxsize_must_be_positive(self) -> None: + with pytest.raises(ValueError): + ContextCache(maxsize=0) + with pytest.raises(ValueError): + ContextCache(maxsize=-1) + + +class TestPersistentContext: + def test_persistent_context_keeps_connection_alive(self, tmp_path: Path) -> None: + db_path = _make_db(tmp_path) + ctx = Context(db_path, persistent=True) + + with ctx.connect() as conn: + assert conn is not None + cursor = conn.cursor() + cursor.execute("SELECT COUNT(*) FROM trace_entry_0") + assert cursor.fetchone()[0] == 3 + + # Connection must still be open; a second connect() reuses it. + assert ctx._conn is not None + with ctx.connect() as conn: + cursor = conn.cursor() + cursor.execute("SELECT COUNT(*) FROM trace_entry_0") + assert cursor.fetchone()[0] == 3 + + ctx.close() + assert ctx._conn is None + + def test_non_persistent_context_closes_after_block(self, tmp_path: Path) -> None: + """Default behaviour is unchanged: the connection closes when the + ``connect()`` context exits so the existing Context contract is + preserved.""" + db_path = _make_db(tmp_path) + ctx = Context(db_path) + + with ctx.connect(): + assert ctx._conn is not None + assert ctx._conn is None + + def test_nested_non_persistent_connect_closes_after_outer_block(self, tmp_path: Path) -> None: + db_path = _make_db(tmp_path) + ctx = Context(db_path) + + with ctx.connect() as outer: + with ctx.connect() as inner: + assert inner is outer + inner.execute("SELECT 1") + outer.execute("SELECT 1") + assert ctx._conn is not None + + assert ctx._conn is None diff --git a/tests/core/test_query_service.py b/tests/core/test_query_service.py index edefdda..81415a7 100644 --- a/tests/core/test_query_service.py +++ b/tests/core/test_query_service.py @@ -12,7 +12,7 @@ QueryService, TemplateNotFoundError, ) -from pt_snap_cli.query.config import QueryTemplate +from pt_snap_cli.query.config import QueryParameter, QueryTemplate from pt_snap_cli.query.registry import QueryRegistry, register_query @@ -106,10 +106,53 @@ def test_execute_query_max_rows_positive_limits_rows(self, sample_db: Path) -> N result = QueryService().execute_query("size_query", max_rows=1) + # ``max_rows`` is pushed down to SQL as a ``LIMIT`` clause, so the + # executor returns exactly ``max_rows`` rows and Python never slices + # the result set. assert result.total == 2 assert result.returned == 1 assert len(result.rows) == 1 + def test_execute_query_explicit_zero_limit_is_not_relaxed(self, sample_db: Path) -> None: + config = Config() + config.write_project_focus(sample_db) + register_query( + QueryTemplate( + name="size_query_with_limit", + description="Test", + query="SELECT size FROM trace_entry_0 LIMIT {{ limit|int }}", + parameters={ + "limit": QueryParameter(name="limit", type="int", default=-1), + }, + ) + ) + + result = QueryService().execute_query( + "size_query_with_limit", params={"limit": 0}, max_rows=5 + ) + + assert result.total == 0 + assert result.returned == 0 + assert result.rows == [] + + def test_execute_query_reuses_executor_for_cached_context(self, sample_db: Path) -> None: + config = Config() + config.write_project_focus(sample_db) + register_query( + QueryTemplate( + name="size_query", + description="Test", + query="SELECT size FROM trace_entry_0", + ) + ) + service = QueryService() + + service.execute_query("size_query") + first_executor = service._executor + service.execute_query("size_query") + + assert service._executor is first_executor + def test_execute_query_invalid_device(self, sample_db: Path) -> None: config = Config() config.write_project_focus(sample_db) diff --git a/tests/query/test_executor.py b/tests/query/test_executor.py index 9b51b6d..19d63db 100644 --- a/tests/query/test_executor.py +++ b/tests/query/test_executor.py @@ -17,6 +17,7 @@ def test_render_simple_template(self): ) executor = QueryExecutor.__new__(QueryExecutor) executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} sql = executor.render(template, {"min_size": 1024}) assert "SELECT * FROM table WHERE size >= 1024" == sql @@ -29,6 +30,7 @@ def test_render_with_device_trace_table(self): ) executor = QueryExecutor.__new__(QueryExecutor) executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} sql = executor.render(template, {}, device_id=0) assert "SELECT * FROM trace_entry_0 WHERE id = 1" == sql @@ -41,6 +43,7 @@ def test_render_with_device_block_table(self): ) executor = QueryExecutor.__new__(QueryExecutor) executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} sql = executor.render(template, {}, device_id=0) assert "SELECT * FROM block_0 WHERE id = 1" == sql @@ -55,6 +58,7 @@ def test_render_with_conditional(self): ) executor = QueryExecutor.__new__(QueryExecutor) executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} sql_with_filter = executor.render(template, {"filter": "alloc"}) assert "WHERE type = 'alloc'" in sql_with_filter @@ -70,6 +74,7 @@ def test_render_invalid_syntax(self): ) executor = QueryExecutor.__new__(QueryExecutor) executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} with pytest.raises(TemplateRenderError, match="Template syntax error"): executor.render(template, {}) @@ -84,6 +89,7 @@ def test_render_missing_required_param(self): ) executor = QueryExecutor.__new__(QueryExecutor) executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} with pytest.raises(ValueError, match="Required parameter"): executor.render(template, {}) @@ -126,6 +132,151 @@ def test_validate_output_empty_result(self): assert executor.validate_output([], schema) is True + def test_max_rows_appends_limit_when_template_has_none(self) -> None: + """A positive max_rows must be pushed down as LIMIT for templates + that don't already declare one (e.g. ``leak_detection``).""" + template = QueryTemplate( + name="no_limit", + query="SELECT id FROM t ORDER BY id", + parameters={}, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + sql = executor.render(template, {}, max_rows=5) + assert sql.endswith("LIMIT 5"), sql + + def test_max_rows_uses_template_limit_when_template_owns_one(self) -> None: + """When the template already exposes ``limit`` via ``LIMIT {{ limit }}`` + the executor must inject the effective limit into that variable + instead of appending a second LIMIT clause.""" + template = QueryTemplate( + name="with_limit", + query="SELECT id FROM t ORDER BY id LIMIT {{ limit|int }}", + parameters={ + "limit": QueryParameter(name="limit", type="int", default=-1), + }, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + sql = executor.render(template, {}, max_rows=5) + # Exactly one LIMIT and it carries the pushed-down value. + upper = sql.upper() + assert upper.count("LIMIT") == 1 + assert sql.endswith("LIMIT 5"), sql + + def test_max_rows_zero_or_none_keeps_template_default(self) -> None: + """``max_rows <= 0`` (including None) must not override the + template's default LIMIT, so a template with ``LIMIT -1`` stays + unlimited.""" + template = QueryTemplate( + name="with_limit", + query="SELECT id FROM t LIMIT {{ limit|int }}", + parameters={ + "limit": QueryParameter(name="limit", type="int", default=-1), + }, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + assert executor.render(template, {}, max_rows=None).endswith("LIMIT -1") + assert executor.render(template, {}, max_rows=0).endswith("LIMIT -1") + assert executor.render(template, {}, max_rows=-1).endswith("LIMIT -1") + + def test_max_rows_min_of_template_and_caller(self) -> None: + """If the user also passes ``params={'limit': 3}``, the effective + limit pushed to SQL is min(template_limit, max_rows).""" + template = QueryTemplate( + name="with_limit", + query="SELECT id FROM t LIMIT {{ limit|int }}", + parameters={ + "limit": QueryParameter(name="limit", type="int", default=-1), + }, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + # Template limit (3) is smaller than max_rows (10): use 3. + assert executor.render(template, {"limit": 3}, max_rows=10).endswith("LIMIT 3") + # max_rows (10) is smaller than template limit (50): use 10. + assert executor.render(template, {"limit": 50}, max_rows=10).endswith("LIMIT 10") + # Zero is an explicit empty result, not an unlimited value. + assert executor.render(template, {"limit": 0}, max_rows=10).endswith("LIMIT 0") + + def test_max_rows_does_not_double_limit(self) -> None: + """Templates that cap rows with a non-``limit`` variable (e.g. + ``top_n``) keep their own LIMIT and the executor must not append + a second one.""" + template = QueryTemplate( + name="with_top_n", + query="SELECT callstack FROM t GROUP BY callstack LIMIT {{ top_n|int }}", + parameters={ + "top_n": QueryParameter(name="top_n", type="int", default=20), + }, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + sql = executor.render(template, {}, max_rows=100) + # ``LIMIT`` appears exactly once and reflects the template's own + # ``top_n`` default, not the caller's ``max_rows``. + assert sql.upper().count("LIMIT") == 1 + assert sql.endswith("LIMIT 20"), sql + + def test_max_rows_tightens_non_limit_template_cap(self) -> None: + """A caller cap must also tighten templates that use ``top_n``.""" + template = QueryTemplate( + name="with_top_n", + query="SELECT callstack FROM t GROUP BY callstack LIMIT {{ top_n|int }}", + parameters={ + "top_n": QueryParameter(name="top_n", type="int", default=20), + }, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + sql = executor.render(template, {}, max_rows=5) + + assert sql.upper().count("LIMIT") == 1 + assert sql.endswith("LIMIT 5"), sql + + def test_jinja_template_compiled_once_per_template(self) -> None: + """Long-lived executors (MCP server) must avoid re-parsing the + same template body on every render call.""" + template = QueryTemplate( + name="cached", + query="SELECT {{ device_id }}", + parameters={}, + ) + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + first = executor._compiled_template(template) + second = executor._compiled_template(template) + assert first is second + assert ("cached", template.query) in executor._compiled_cache + + def test_jinja_cache_distinguishes_same_name_with_new_query(self) -> None: + first_template = QueryTemplate(name="cached", query="SELECT 1") + second_template = QueryTemplate(name="cached", query="SELECT 2") + executor = QueryExecutor.__new__(QueryExecutor) + executor._env = QueryExecutor(context=None)._env + executor._compiled_cache = {} + + first = executor._compiled_template(first_template) + second = executor._compiled_template(second_template) + + assert first is not second + assert len(executor._compiled_cache) == 2 + def test_list_templates(self): executor = QueryExecutor.__new__(QueryExecutor) executor._configs = {} diff --git a/tests/query/test_memory_peak_cte.py b/tests/query/test_memory_peak_cte.py new file mode 100644 index 0000000..ba1edef --- /dev/null +++ b/tests/query/test_memory_peak_cte.py @@ -0,0 +1,218 @@ +"""Regression tests for the ``memory_peak`` template rewrite. + +The CTE-based rewrite must produce byte-identical results to the original +nested-subquery form for every ``start_id`` / ``end_id`` combination -- +including ``null`` and edge cases such as inverted or out-of-range windows. +These guard against regressions in the SQL itself as well as in the +``QueryService`` -> ``QueryExecutor`` integration that drives it. +""" + +from __future__ import annotations + +import sqlite3 +from pathlib import Path + +import pytest + +from pt_snap_cli.context import Context +from pt_snap_cli.query.executor import QueryExecutor +from pt_snap_cli.query.registry import QueryRegistry, _load_all_templates + + +@pytest.fixture(autouse=True) +def _isolate_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Run each test from a temp directory so ``write_project_focus`` + doesn't pollute the workspace root with a stray ``.pt-snap/``.""" + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("PT_SNAP_DB_PATH", raising=False) + + +ORIGINAL_SQL = """ +SELECT + (SELECT MAX(allocated) FROM trace_entry_0 + {start_cond} + ) as peak_allocated, + (SELECT MIN(id) FROM trace_entry_0 + WHERE allocated = (SELECT MAX(allocated) FROM trace_entry_0 + {start_cond} + ) + {end_cond_inner} + ) as peak_allocated_event_id, + (SELECT MAX(active) FROM trace_entry_0 + {start_cond} + ) as peak_active, + (SELECT MIN(id) FROM trace_entry_0 + WHERE active = (SELECT MAX(active) FROM trace_entry_0 + {start_cond} + ) + {end_cond_inner} + ) as peak_active_event_id, + (SELECT MAX(reserved) FROM trace_entry_0 + {start_cond} + ) as peak_reserved, + (SELECT MIN(id) FROM trace_entry_0 + WHERE reserved = (SELECT MAX(reserved) FROM trace_entry_0 + {start_cond} + ) + {end_cond_inner} + ) as peak_reserved_event_id +""" + + +def _render_original(start_id: int | None, end_id: int | None) -> str: + if start_id is not None and end_id is not None: + start_cond = f"WHERE id >= {start_id} AND id <= {end_id}" + end_cond_inner = f"AND id >= {start_id} AND id <= {end_id}" + elif start_id is not None: + start_cond = f"WHERE id >= {start_id}" + end_cond_inner = f"AND id >= {start_id}" + elif end_id is not None: + start_cond = f"WHERE id <= {end_id}" + end_cond_inner = f"AND id <= {end_id}" + else: + start_cond = "" + end_cond_inner = "" + return ORIGINAL_SQL.format(start_cond=start_cond, end_cond_inner=end_cond_inner) + + +@pytest.fixture(autouse=True) +def _reload_registry() -> None: + QueryRegistry.reset() + _load_all_templates() + + +@pytest.fixture +def memory_peak_db(tmp_path: Path) -> Path: + """Snapshot database with non-trivial, overlapping peaks per metric.""" + db_path = tmp_path / "memory_peak.db" + conn = sqlite3.connect(str(db_path)) + conn.execute(""" + CREATE TABLE dictionary ( + `table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT + ) + """) + conn.execute(""" + CREATE TABLE trace_entry_0 ( + id INTEGER PRIMARY KEY, + action INTEGER, + address INTEGER, + size INTEGER, + stream INTEGER, + allocated INTEGER, + active INTEGER, + reserved INTEGER, + callstack TEXT + ) + """) + # Rows are crafted so: + # * The all-time allocated peak lives at id=4 (not at id=8 which is + # inside an arbitrary window). + # * The active peak is id=5. + # * The reserved peak is id=3. + # * Different windows pick different ids. + conn.executemany( + """ + INSERT INTO trace_entry_0 + (id, action, address, size, stream, allocated, active, reserved, callstack) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + """, + [ + (1, 2, 0x1000, 1024, 0, 100, 50, 200, "a"), + (2, 2, 0x2000, 2048, 0, 200, 150, 400, "b"), + (3, 3, 0x2000, 2048, 0, 100, 100, 800, "c"), + (4, 2, 0x4000, 4096, 0, 500, 300, 500, "d"), + (5, 2, 0x5000, 512, 0, 400, 700, 600, "e"), + (6, 2, 0x6000, 1024, 0, 400, 500, 1000, "f"), + (7, 3, 0x6000, 1024, 0, 200, 200, 500, "g"), + (8, 2, 0x8000, 2048, 0, 350, 350, 700, "h"), + ], + ) + conn.commit() + conn.close() + return db_path + + +def _execute_cte(db_path: Path, params: dict) -> dict: + ctx = Context(db_path) + executor = QueryExecutor(ctx) + rows = executor.execute_template("memory_peak", params=params, device_id=0) + ctx.close() + return rows[0] + + +def _execute_original(db_path: Path, start_id: int | None, end_id: int | None) -> tuple: + conn = sqlite3.connect(str(db_path)) + try: + return conn.execute(_render_original(start_id, end_id)).fetchone() + finally: + conn.close() + + +@pytest.mark.parametrize( + "start_id, end_id", + [ + (None, None), + (3, None), + (None, 5), + (3, 6), + (5, 5), + (1, 8), + (10, 20), # out of range + (5, 1), # inverted window -- yields empty set + (4, 4), + (None, 3), + ], +) +def test_memory_peak_cte_matches_original( + memory_peak_db: Path, start_id: int | None, end_id: int | None +) -> None: + """The CTE rewrite must be byte-identical to the original nested + subquery form for every start_id/end_id combination (including + inverted and out-of-range windows).""" + expected = _execute_original(memory_peak_db, start_id, end_id) + actual = _execute_cte( + memory_peak_db, + {"start_id": start_id, "end_id": end_id}, + ) + + # Translate the CTE dict into the same column order as ``expected`` so + # tuple comparison works regardless of dict ordering. + if expected is None: + assert actual == {} + return + actual_tuple = tuple( + actual[name] + for name in ( + "peak_allocated", + "peak_allocated_event_id", + "peak_active", + "peak_active_event_id", + "peak_reserved", + "peak_reserved_event_id", + ) + ) + assert actual_tuple == expected + + +def test_memory_peak_null_start_and_end_runs_via_query_service( + memory_peak_db: Path, +) -> None: + """End-to-end smoke test: the rewritten template is reachable through + the QueryService -> QueryExecutor pipeline used by the CLI, MCP server + and SnapshotAnalyzer.""" + from pt_snap_cli.config import Config + from pt_snap_cli.core.query_service import QueryService + + config = Config() + config.write_project_focus(memory_peak_db, device_id=0) + + result = QueryService().execute_query("memory_peak") + + assert result.total == 1 + row = result.rows[0] + assert row["peak_allocated"] == 500 + assert row["peak_allocated_event_id"] == 4 + assert row["peak_active"] == 700 + assert row["peak_active_event_id"] == 5 + assert row["peak_reserved"] == 1000 + assert row["peak_reserved_event_id"] == 6 diff --git a/tests/query/test_query_max_rows_pushdown.py b/tests/query/test_query_max_rows_pushdown.py new file mode 100644 index 0000000..ce3d7c5 --- /dev/null +++ b/tests/query/test_query_max_rows_pushdown.py @@ -0,0 +1,168 @@ +"""End-to-end tests for the ``max_rows`` SQL pushdown that the executor +performs. These exercise the templates touched by issue #76 +(``leak_detection`` and ``callstack_analysis``) to prove that ``max_rows`` +reaches SQL as a ``LIMIT`` clause instead of being applied via Python +slicing in :class:`QueryService`. +""" + +from __future__ import annotations + +import sqlite3 +from pathlib import Path + +import pytest + +from pt_snap_cli.config import Config +from pt_snap_cli.context import Context +from pt_snap_cli.core.query_service import QueryService +from pt_snap_cli.query.executor import QueryExecutor +from pt_snap_cli.query.registry import QueryRegistry, _load_all_templates + + +@pytest.fixture(autouse=True) +def _isolate_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Write project focus into a temp directory so the test run doesn't + pollute the workspace root with a stray ``.pt-snap/focus.json``.""" + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("PT_SNAP_DB_PATH", raising=False) + + +@pytest.fixture(autouse=True) +def _reload_registry() -> None: + QueryRegistry.reset() + _load_all_templates() + + +@pytest.fixture +def leak_db(tmp_path: Path) -> Path: + db_path = tmp_path / "leak.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute(""" + CREATE TABLE trace_entry_0 ( + id INTEGER PRIMARY KEY, + size INTEGER + ) + """) + conn.execute(""" + CREATE TABLE block_0 ( + id INTEGER PRIMARY KEY, + address INTEGER, + size INTEGER, + requestedSize INTEGER, + state INTEGER, + allocEventId INTEGER, + freeEventId INTEGER + ) + """) + # Mix leaked blocks (freeEventId NULL/-1) with cleanly freed ones. + rows = [ + (i, 0x1000 + i * 0x1000, 1024 * (i + 1), 1024 * (i + 1), 1, i + 1, -1) for i in range(10) + ] + rows += [(20 + i, 0xA000 + i * 0x1000, 256, 256, 0, 100 + i, 100 + i + 1) for i in range(5)] + conn.executemany( + """ + INSERT INTO block_0 + (id, address, size, requestedSize, state, allocEventId, freeEventId) + VALUES (?, ?, ?, ?, ?, ?, ?) + """, + rows, + ) + conn.commit() + conn.close() + return db_path + + +@pytest.fixture +def callstack_db(tmp_path: Path) -> Path: + db_path = tmp_path / "callstack.db" + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute(""" + CREATE TABLE trace_entry_0 ( + id INTEGER PRIMARY KEY, + size INTEGER, + callstack TEXT + ) + """) + # 6 callstacks with varying alloc counts so the ``min_count`` filter + # actually has something to drop: + # * 4 callstacks have 10+ entries (pass min_count=5) + # * 2 callstacks have 4 entries each (fail min_count=5) + rows: list[tuple[int, int, str | None]] = [] + callstacks = [ + ("train.py:10", 12), + ("train.py:20", 11), + ("model.py:30", 10), + ("model.py:40", 10), + ("noise.py:50", 4), + ("noise.py:60", 4), + ] + for cs, count in callstacks: + for _ in range(count): + rows.append((len(rows) + 1, 100, cs)) + conn.executemany( + "INSERT INTO trace_entry_0 (id, size, callstack) VALUES (?, ?, ?)", + rows, + ) + conn.commit() + conn.close() + return db_path + + +def _execute_template(db_path: Path, name: str, params: dict) -> list[dict]: + ctx = Context(db_path) + executor = QueryExecutor(ctx) + rows = executor.execute_template(name, params=params, device_id=0) + ctx.close() + return rows + + +class TestLeakDetectionMaxRowsPushdown: + def test_default_returns_all_leaks(self, leak_db: Path) -> None: + rows = _execute_template(leak_db, "leak_detection", {}) + assert len(rows) == 10 + + def test_max_rows_appended_as_limit(self, leak_db: Path) -> None: + """``max_rows`` must push down so SQL returns only N rows.""" + config = Config() + config.write_project_focus(leak_db, device_id=0) + + result = QueryService().execute_query("leak_detection", max_rows=3) + assert result.total == 10 + assert result.returned == 3 + assert len(result.rows) == 3 + + def test_explicit_limit_param_pushes_down(self, leak_db: Path) -> None: + """Users can still pass ``params['limit']`` directly to the + template; the executor does not override a positive limit.""" + rows = _execute_template(leak_db, "leak_detection", {"limit": 4}) + assert len(rows) == 4 + + def test_max_rows_zero_keeps_all_rows(self, leak_db: Path) -> None: + config = Config() + config.write_project_focus(leak_db, device_id=0) + result = QueryService().execute_query("leak_detection", max_rows=0) + assert result.total == 10 + + +class TestCallstackAnalysisMaxRowsPushdown: + def test_default_min_count_filters_noise(self, callstack_db: Path) -> None: + rows = _execute_template(callstack_db, "callstack_analysis", {}) + # Default min_count=5 leaves the four real callstacks. + assert len(rows) == 4 + + def test_max_rows_pushes_down_to_limit(self, callstack_db: Path) -> None: + config = Config() + config.write_project_focus(callstack_db, device_id=0) + result = QueryService().execute_query("callstack_analysis", max_rows=2) + assert result.total == 4 + assert result.returned == 2 + + def test_min_size_filter_combines_with_limit(self, callstack_db: Path) -> None: + rows = _execute_template( + callstack_db, + "callstack_analysis", + {"min_size": 0, "min_count": 1, "limit": 2}, + ) + assert len(rows) == 2 diff --git a/tests/test_query_cache_perf.py b/tests/test_query_cache_perf.py new file mode 100644 index 0000000..7212b01 --- /dev/null +++ b/tests/test_query_cache_perf.py @@ -0,0 +1,78 @@ +"""Performance regression test for :class:`SnapshotAnalyzer` connection reuse. + +The MCP server keeps one :class:`SnapshotAnalyzer` alive across many +``execute_query`` tool calls. Without caching, every call would pay for +schema validation and a fresh ``sqlite3.connect`` URI handshake. This test +exercises the caching path and asserts that ten consecutive calls against +the same database are not catastrophically slower than one call -- a +backstop to catch accidental regressions where the cache is silently +bypassed. +""" + +from __future__ import annotations + +import sqlite3 +import tempfile +import time +from pathlib import Path + +from pt_snap_cli.api import SnapshotAnalyzer + + +def _make_db() -> Path: + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f: + db_path = Path(f.name) + conn = sqlite3.connect(str(db_path)) + conn.execute("CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)") + conn.execute(""" + CREATE TABLE trace_entry_0 ( + id INTEGER PRIMARY KEY, action INTEGER, address INTEGER, + size INTEGER, stream INTEGER, allocated INTEGER, + active INTEGER, reserved INTEGER, callstack TEXT + ) + """) + conn.execute(""" + CREATE TABLE block_0 ( + id INTEGER PRIMARY KEY, address INTEGER, size INTEGER, + requestedSize INTEGER, state INTEGER, allocEventId INTEGER, + freeEventId INTEGER + ) + """) + # Populate enough rows so SQLite does some work, but not so much that + # the test becomes flaky on slow machines. + conn.executemany( + "INSERT INTO block_0 (size, allocEventId, freeEventId) VALUES (?, ?, ?)", + [(1024 * (i + 1), i + 1, -1) for i in range(200)], + ) + conn.commit() + conn.close() + return db_path + + +def test_repeated_execute_query_uses_cached_connection() -> None: + """A single cached connection must serve every call in the loop, so + the cumulative time is dominated by the query cost and not by + connection setup.""" + db_path = _make_db() + try: + analyzer = SnapshotAnalyzer(db_path=db_path) + + # Warm up the cache (first call pays the schema-validation cost). + analyzer.execute_query("leak_detection") + + started = time.perf_counter() + for _ in range(10): + analyzer.execute_query("leak_detection") + elapsed = time.perf_counter() - started + + # The cache should contain exactly one entry after the warmup. + assert len(analyzer.context_cache) == 1 + + # 10 query calls each fetching ~200 rows must finish well under a + # second on any reasonable machine; we use a generous 2 s budget to + # avoid CI flakes while still failing if connection setup is + # accidentally reintroduced per call (that would push elapsed time + # into the multi-second range even on fast disks). + assert elapsed < 2.0, f"10 cached queries took {elapsed:.3f}s" + finally: + db_path.unlink(missing_ok=True) diff --git a/tests/test_snapshot_analyzer_cache.py b/tests/test_snapshot_analyzer_cache.py new file mode 100644 index 0000000..b584c76 --- /dev/null +++ b/tests/test_snapshot_analyzer_cache.py @@ -0,0 +1,111 @@ +"""End-to-end tests for :class:`SnapshotAnalyzer` connection reuse. + +These exercise the path that the MCP server takes: keep one +:class:`SnapshotAnalyzer` alive and call ``execute_query`` repeatedly +against the same database. We assert that: + +* the analyzer reuses a single cached :class:`Context` across calls, +* ``invalidate_context_cache`` forces a fresh context, +* a database file replaced on disk is detected through the mtime probe, +* a fresh schema invalidation surfaces the standard ``DatabaseSchemaError``- + equivalent error to callers. +""" + +from __future__ import annotations + +import os +import sqlite3 +import tempfile +import time +from pathlib import Path + +import pytest + +from pt_snap_cli.api import SnapshotAnalyzer +from pt_snap_cli.core.context_cache import ContextCache + + +@pytest.fixture +def valid_db() -> Path: + with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f: + db_path = Path(f.name) + + conn = sqlite3.connect(str(db_path)) + conn.execute(""" + CREATE TABLE dictionary ( + `table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT + ) + """) + conn.execute(""" + CREATE TABLE trace_entry_0 ( + id INTEGER PRIMARY KEY, action INTEGER, address INTEGER, + size INTEGER, stream INTEGER, allocated INTEGER, + active INTEGER, reserved INTEGER, callstack TEXT + ) + """) + conn.execute(""" + CREATE TABLE block_0 ( + id INTEGER PRIMARY KEY, address INTEGER, size INTEGER, + requestedSize INTEGER, state INTEGER, allocEventId INTEGER, + freeEventId INTEGER + ) + """) + conn.commit() + conn.close() + + yield db_path + db_path.unlink(missing_ok=True) + + +class TestSnapshotAnalyzerContextCache: + def test_repeated_queries_reuse_cached_context(self, valid_db: Path) -> None: + """Two consecutive ``execute_query`` calls must share one cached + Context so that the second call avoids the schema validation + and sqlite3.connect handshake.""" + analyzer = SnapshotAnalyzer(db_path=valid_db) + + first_ctx = analyzer.context_cache.get(valid_db) + analyzer.execute_query("leak_detection") + second_ctx = analyzer.context_cache.get(valid_db) + + assert first_ctx is second_ctx + assert len(analyzer.context_cache) == 1 + + def test_invalidate_context_cache_forces_refresh(self, valid_db: Path) -> None: + analyzer = SnapshotAnalyzer(db_path=valid_db) + + first_ctx = analyzer.context_cache.get(valid_db) + analyzer.invalidate_context_cache(valid_db) + assert len(analyzer.context_cache) == 0 + + second_ctx = analyzer.context_cache.get(valid_db) + assert second_ctx is not first_ctx + + def test_db_file_replacement_invalidates_cache(self, valid_db: Path) -> None: + analyzer = SnapshotAnalyzer(db_path=valid_db) + first_ctx = analyzer.context_cache.get(valid_db) + + # Recreate the file with new content. ``os.replace`` updates + # ``st_mtime`` so the cache's mtime probe invalidates the entry. + time.sleep(0.05) + new_path = valid_db.with_suffix(".new") + conn = sqlite3.connect(str(new_path)) + conn.execute( + "CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT)" + ) + conn.execute("CREATE TABLE trace_entry_1 (id INTEGER PRIMARY KEY)") + conn.commit() + conn.close() + os.replace(new_path, valid_db) + + second_ctx = analyzer.context_cache.get(valid_db) + assert second_ctx is not first_ctx + assert second_ctx.device_ids == [1] + + def test_analyzer_can_use_externally_supplied_cache(self, valid_db: Path) -> None: + shared = ContextCache(maxsize=2) + analyzer = SnapshotAnalyzer(db_path=valid_db, context_cache=shared) + + assert analyzer.context_cache is shared + analyzer.execute_query("leak_detection") + assert len(shared) == 1