pgtriage 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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)

pgtriage/analyzers/patterns.py

@@ -0,0 +1,182 @@
+"""Deterministic pattern detection on PostgreSQL metrics."""
+
+from datetime import datetime, timezone
+
+from pgtriage.models import Category, Finding, Severity
+
+DEAD_TUPLE_THRESHOLD_PCT = 10.0
+LARGE_TABLE_ROWS = 100_000
+SEQ_SCAN_RATIO_THRESHOLD = 80.0
+VACUUM_STALE_HOURS = 24
+TOAST_BLOAT_RATIO = 0.5
+
+
+def analyze_dead_tuples(table_stats: list[dict]) -> list[Finding]:
+    findings = []
+    for t in table_stats:
+        dead_pct = float(t.get("dead_tuple_pct", 0))
+        dead_count = t.get("n_dead_tup", 0)
+        live_count = t.get("n_live_tup", 0)
+
+        if dead_pct <= DEAD_TUPLE_THRESHOLD_PCT or dead_count < 1000:
+            continue
+
+        if dead_pct > 30:
+            severity = Severity.CRITICAL
+        elif dead_pct > 20:
+            severity = Severity.HIGH
+        else:
+            severity = Severity.MEDIUM
+
+        findings.append(Finding(
+            severity=severity,
+            category=Category.DEAD_TUPLES,
+            table=t["table_name"],
+            detail=(
+                f"Table has {dead_count:,} dead tuples ({dead_pct}% of total rows). "
+                f"Live rows: {live_count:,}. "
+                f"Autovacuum may not be keeping up with the write volume."
+            ),
+            estimated_impact="Table bloat increases query times and disk usage",
+            suggested_fix=(
+                f"VACUUM (VERBOSE) {t['table_name']}; "
+                f"-- or for severe cases: VACUUM FULL {t['table_name']}; "
+                f"(requires exclusive lock)"
+            ),
+            safe_to_apply=True,
+            requires_downtime=False,
+            evidence={
+                "dead_tuples": dead_count,
+                "live_tuples": live_count,
+                "dead_tuple_pct": dead_pct,
+                "autovacuum_count": t.get("autovacuum_count", 0),
+            },
+        ))
+    return findings
+
+
+def analyze_sequential_scans(table_stats: list[dict]) -> list[Finding]:
+    findings = []
+    for t in table_stats:
+        live_rows = t.get("n_live_tup", 0)
+        seq_scan_pct = float(t.get("seq_scan_pct", 0))
+        seq_scans = t.get("seq_scan", 0)
+        idx_scans = t.get("idx_scan", 0)
+
+        if live_rows < LARGE_TABLE_ROWS:
+            continue
+        if seq_scan_pct < SEQ_SCAN_RATIO_THRESHOLD:
+            continue
+        if seq_scans < 100:
+            continue
+
+        if live_rows > 1_000_000:
+            severity = Severity.HIGH
+        else:
+            severity = Severity.MEDIUM
+
+        findings.append(Finding(
+            severity=severity,
+            category=Category.SEQUENTIAL_SCAN,
+            table=t["table_name"],
+            detail=(
+                f"Table has {live_rows:,} rows with {seq_scan_pct}% sequential scans "
+                f"({seq_scans:,} seq vs {idx_scans:,} idx). "
+                f"Likely missing an index on frequently queried columns."
+            ),
+            estimated_impact="Sequential scans on large tables cause slow queries under load",
+            suggested_fix=(
+                f"Identify the most common WHERE clauses on {t['table_name']} "
+                f"and add targeted indexes with CREATE INDEX CONCURRENTLY."
+            ),
+            evidence={
+                "live_rows": live_rows,
+                "seq_scans": seq_scans,
+                "idx_scans": idx_scans,
+                "seq_scan_pct": seq_scan_pct,
+            },
+        ))
+    return findings
+
+
+def analyze_vacuum_staleness(table_stats: list[dict]) -> list[Finding]:
+    findings = []
+    now = datetime.now(timezone.utc)
+
+    for t in table_stats:
+        dead_count = t.get("n_dead_tup", 0)
+        if dead_count < 1000:
+            continue
+
+        last_vacuum = t.get("last_autovacuum") or t.get("last_vacuum")
+        if last_vacuum is None:
+            findings.append(Finding(
+                severity=Severity.MEDIUM,
+                category=Category.AUTOVACUUM_LAG,
+                table=t["table_name"],
+                detail=(
+                    f"Table has never been vacuumed but has {dead_count:,} dead tuples. "
+                    f"Autovacuum may not be configured or may not have triggered yet."
+                ),
+                suggested_fix=f"VACUUM ANALYZE {t['table_name']};",
+                evidence={"dead_tuples": dead_count, "last_vacuum": None},
+            ))
+            continue
+
+        if last_vacuum.tzinfo is None:
+            last_vacuum = last_vacuum.replace(tzinfo=timezone.utc)
+
+        hours_since = (now - last_vacuum).total_seconds() / 3600
+        if hours_since > VACUUM_STALE_HOURS and dead_count > 10_000:
+            findings.append(Finding(
+                severity=Severity.MEDIUM,
+                category=Category.AUTOVACUUM_LAG,
+                table=t["table_name"],
+                detail=(
+                    f"Table has {dead_count:,} dead tuples and hasn't been vacuumed "
+                    f"in {hours_since:.0f} hours. Last vacuum: {last_vacuum}."
+                ),
+                suggested_fix=f"VACUUM ANALYZE {t['table_name']};",
+                evidence={
+                    "dead_tuples": dead_count,
+                    "hours_since_vacuum": round(hours_since, 1),
+                    "last_vacuum": str(last_vacuum),
+                },
+            ))
+    return findings
+
+
+def analyze_table_bloat(table_sizes: list[dict]) -> list[Finding]:
+    findings = []
+    for t in table_sizes:
+        table_bytes = t.get("table_size_bytes", 0)
+        toast_bytes = t.get("toast_size_bytes", 0)
+
+        if table_bytes < 10_000_000:
+            continue
+        if toast_bytes <= 0:
+            continue
+
+        toast_ratio = toast_bytes / max(table_bytes, 1)
+        if toast_ratio < TOAST_BLOAT_RATIO:
+            continue
+
+        findings.append(Finding(
+            severity=Severity.MEDIUM,
+            category=Category.TOAST_BLOAT,
+            table=t["table_name"],
+            detail=(
+                f"TOAST storage ({t.get('toast_size', 'N/A')}) is "
+                f"{toast_ratio:.1f}x the table size ({t.get('table_size', 'N/A')}). "
+                f"Large JSONB or TEXT columns may be causing bloat. "
+                f"TOAST tables have separate autovacuum tracking and can lag behind."
+            ),
+            estimated_impact="TOAST bloat increases disk usage and slows full table operations",
+            evidence={
+                "table_size": t.get("table_size"),
+                "toast_size": t.get("toast_size"),
+                "total_size": t.get("total_size"),
+                "toast_ratio": round(toast_ratio, 2),
+            },
+        ))
+    return findings

pgtriage/collectors/config.py

@@ -0,0 +1,63 @@
+"""Collect PostgreSQL configuration and connection stats."""
+
+from pgtriage.connection import ConnectionManager
+
+CONFIG_SETTINGS_QUERY = """
+SELECT name, setting, unit, short_desc, context, boot_val, reset_val
+FROM pg_settings
+WHERE name IN (
+    'max_connections',
+    'shared_buffers',
+    'effective_cache_size',
+    'work_mem',
+    'maintenance_work_mem',
+    'random_page_cost',
+    'seq_page_cost',
+    'default_statistics_target',
+    'checkpoint_completion_target',
+    'wal_buffers',
+    'min_wal_size',
+    'max_wal_size',
+    'autovacuum',
+    'autovacuum_max_workers',
+    'autovacuum_vacuum_threshold',
+    'autovacuum_vacuum_scale_factor',
+    'autovacuum_analyze_threshold',
+    'autovacuum_analyze_scale_factor',
+    'autovacuum_vacuum_cost_delay',
+    'autovacuum_vacuum_cost_limit',
+    'log_min_duration_statement',
+    'track_activity_query_size'
+)
+ORDER BY name
+"""
+
+CONNECTION_STATS_QUERY = """
+SELECT
+    (SELECT count(*) FROM pg_stat_activity) AS total_connections,
+    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections,
+    (SELECT count(*) FROM pg_stat_activity WHERE state = 'active') AS active_queries,
+    (SELECT count(*) FROM pg_stat_activity WHERE state = 'idle') AS idle_connections,
+    (SELECT count(*) FROM pg_stat_activity
+     WHERE state = 'active'
+       AND now() - query_start > interval '30 seconds') AS long_running_queries
+"""
+
+DATABASE_INFO_QUERY = """
+SELECT
+    pg_size_pretty(pg_database_size(current_database())) AS database_size,
+    current_database() AS database_name,
+    (SELECT setting FROM pg_settings WHERE name = 'server_version') AS pg_version
+"""
+
+
+async def collect_config_settings(db: ConnectionManager) -> list[dict]:
+    return await db.fetch_all(CONFIG_SETTINGS_QUERY)
+
+
+async def collect_connection_stats(db: ConnectionManager) -> dict | None:
+    return await db.fetch_one(CONNECTION_STATS_QUERY)
+
+
+async def collect_database_info(db: ConnectionManager) -> dict | None:
+    return await db.fetch_one(DATABASE_INFO_QUERY)

pgtriage/collectors/index_health.py

@@ -0,0 +1,84 @@
+"""Collect index health metrics from PostgreSQL system views."""
+
+from pgtriage.connection import ConnectionManager
+
+UNUSED_INDEXES_QUERY = """
+SELECT
+    s.schemaname,
+    s.relname AS table_name,
+    s.indexrelname AS index_name,
+    s.idx_scan AS scans_since_reset,
+    pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size,
+    pg_relation_size(s.indexrelid) AS index_size_bytes,
+    pg_get_indexdef(i.indexrelid) AS index_definition,
+    i.indisunique AS is_unique,
+    i.indisprimary AS is_primary
+FROM pg_stat_user_indexes s
+JOIN pg_index i ON s.indexrelid = i.indexrelid
+WHERE s.idx_scan = 0
+  AND NOT i.indisunique
+  AND NOT i.indisprimary
+  AND s.schemaname = %s
+ORDER BY pg_relation_size(s.indexrelid) DESC
+"""
+
+DUPLICATE_INDEXES_QUERY = """
+SELECT
+    a.indrelid::regclass AS table_name,
+    a.indexrelid::regclass AS index_1,
+    b.indexrelid::regclass AS index_2,
+    pg_get_indexdef(a.indexrelid) AS index_1_def,
+    pg_get_indexdef(b.indexrelid) AS index_2_def,
+    pg_size_pretty(pg_relation_size(a.indexrelid)) AS index_1_size,
+    pg_size_pretty(pg_relation_size(b.indexrelid)) AS index_2_size,
+    pg_relation_size(a.indexrelid) AS index_1_size_bytes,
+    pg_relation_size(b.indexrelid) AS index_2_size_bytes
+FROM pg_index a
+JOIN pg_index b ON a.indrelid = b.indrelid
+    AND a.indexrelid < b.indexrelid
+    AND a.indkey::text = b.indkey::text
+JOIN pg_namespace n ON n.oid = (
+    SELECT relnamespace FROM pg_class WHERE oid = a.indrelid
+)
+WHERE n.nspname = %s
+ORDER BY pg_relation_size(a.indexrelid) + pg_relation_size(b.indexrelid) DESC
+"""
+
+TABLES_NEEDING_INDEXES_QUERY = """
+SELECT
+    schemaname,
+    relname AS table_name,
+    seq_scan,
+    idx_scan,
+    n_live_tup,
+    seq_tup_read,
+    CASE WHEN seq_scan > 0
+         THEN seq_tup_read / seq_scan
+         ELSE 0 END AS avg_rows_per_seq_scan
+FROM pg_stat_user_tables
+WHERE n_live_tup > 100000
+  AND seq_scan > idx_scan
+  AND seq_scan > 100
+ORDER BY seq_tup_read DESC
+LIMIT 20
+"""
+
+
+async def collect_unused_indexes(
+    db: ConnectionManager,
+    schema_name: str = "public",
+) -> list[dict]:
+    return await db.fetch_all(UNUSED_INDEXES_QUERY, (schema_name,))
+
+
+async def collect_duplicate_indexes(
+    db: ConnectionManager,
+    schema_name: str = "public",
+) -> list[dict]:
+    return await db.fetch_all(DUPLICATE_INDEXES_QUERY, (schema_name,))
+
+
+async def collect_tables_needing_indexes(
+    db: ConnectionManager,
+) -> list[dict]:
+    return await db.fetch_all(TABLES_NEEDING_INDEXES_QUERY)