feat: run_analytical_query — long-running reads on an isolated pool

[devopam]

Summary

A follow-up to the timeout analysis: run_select is bounded to a short (~30 s) timeout on the shared 5-connection pool so an agent can't pin a connection with a runaway query — which made genuine analytical queries infeasible, and MCPG_STATEMENT_TIMEOUT_MS didn't help (it moves Postgres's statement_timeout but not the client-side asyncio cap in SafeSqlDriver).

New tool run_analytical_query — a read-only SELECT for real analytical work (large aggregations, multi-table joins, window functions) that:

• validates through the same pglast allowlist + TenantSqlDriver (SET LOCAL ROLE / RLS) + read-only transaction as run_select (reuses query.run_select/run_select_tuned verbatim), and
• runs on a dedicated connection pool (mcpg/analytical.py::AnalyticalRunner) isolated from the main pool and sized to the concurrency cap — so a slow query can never starve the fast-path tools.

The isolated pool size is the concurrency cap; the per-call timeout_ms (clamped to the max) is the client-side budget, with the pool's statement_timeout as the Postgres ceiling. Optional work_mem. A run_select timeout now points the agent at the tool (self-correcting fallback, so it needn't predict duration up front).

Boot-time knobs (the "arguments at boot" you asked for)

Env var	Meaning	Default
MCPG_ENABLE_ANALYTICAL_QUERIES	gates the tool (a READ tool — set false to withdraw it from an anonymous read-only deployment)	true
MCPG_ANALYTICAL_TIMEOUT_MS	default per-call budget	120000 (2 min)
MCPG_ANALYTICAL_MAX_TIMEOUT_MS	hard ceiling; per-call timeout_ms clamped to it	600000 (10 min)
MCPG_ANALYTICAL_MAX_CONCURRENCY	isolated pool size = concurrency cap	2

Read-only only (write/DDL bulk paths deferred); primary database only for now.

Verification (against a live PostgreSQL)

• Basic query on the isolated pool ✓; a heavy generate_series with timeout_ms=300 timed out at 0.3 s ✓; clamp 9e9 → 600 s ✓; pg_sleep/CREATE TABLE rejected by the reused allowlist ✓ (so tenancy/safety carry over).
• Fixed a real integration snag caught by the suite: the analytical runner is now built only when the main DB isn't injected (production), so lifespan tests that mock the DB don't spin up a real second pool and hang.
• Surface 253 → 254; both contract snapshots + tools.md/architecture.md regenerated; counts + anchors updated. New test_analytical.py (clamp, config validation, gating). Full unit + contract suite: 2859 passed; ruff/ruff format/mypy src/mcpg clean.

Roadmap linkage

N/A — reactive capability from your analysis of the statement-timeout ceiling; not a planned roadmap item.

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by Sourcery

Add a dedicated analytical query path and tool for long-running read-only SELECTs, backed by an isolated connection pool with configurable timeouts and concurrency, and wire it into the server lifecycle, configuration, and documentation.

New Features:

• Introduce the run_analytical_query tool for long-running analytical read-only queries with optional timeout and work_mem parameters, sharing validation and result shape with run_select.
• Create an AnalyticalRunner component that manages an isolated database pool for analytical queries with capped concurrency and elevated statement timeout.

Enhancements:

• Update run_select to surface a more helpful error message on timeouts, directing callers to run_analytical_query when analytical queries are enabled.
• Extend server context and lifespan management to own and lifecycle-manage the analytical runner when enabled.
• Expose configuration options and environment variables to control analytical query timeouts, concurrency, and gating, with validation for invalid or inconsistent settings.
• Update tool indexing, capability metadata, and architecture docs to account for the new analytical query module and tool, including tool and module counts.

Tests:

• Add unit tests for AnalyticalRunner timeout clamping and configuration validation, and for conditional registration of the analytical query tool.

[gemini-code-assist-2]

Code Review

This pull request introduces the run_analytical_query tool to execute long-running, read-only analytical queries on an isolated connection pool, preventing slow queries from starving fast-path tools. Feedback suggests broadening the exception check in run_select from 'timed out' to 'timeout' to correctly catch server-side PostgreSQL timeouts and trigger the fallback suggestion. Additionally, it is recommended to refine the error message when the analytical runner is uninitialized to distinguish between disabled queries and an injected mock database.

[gemini-code-assist-2]

The check "timed out" in str(exc).lower() will not match server-side PostgreSQL timeouts, which typically raise an error containing "canceling statement due to statement timeout" (which does not contain the substring "timed out"). Changing this to check for "timeout" ensures that both client-side and server-side timeouts correctly trigger the self-correcting fallback suggestion to use run_analytical_query.

Suggested change

	if settings.enable_analytical_queries and "timed out" in str(exc).lower():
	if settings.enable_analytical_queries and "timeout" in str(exc).lower():

[gemini-code-assist-2]

If analytical_runner is None because a custom or mock database was injected (e.g., during testing or in specific custom environments), raising an error claiming that MCPG_ENABLE_ANALYTICAL_QUERIES=false is misleading and can make debugging difficult. It is better to check the actual setting and raise a more precise error message.

Suggested change

	if runner is None: # defensive: tool only registered when enabled
	raise query.QueryError("analytical queries are disabled (MCPG_ENABLE_ANALYTICAL_QUERIES=false)")
	if runner is None:
	settings = ctx.request_context.lifespan_context.settings
	if not settings.enable_analytical_queries:
	raise query.QueryError("analytical queries are disabled (MCPG_ENABLE_ANALYTICAL_QUERIES=false)")
	raise query.QueryError("analytical runner is not initialized (possibly due to an injected database)")

[sourcery-ai]

Hey - I've left some high level feedback:

• The run_select fallback that checks "timed out" in str(exc).lower() is a bit brittle (and potentially locale-dependent); consider tagging timeout-originated QueryErrors with a specific attribute/flag or subclass so you can branch on a structured signal instead of string matching.
• With an injected database in create_server, enable_analytical_queries=True will still register the run_analytical_query tool but always run with analytical_runner is None and error; if that embedding pattern is expected, it may be worth either wiring an injectable AnalyticalRunner or aligning tool registration with the same condition used when constructing the runner to avoid advertising a non-functional tool.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `run_select` fallback that checks `"timed out" in str(exc).lower()` is a bit brittle (and potentially locale-dependent); consider tagging timeout-originated `QueryError`s with a specific attribute/flag or subclass so you can branch on a structured signal instead of string matching.
- With an injected `database` in `create_server`, `enable_analytical_queries=True` will still register the `run_analytical_query` tool but always run with `analytical_runner is None` and error; if that embedding pattern is expected, it may be worth either wiring an injectable `AnalyticalRunner` or aligning tool registration with the same condition used when constructing the runner to avoid advertising a non-functional tool.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}