pgtriage 0.1.0__tar.gz

pgtriage-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

pgtriage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manas Maheshwari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pgtriage-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: pgtriage
+Version: 0.1.0
+Summary: MCP server for PostgreSQL performance auditing
+Author: Manas Maheshwari
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,database,mcp,performance,postgresql
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.25.0
+Requires-Dist: psycopg[binary]>=3.2.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.14; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pgtriage
+
+MCP server for PostgreSQL performance auditing. Connect it to Claude Code (or any MCP client) and say "audit my database" to get actionable performance findings with exact fixes.
+
+## How it works
+
+```
+Claude Code (AI interpretation)
+       |  MCP (stdio)
+       v
+pgtriage (data collection + pattern detection)
+       |  psycopg3 (read-only)
+       v
+PostgreSQL database
+```
+
+pgtriage connects to your PostgreSQL database and exposes performance auditing tools via the Model Context Protocol. It collects metrics from PostgreSQL system views, runs deterministic pattern detection, and returns structured findings. The MCP client provides the AI layer, interpreting results and explaining fixes in plain English.
+
+No API keys required. No AI costs. The intelligence comes from your MCP client.
+
+## What it finds
+
+- **Sequential scans on large tables** with missing index suggestions
+- **Dead tuple buildup** and autovacuum health issues
+- **Unused and duplicate indexes** wasting disk and slowing writes
+- **N+1 query patterns** from pg_stat_statements analysis
+- **Stale table statistics** causing bad query plans
+- **TOAST table bloat** from large JSONB/TEXT columns
+- **Configuration issues** (shared_buffers, work_mem, autovacuum tuning)
+- **Connection pressure** approaching max_connections
+- **Long-running queries** holding locks
+
+## Quick start
+
+### Install
+
+```bash
+pip install pgtriage
+```
+
+### Configure Claude Code
+
+Add to your MCP settings (`.claude/settings.json` or project settings):
+
+```json
+{
+  "mcpServers": {
+    "pgtriage": {
+      "command": "python",
+      "args": ["-m", "pgtriage"],
+      "env": {
+        "PGAUDIT_CONNECTION_STRING": "postgres://user:pass@localhost:5432/dbname"
+      }
+    }
+  }
+}
+```
+
+### Use
+
+```
+> audit my database
+
+> check table health for the users table
+
+> are there any unused indexes?
+
+> review my PostgreSQL configuration
+
+> find slow queries
+```
+
+## Tools
+
+### `full_audit`
+Run a comprehensive performance audit covering table health, slow queries, index health, and configuration. Returns all findings sorted by severity.
+
+### `check_table_health`
+Analyze dead tuples, autovacuum stats, sequential scan ratios, and TOAST bloat. Optionally filter to a specific table.
+
+### `analyze_slow_queries`
+Pull the slowest queries from `pg_stat_statements`, run `EXPLAIN ANALYZE` on each, and detect patterns like sequential scans, stale statistics, and N+1 queries.
+
+### `check_index_health`
+Find unused indexes (zero scans), duplicate indexes (same column definition), and tables that likely need indexes based on scan patterns.
+
+### `check_config`
+Review PostgreSQL settings (`shared_buffers`, `work_mem`, `autovacuum_vacuum_scale_factor`, `random_page_cost`, etc.) and flag suboptimal values. Checks connection utilization and long-running queries.
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `pgtriage://status` | Connection status, PostgreSQL version, loaded extensions |
+| `pgtriage://tables` | All tables with sizes and approximate row counts |
+
+## Requirements
+
+- Python 3.11+
+- PostgreSQL 12+
+- `pg_stat_statements` extension (recommended for slow query analysis, not required for other tools)
+- Database user with read access to `pg_stat_*` views
+
+## Safety
+
+- All connections enforce `SET default_transaction_read_only = true`
+- `EXPLAIN ANALYZE` only runs on `SELECT` queries (validated before execution)
+- Connection strings are never exposed in tool outputs
+- Single read-only connection, no write operations
+
+## Development
+
+```bash
+git clone https://github.com/pgtriage/pgtriage.git
+cd pgtriage
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pgtriage-0.1.0/README.md

@@ -0,0 +1,124 @@
+# pgtriage
+
+MCP server for PostgreSQL performance auditing. Connect it to Claude Code (or any MCP client) and say "audit my database" to get actionable performance findings with exact fixes.
+
+## How it works
+
+```
+Claude Code (AI interpretation)
+       |  MCP (stdio)
+       v
+pgtriage (data collection + pattern detection)
+       |  psycopg3 (read-only)
+       v
+PostgreSQL database
+```
+
+pgtriage connects to your PostgreSQL database and exposes performance auditing tools via the Model Context Protocol. It collects metrics from PostgreSQL system views, runs deterministic pattern detection, and returns structured findings. The MCP client provides the AI layer, interpreting results and explaining fixes in plain English.
+
+No API keys required. No AI costs. The intelligence comes from your MCP client.
+
+## What it finds
+
+- **Sequential scans on large tables** with missing index suggestions
+- **Dead tuple buildup** and autovacuum health issues
+- **Unused and duplicate indexes** wasting disk and slowing writes
+- **N+1 query patterns** from pg_stat_statements analysis
+- **Stale table statistics** causing bad query plans
+- **TOAST table bloat** from large JSONB/TEXT columns
+- **Configuration issues** (shared_buffers, work_mem, autovacuum tuning)
+- **Connection pressure** approaching max_connections
+- **Long-running queries** holding locks
+
+## Quick start
+
+### Install
+
+```bash
+pip install pgtriage
+```
+
+### Configure Claude Code
+
+Add to your MCP settings (`.claude/settings.json` or project settings):
+
+```json
+{
+  "mcpServers": {
+    "pgtriage": {
+      "command": "python",
+      "args": ["-m", "pgtriage"],
+      "env": {
+        "PGAUDIT_CONNECTION_STRING": "postgres://user:pass@localhost:5432/dbname"
+      }
+    }
+  }
+}
+```
+
+### Use
+
+```
+> audit my database
+
+> check table health for the users table
+
+> are there any unused indexes?
+
+> review my PostgreSQL configuration
+
+> find slow queries
+```
+
+## Tools
+
+### `full_audit`
+Run a comprehensive performance audit covering table health, slow queries, index health, and configuration. Returns all findings sorted by severity.
+
+### `check_table_health`
+Analyze dead tuples, autovacuum stats, sequential scan ratios, and TOAST bloat. Optionally filter to a specific table.
+
+### `analyze_slow_queries`
+Pull the slowest queries from `pg_stat_statements`, run `EXPLAIN ANALYZE` on each, and detect patterns like sequential scans, stale statistics, and N+1 queries.
+
+### `check_index_health`
+Find unused indexes (zero scans), duplicate indexes (same column definition), and tables that likely need indexes based on scan patterns.
+
+### `check_config`
+Review PostgreSQL settings (`shared_buffers`, `work_mem`, `autovacuum_vacuum_scale_factor`, `random_page_cost`, etc.) and flag suboptimal values. Checks connection utilization and long-running queries.
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `pgtriage://status` | Connection status, PostgreSQL version, loaded extensions |
+| `pgtriage://tables` | All tables with sizes and approximate row counts |
+
+## Requirements
+
+- Python 3.11+
+- PostgreSQL 12+
+- `pg_stat_statements` extension (recommended for slow query analysis, not required for other tools)
+- Database user with read access to `pg_stat_*` views
+
+## Safety
+
+- All connections enforce `SET default_transaction_read_only = true`
+- `EXPLAIN ANALYZE` only runs on `SELECT` queries (validated before execution)
+- Connection strings are never exposed in tool outputs
+- Single read-only connection, no write operations
+
+## Development
+
+```bash
+git clone https://github.com/pgtriage/pgtriage.git
+cd pgtriage
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pgtriage-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pgtriage"
+version = "0.1.0"
+description = "MCP server for PostgreSQL performance auditing"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Manas Maheshwari" }]
+keywords = ["postgresql", "mcp", "performance", "audit", "database"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+
+dependencies = [
+    "mcp[cli]>=1.25.0",
+    "psycopg[binary]>=3.2.0",
+    "pydantic>=2.12.0",
+]
+
+[project.scripts]
+pgtriage = "pgtriage:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pgtriage"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.14",
+]

pgtriage-0.1.0/src/pgtriage/__init__.py

@@ -0,0 +1,9 @@
+"""pgtriage - MCP server for PostgreSQL performance auditing."""
+
+__version__ = "0.1.0"
+
+
+def main():
+    from pgtriage.server import mcp
+
+    mcp.run()

pgtriage-0.1.0/src/pgtriage/__main__.py

@@ -0,0 +1,3 @@
+from pgtriage import main
+
+main()

pgtriage-0.1.0/src/pgtriage/analyzers/config_rules.py

@@ -0,0 +1,159 @@
+"""Configuration recommendation rules."""
+
+from pgtriage.models import Category, Finding, Severity
+
+
+def _get_setting(settings: list[dict], name: str) -> str | None:
+    for s in settings:
+        if s["name"] == name:
+            return s["setting"]
+    return None
+
+
+def _parse_memory_kb(value: str, unit: str | None) -> int:
+    """Convert a pg_settings memory value to KB."""
+    num = int(value)
+    if unit == "8kB":
+        return num * 8
+    if unit == "kB":
+        return num
+    if unit == "MB":
+        return num * 1024
+    if unit == "GB":
+        return num * 1024 * 1024
+    return num
+
+
+def _get_setting_with_unit(settings: list[dict], name: str) -> tuple[str | None, str | None]:
+    for s in settings:
+        if s["name"] == name:
+            return s["setting"], s.get("unit")
+    return None, None
+
+
+def analyze_config(
+    settings: list[dict],
+    connection_stats: dict | None,
+) -> list[Finding]:
+    findings = []
+
+    shared_buffers_val, shared_buffers_unit = _get_setting_with_unit(settings, "shared_buffers")
+    if shared_buffers_val and shared_buffers_unit:
+        shared_buffers_kb = _parse_memory_kb(shared_buffers_val, shared_buffers_unit)
+        if shared_buffers_kb < 128 * 1024:
+            findings.append(Finding(
+                severity=Severity.HIGH,
+                category=Category.CONFIG_ISSUE,
+                detail=(
+                    f"shared_buffers is {shared_buffers_kb // 1024}MB. "
+                    f"For production workloads, this should typically be 25% of available RAM "
+                    f"(minimum 128MB for small instances)."
+                ),
+                suggested_fix="ALTER SYSTEM SET shared_buffers = '256MB'; -- then restart PostgreSQL",
+                requires_downtime=True,
+                evidence={"shared_buffers_kb": shared_buffers_kb},
+            ))
+
+    work_mem_val, work_mem_unit = _get_setting_with_unit(settings, "work_mem")
+    if work_mem_val and work_mem_unit:
+        work_mem_kb = _parse_memory_kb(work_mem_val, work_mem_unit)
+        if work_mem_kb <= 4 * 1024:
+            findings.append(Finding(
+                severity=Severity.LOW,
+                category=Category.CONFIG_ISSUE,
+                detail=(
+                    f"work_mem is at default ({work_mem_kb // 1024}MB). "
+                    f"Complex queries with sorts and hash joins may spill to disk. "
+                    f"Consider increasing for workloads with complex queries."
+                ),
+                suggested_fix="ALTER SYSTEM SET work_mem = '16MB'; -- then SELECT pg_reload_conf();",
+                evidence={"work_mem_kb": work_mem_kb},
+            ))
+
+    autovacuum_sf = _get_setting(settings, "autovacuum_vacuum_scale_factor")
+    if autovacuum_sf:
+        sf_val = float(autovacuum_sf)
+        if sf_val > 0.1:
+            findings.append(Finding(
+                severity=Severity.MEDIUM,
+                category=Category.CONFIG_ISSUE,
+                detail=(
+                    f"autovacuum_vacuum_scale_factor is {sf_val} (default 0.2). "
+                    f"For large tables, this means autovacuum won't trigger until 20% of rows are dead. "
+                    f"On a 10M row table, that's 2M dead rows before cleanup starts."
+                ),
+                suggested_fix=(
+                    "For high-churn tables, set per-table: "
+                    "ALTER TABLE <table> SET (autovacuum_vacuum_scale_factor = 0.01);"
+                ),
+                evidence={"autovacuum_vacuum_scale_factor": sf_val},
+            ))
+
+    random_page_cost = _get_setting(settings, "random_page_cost")
+    if random_page_cost and float(random_page_cost) > 1.5:
+        findings.append(Finding(
+            severity=Severity.LOW,
+            category=Category.CONFIG_ISSUE,
+            detail=(
+                f"random_page_cost is {random_page_cost} (default 4.0). "
+                f"If your database is on SSD storage, a value of 1.1 better reflects "
+                f"actual random read performance and helps the planner choose index scans."
+            ),
+            suggested_fix="ALTER SYSTEM SET random_page_cost = 1.1; -- then SELECT pg_reload_conf();",
+            evidence={"random_page_cost": float(random_page_cost)},
+        ))
+
+    log_min_duration = _get_setting(settings, "log_min_duration_statement")
+    if log_min_duration and int(log_min_duration) < 0:
+        findings.append(Finding(
+            severity=Severity.INFO,
+            category=Category.CONFIG_ISSUE,
+            detail=(
+                "log_min_duration_statement is disabled (-1). "
+                "Enabling it helps identify slow queries in PostgreSQL logs."
+            ),
+            suggested_fix=(
+                "ALTER SYSTEM SET log_min_duration_statement = 1000; "
+                "-- logs queries taking > 1 second"
+            ),
+            evidence={"log_min_duration_statement": int(log_min_duration)},
+        ))
+
+    if connection_stats:
+        total = connection_stats.get("total_connections", 0)
+        max_conn = connection_stats.get("max_connections", 100)
+        utilization = total / max(max_conn, 1) * 100
+
+        if utilization > 80:
+            findings.append(Finding(
+                severity=Severity.HIGH,
+                category=Category.CONNECTION_PRESSURE,
+                detail=(
+                    f"Connection utilization at {utilization:.0f}% "
+                    f"({total}/{max_conn}). "
+                    f"Approaching max_connections limit."
+                ),
+                suggested_fix=(
+                    "Consider using a connection pooler (PgBouncer) or "
+                    "increasing max_connections if RAM allows."
+                ),
+                evidence={
+                    "total_connections": total,
+                    "max_connections": max_conn,
+                    "utilization_pct": round(utilization, 1),
+                },
+            ))
+
+        long_running = connection_stats.get("long_running_queries", 0)
+        if long_running > 0:
+            findings.append(Finding(
+                severity=Severity.HIGH,
+                category=Category.LONG_RUNNING_QUERY,
+                detail=(
+                    f"{long_running} queries running for more than 30 seconds. "
+                    f"Long-running queries hold locks and prevent autovacuum."
+                ),
+                evidence={"long_running_queries": long_running},
+            ))
+
+    return findings

pgtriage-0.1.0/src/pgtriage/analyzers/explain.py

@@ -0,0 +1,128 @@
+"""EXPLAIN ANALYZE runner and execution plan analyzer."""
+
+import re
+
+from pgtriage.connection import ConnectionManager
+from pgtriage.models import Category, Finding, Severity
+
+SELECT_PATTERN = re.compile(r"^\s*SELECT\b", re.IGNORECASE)
+STACKED_QUERY_PATTERN = re.compile(r";\s*\S")
+
+
+async def run_explain_analyze(
+    db: ConnectionManager,
+    query: str,
+) -> dict | None:
+    """Run EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) on a SELECT query.
+    Returns the JSON plan or None if the query is not safe to run."""
+    if not SELECT_PATTERN.match(query):
+        return None
+    if STACKED_QUERY_PATTERN.search(query):
+        return None
+
+    clean_query = query.rstrip().rstrip(";")
+    explain_sql = f"EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) {clean_query}"
+
+    row = await db.fetch_one(explain_sql)
+    if row and "QUERY PLAN" in row:
+        return row["QUERY PLAN"]
+    return None
+
+
+def detect_plan_issues(
+    plan_json: list[dict],
+    original_query: str | None = None,
+) -> list[Finding]:
+    """Analyze an EXPLAIN ANALYZE JSON plan for performance issues."""
+    if not plan_json:
+        return []
+
+    findings = []
+    plan = plan_json[0].get("Plan", {})
+    _walk_plan_node(plan, findings, original_query)
+    return findings
+
+
+def _walk_plan_node(
+    node: dict,
+    findings: list[Finding],
+    original_query: str | None = None,
+) -> None:
+    node_type = node.get("Node Type", "")
+    relation = node.get("Relation Name")
+    actual_rows = node.get("Actual Rows", 0)
+    plan_rows = node.get("Plan Rows", 0)
+
+    if node_type == "Seq Scan" and actual_rows > 100_000:
+        filter_text = node.get("Filter", "")
+        findings.append(Finding(
+            severity=Severity.HIGH if actual_rows > 1_000_000 else Severity.MEDIUM,
+            category=Category.SEQUENTIAL_SCAN,
+            table=relation,
+            query=original_query,
+            detail=(
+                f"Sequential scan on '{relation}' reading {actual_rows:,} rows. "
+                f"Filter: {filter_text or 'none'}. "
+                f"An index on the filtered columns would likely eliminate this scan."
+            ),
+            estimated_impact=f"Scanning {actual_rows:,} rows instead of targeted index lookup",
+            suggested_fix=(
+                f"Identify the columns in the WHERE clause and create a targeted index: "
+                f"CREATE INDEX CONCURRENTLY ON {relation} (...);"
+                if relation else None
+            ),
+            evidence={
+                "node_type": node_type,
+                "actual_rows": actual_rows,
+                "filter": filter_text,
+                "relation": relation,
+            },
+        ))
+
+    if plan_rows > 0 and actual_rows > 0:
+        estimate_ratio = actual_rows / max(plan_rows, 1)
+        if estimate_ratio > 10 or estimate_ratio < 0.1:
+            findings.append(Finding(
+                severity=Severity.MEDIUM,
+                category=Category.STALE_STATS,
+                table=relation,
+                query=original_query,
+                detail=(
+                    f"Row estimate is off by {estimate_ratio:.1f}x on '{relation or 'unknown'}'. "
+                    f"Planned: {plan_rows:,}, actual: {actual_rows:,}. "
+                    f"Table statistics may be stale, causing the planner to pick a bad strategy."
+                ),
+                suggested_fix=f"ANALYZE {relation};" if relation else "Run ANALYZE on the relevant tables.",
+                evidence={
+                    "planned_rows": plan_rows,
+                    "actual_rows": actual_rows,
+                    "estimate_ratio": round(estimate_ratio, 2),
+                    "relation": relation,
+                },
+            ))
+
+    if node_type == "Nested Loop" and actual_rows > 10_000:
+        inner = node.get("Plans", [{}])
+        inner_type = inner[-1].get("Node Type", "") if inner else ""
+        if inner_type == "Seq Scan":
+            inner_relation = inner[-1].get("Relation Name", "unknown")
+            findings.append(Finding(
+                severity=Severity.HIGH,
+                category=Category.MISSING_INDEX,
+                query=original_query,
+                detail=(
+                    f"Nested loop join with sequential scan on '{inner_relation}' "
+                    f"processing {actual_rows:,} rows. "
+                    f"A hash join or index lookup would be faster."
+                ),
+                estimated_impact="Nested loop + seq scan is the slowest join strategy",
+                evidence={
+                    "outer_type": node_type,
+                    "inner_type": inner_type,
+                    "actual_rows": actual_rows,
+                    "inner_relation": inner_relation,
+                },
+            ))
+
+    for child in node.get("Plans", []):
+        _walk_plan_node(child, findings, original_query)