Phase 3a: Query performance diagnostics

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+**Phase 3a: Query Performance Diagnostics**
+
+Complete the "why is prod slow?" workflow with query and connection analysis.
+
+### New Commands
+
+- **`pgcrate queries`**: Top queries from pg_stat_statements by execution time, mean time, or call count
+- **`pgcrate connections`**: Connection usage analysis vs max_connections with breakdown by state, user, and database
+
+### Queries Command Features
+
+- **Sort options**: `--by total` (default), `--by mean`, `--by calls`
+- **Limit control**: `--limit N` (default: 10) or `--all` for all tracked queries
+- **Graceful degradation**: Works without pg_stat_statements extension (shows unavailable message)
+- **Cache hit ratio**: Shows buffer cache efficiency per query
+- **Status thresholds**: Critical (mean > 5s), Warning (mean > 1s), Healthy (< 1s)
+
+### Connections Command Features
+
+- **Usage analysis**: Total connections vs max_connections with percentage
+- **State breakdown**: Connections grouped by state (active, idle, idle in transaction)
+- **Grouping options**: `--by-user` and `--by-database` for detailed analysis
+- **Status thresholds**: Critical (> 90%), Warning (> 75%), Healthy (< 75%)
+
+### Capabilities
+
+- `diagnostics.queries` capability added (requires pg_stat_statements extension)
+- `diagnostics.connections` capability added (always available via pg_stat_activity)
+
+---
+
 **Phase 2a: Fix Commands**
 
 Complete the diagnose→fix→verify loop with safe remediation commands.

README.md

@@ -143,6 +143,8 @@ pgcrate xid                           # Transaction ID wraparound analysis
 pgcrate sequences                     # Sequence exhaustion check
 pgcrate indexes                       # Missing, unused, duplicate indexes
 pgcrate vacuum                        # Table bloat and vacuum health
+pgcrate queries                       # Top queries from pg_stat_statements
+pgcrate connections                   # Connection usage vs max_connections
 ```
 
 All diagnostic commands support timeout flags for production safety:
@@ -309,6 +311,8 @@ DROP TABLE users;
 | `pgcrate sequences` | Sequence exhaustion check |
 | `pgcrate indexes` | Missing, unused, duplicate indexes |
 | `pgcrate vacuum` | Table bloat and vacuum health |
+| `pgcrate queries` | Top queries from pg_stat_statements |
+| `pgcrate connections` | Connection usage vs max_connections |
 | `pgcrate fix sequence` | Upgrade sequence type to prevent exhaustion |
 | `pgcrate fix index` | Drop unused/duplicate indexes |
 | `pgcrate fix vacuum` | Run VACUUM on tables |

llms.txt

@@ -752,6 +752,13 @@ pgcrate xid                      # Transaction ID wraparound analysis
 pgcrate sequences                # Sequence exhaustion check
 pgcrate indexes                  # Missing, unused, duplicate indexes
 pgcrate vacuum                   # Table bloat and vacuum health
+pgcrate queries                  # Top queries from pg_stat_statements
+pgcrate queries --by mean        # Sort by mean execution time
+pgcrate queries --by calls       # Sort by call count
+pgcrate queries --limit 20       # Show more queries
+pgcrate connections              # Connection usage vs max_connections
+pgcrate connections --by-user    # Group by user
+pgcrate connections --by-database # Group by database
 
 # Connection context
 pgcrate context --json           # Connection info, server version, privileges
@@ -837,6 +844,8 @@ Currently, `--json` is supported for these commands:
 - `sequences` - Sequence exhaustion check
 - `indexes` - Index health analysis
 - `vacuum` - Table bloat analysis
+- `queries` - Query performance analysis
+- `connections` - Connection usage analysis
 - `fix sequence` - Sequence upgrade result
 - `fix index` - Index drop result
 - `fix vacuum` - Vacuum result

src/commands/capabilities.rs

@@ -116,8 +116,10 @@ pub async fn run_capabilities(client: &Client, read_only: bool) -> Result<Capabi
             requirements: vec![],
             limitations: vec![],
         },
-        // diagnostics.queries - needs pg_stat_statements (Phase 3, not yet implemented)
+        // diagnostics.queries - needs pg_stat_statements
         check_queries_capability(has_pg_stat_statements),
+        // diagnostics.connections - needs pg_stat_activity
+        check_connections_capability(has_pg_stat_activity),
         // fix.sequence - needs write access and pg_sequences
         check_fix_sequence_capability(has_pg_sequences, read_only),
         // fix.cancel - needs pg_cancel_backend
@@ -385,24 +387,46 @@ fn check_queries_capability(has_pg_stat_statements: bool) -> CapabilityInfo {
             )],
         )
     } else {
-        // Even with the extension, this capability is not yet implemented
+        (CapabilityStatus::Available, vec![])
+    };
+
+    CapabilityInfo {
+        id: "diagnostics.queries",
+        name: "Query Analysis",
+        description: "Slow query identification (pg_stat_statements)",
+        status,
+        reasons,
+        requirements,
+        limitations: vec![],
+    }
+}
+
+fn check_connections_capability(has_pg_stat_activity: bool) -> CapabilityInfo {
+    let requirements = vec![Requirement {
+        what: "pg_stat_activity SELECT".to_string(),
+        met: has_pg_stat_activity,
+    }];
+
+    let (status, reasons) = if !has_pg_stat_activity {
         (
             CapabilityStatus::Unavailable,
             vec![ReasonInfo::new(
-                ReasonCode::NotApplicable,
-                "Query analysis not yet implemented (planned for Phase 3)",
+                ReasonCode::MissingPrivilege,
+                "Cannot read pg_stat_activity",
             )],
         )
+    } else {
+        (CapabilityStatus::Available, vec![])
     };
 
     CapabilityInfo {
-        id: "diagnostics.queries",
-        name: "Query Analysis",
-        description: "Slow query identification (pg_stat_statements)",
+        id: "diagnostics.connections",
+        name: "Connections",
+        description: "Connection usage analysis",
         status,
         reasons,
         requirements,
-        limitations: vec!["Not yet implemented".to_string()],
+        limitations: vec![],
     }
 }