feat: run_analytical_query — long-running reads on an isolated pool (#283)

Adds run_analytical_query — a read-only SELECT for genuine analytical work
(large aggregations / joins / window functions) that runs on a DEDICATED
connection pool isolated from the main 5-slot pool, so a long query can't
starve the fast-path tools. Reuses the same pglast allowlist + TenantSqlDriver
(SET LOCAL ROLE / RLS) + read-only transaction as run_select, with an elevated,
bounded timeout: the isolated pool size is the concurrency cap, a per-call
timeout_ms (clamped to the max) is the client budget, and the pool's
statement_timeout is the PG ceiling. A run_select timeout points the agent at
the tool.

Boot-time knobs: MCPG_ENABLE_ANALYTICAL_QUERIES (default true; gates the READ
tool), MCPG_ANALYTICAL_TIMEOUT_MS (120000), MCPG_ANALYTICAL_MAX_TIMEOUT_MS
(600000), MCPG_ANALYTICAL_MAX_CONCURRENCY (2). Primary DB only for now; the
runner is built only in production (mock-DB tests don't spin a real pool).

Surface 253 -> 254; snapshots + doc tables regenerated; test_analytical.py added.
Full unit+contract suite (2859) + mypy/ruff clean.

N/A — reactive capability from the statement-timeout-ceiling analysis.

Author: devopam

CHANGELOG.md

@@ -8,6 +8,24 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **`run_analytical_query` — long-running reads on an isolated pool.**
+  `run_select` is bounded to a short (~30s) timeout on the shared 5-connection
+  pool so an agent can't pin a connection with a runaway query — which made
+  genuine analytical queries (large aggregations / joins / window functions)
+  infeasible, and `MCPG_STATEMENT_TIMEOUT_MS` didn't help (it moves Postgres's
+  `statement_timeout` but not the client-side asyncio cap). The new tool runs a
+  read-only SELECT through the **same** allowlist + tenancy/RLS + read-only
+  transaction, but on a **dedicated connection pool** isolated from the main
+  one, with an **elevated, bounded** timeout — so a slow query can never starve
+  the fast-path tools. A per-call `timeout_ms` (clamped to the max) and optional
+  `work_mem` are exposed; a `run_select` timeout now points the agent at the
+  tool. Boot-time knobs: `MCPG_ENABLE_ANALYTICAL_QUERIES` (default true, gates
+  the tool — it's a READ tool, so set false to withdraw it from an anonymous
+  read-only deployment), `MCPG_ANALYTICAL_TIMEOUT_MS` (default 120000),
+  `MCPG_ANALYTICAL_MAX_TIMEOUT_MS` (600000), `MCPG_ANALYTICAL_MAX_CONCURRENCY`
+  (2 — the isolated pool size, which is also the concurrency cap). Primary
+  database only for now. Tool surface **253 → 254**.
+
 - **Cache-freshness controls for out-of-band schema changes.** MCPg's read
   cache is invalidated automatically by MCPg's own write/DDL tools, but it
   could serve stale introspection/advisor results for up to

CLAUDE.md

@@ -6,7 +6,7 @@ stays true; verify anything here against the code before relying on it.
 ## What MCPg is
 
 A production-grade PostgreSQL MCP server. Single-process, async
-(`asyncio`), Python 3.12–3.14. **253 MCP tools** (read-only mode exposes
+(`asyncio`), Python 3.12–3.14. **254 MCP tools** (read-only mode exposes
 a subset). Ships to PyPI (`mcpg`), GHCR, the MCP registry, Smithery, and
 a read-only HF Spaces demo.
 

README.md

@@ -4,7 +4,7 @@
 
 **A production-grade [Model Context Protocol](https://modelcontextprotocol.io)
 server for PostgreSQL.** Lets AI agents safely inspect, query, operate, and
-tune a Postgres database — 253 tools spanning catalog introspection,
+tune a Postgres database — 254 tools spanning catalog introspection,
 query intelligence, natural-language SQL, structural diffs, hybrid search,
 graph queries, data movement, live ops, and more.
 

docs/architecture.md

@@ -64,7 +64,7 @@ flowchart TD
 ---
 
 <!-- BEGIN generated: module-map (python tools/generate_doc_tables.py --modules) -->
-## Module map (103 modules)
+## Module map (104 modules)
 
 Every `mcpg.*` module and what it owns, alphabetical. The layered
 request path through these lives in the [Overview](#overview) diagram;
@@ -76,6 +76,7 @@ this table is the exhaustive index. Regenerate with
 | `mcpg.about` | MCPg self-description. |
 | `mcpg.advisors` | Schema advisors — codified lint rules over the PG catalog. |
 | `mcpg.aio` | `AIO` — PG 19 asynchronous-I/O subsystem coverage. |
+| `mcpg.analytical` | Long-running analytical read path — an isolated pool, capped concurrency. |
 | `mcpg.audit` | Audit logging of tool invocations and DBA database performance checks. |
 | `mcpg.audit_integrity` | Audit trail verification utility. |
 | `mcpg.audit_nl2sql` | NL→SQL audit table — partitioned, compressed, RLS-gated. |

docs/plans/bm25-integration.md

@@ -6,7 +6,7 @@
 > `pg_search_parse_query`, `hybrid_bm25_vector_search`,
 > `create_pg_search_index`, `reindex_pg_search_index`, plus the
 > observability/advisor tools — see the
-> [tool index](../tools.md#tool-index-253-tools). This doc is kept for
+> [tool index](../tools.md#tool-index-254-tools). This doc is kept for
 > its design rationale and the deferred-alternatives (`pg_textsearch`,
 > `vchord_bm25`) return conditions; it is no longer a live roadmap.
 > Current gaps live in [feature-shortlist.md](../feature-shortlist.md).

docs/plans/pg19-readiness.md

@@ -44,7 +44,7 @@ that accidentally deletes a tool fails CI.
 |---|---|---|
 | 1. CI matrix + compatibility surface | ✅ **Shipped** | PG 19 beta runs as an experimental (`continue-on-error`) matrix entry; pgvector built from source via `.github/ci-postgres-pg19.Dockerfile`. A WarehousePG (MPP) characterisation lane landed alongside. PostGIS still deferred until an apt package is published. |
 | 2. Feature audit | ✅ **Done** | The Beta 1 sweep below is complete — every domain triaged through the product-owner lens. |
-| 3. Incremental landing | ⏳ **Largely shipped** | Many tool families have landed: SQL/PGQ property graphs (`run_pgq`, `create_property_graph`, …), in-server `REPACK` (`repack_table`), skip-scan advisor (`recommend_skip_scan_indexes`), `WAIT FOR LSN` read-your-writes (`wait_for_lsn`), online data-checksum + on-demand logical-replication toggles, DDL introspection (`get_role_ddl` / `get_database_ddl` / `get_tablespace_ddl` / `validate_check_constraint`), partition `MERGE` / `SPLIT`, lock + recovery stats, and async-I/O coverage. See the [tool index](../tools.md#tool-index-253-tools) for the shipped surface and [feature-shortlist.md](../feature-shortlist.md) for the remaining items (tracked to GA). |
+| 3. Incremental landing | ⏳ **Largely shipped** | Many tool families have landed: SQL/PGQ property graphs (`run_pgq`, `create_property_graph`, …), in-server `REPACK` (`repack_table`), skip-scan advisor (`recommend_skip_scan_indexes`), `WAIT FOR LSN` read-your-writes (`wait_for_lsn`), online data-checksum + on-demand logical-replication toggles, DDL introspection (`get_role_ddl` / `get_database_ddl` / `get_tablespace_ddl` / `validate_check_constraint`), partition `MERGE` / `SPLIT`, lock + recovery stats, and async-I/O coverage. See the [tool index](../tools.md#tool-index-254-tools) for the shipped surface and [feature-shortlist.md](../feature-shortlist.md) for the remaining items (tracked to GA). |
 
 ## Phase 1 — what landed
 

docs/plans/pg_turboquant-integration.md

@@ -6,7 +6,7 @@
 > (`turboquant_approx_candidates`, `turboquant_rerank_candidates`,
 > `recommend_turboquant_query_knobs`), `maintain_turboquant_index`
 > (write), and `create_turboquant_index` / `reindex_turboquant_index`
-> (DDL) — see the [tool index](../tools.md#tool-index-253-tools). Kept
+> (DDL) — see the [tool index](../tools.md#tool-index-254-tools). Kept
 > for design rationale; no longer a live roadmap. Current gaps live in
 > [feature-shortlist.md](../feature-shortlist.md).
 

docs/plans/rag-efficiency-suite.md

@@ -6,7 +6,7 @@
 > `analyze_topk_stability`, `analyze_rerank_score_distribution`,
 > `analyze_rerank_ndcg`, `recommend_rerank_strategy`) plus the telemetry
 > capture/threshold tools — see the
-> [tool index](../tools.md#tool-index-253-tools). Kept for design
+> [tool index](../tools.md#tool-index-254-tools). Kept for design
 > rationale; no longer a live roadmap. Current gaps live in
 > [feature-shortlist.md](../feature-shortlist.md).
 

docs/tools.md

@@ -37,7 +37,7 @@ plumbing:
 | `MCPG_NL2SQL_PROVIDER` / `MCPG_NL2SQL_API_KEY` / `MCPG_NL2SQL_MODEL` / `MCPG_NL2SQL_BASE_URL` / `MCPG_NL2SQL_MAX_TOKENS` | `translate_nl_to_sql` provider config — 22 built-in providers + custom (`MCPG_NL2SQL_CUSTOM_PROVIDERS`). |
 
 <!-- BEGIN generated: tool-index (python tools/generate_doc_tables.py --tools) -->
-## Tool index (253 tools)
+## Tool index (254 tools)
 
 Grouped by feature area. The **Gate** column shows the capability
 each tool needs — plain `read` tools are available in every access
@@ -51,7 +51,7 @@ need `unrestricted` **plus** the matching `MCPG_ALLOW_*` opt-in (see
 | **Catalog — schemas / tables / columns** | read | `list_schemas`, `list_tables`, `describe_table`, `list_indexes`, `list_constraints`, `list_foreign_keys`, `list_views`, `list_functions`, `list_triggers`, `list_partitions`, `list_roles`, `list_grants`, `list_policies`, `list_sequences`, `list_enums`, `list_domains`, `list_composite_types`, `list_foreign_data_wrappers`, `list_foreign_servers`, `list_foreign_tables`, `list_user_mappings`, `list_publications`, `list_subscriptions`, `list_extensions`, `list_available_extensions`, `list_generated_columns` |
 | **Catalog — compact** | read | `get_compact_schema` |
 | **Visualisation & structural diff** | read | `generate_schema_diagram`, `generate_fk_cascade_graph`, `generate_schema_docs`, `compare_schemas` |
-| **Query & cursors** | read | `run_select`, `run_select_tuned`, `run_select_parallel`, `open_cursor`, `fetch_cursor`, `close_cursor`, `list_cursors`, `explain_query`, `analyze_query_plan`, `translate_nl_to_sql` |
+| **Query & cursors** | read | `run_select`, `run_select_tuned`, `run_select_parallel`, `open_cursor`, `fetch_cursor`, `close_cursor`, `list_cursors`, `explain_query`, `analyze_query_plan`, `translate_nl_to_sql`, `run_analytical_query` |
 | **Health, tuning & advisors** | read | `check_database_health`, `analyze_table_bloat`, `list_databases`, `audit_database`, `analyze_workload`, `detect_n_plus_one`, `read_autovacuum_priority`, `recommend_indexes`, `recommend_index_drops`, `run_advisors`, `find_unused_objects`, `find_sensitive_columns`, `lint_naming_conventions`, `test_rls_for_role`, `analyze_session_cost`, `recommend_headline_tools`, `audit_sequences`, `audit_settings`, `recommend_postgres_conf`, `optimize_query`, `summarize_table`, `why_is_this_slow` |
 | **Search** | read | `fuzzy_search`, `full_text_search`, `vector_search`, `vector_range_search`, `mmr_search`, `hybrid_search`, `geo_search` |
 | **Test-data factory** | read / **WRITE** (`seed_table_with_sample_data`) | `generate_test_data`, `generate_test_row_for`, `seed_table_with_sample_data` |

docs/tour.md

@@ -6,12 +6,12 @@ surface, not the full catalogue — the exhaustive per-tool reference is
 in [`tools.md`](tools.md), and task-oriented recipes live in
 [`cookbook.md`](cookbook.md).
 
-**253 tools** across 19 capability areas as of trunk. Each line shows
+**254 tools** across 19 capability areas as of trunk. Each line shows
 the tool name + how its parameters land (required first, common
 defaults after). Capability gates are noted in section titles where
 they apply. A few specialist areas (PITR, WarehousePG MPP, Redis FDW,
 SQL/PGQ property graphs, `pg_prewarm`, `pg_repack`, PG 19 runtime
-toggles) aren't walked below — see the [tool index](tools.md#tool-index-253-tools)
+toggles) aren't walked below — see the [tool index](tools.md#tool-index-254-tools)
 for those.
 
 ---