Phase 3: Query Performance & Infrastructure Diagnostics

CHANGELOG.md

@@ -2,6 +2,67 @@
 
 ## 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
+  - Sort by total time, mean time, or call count (`--by total|mean|calls`)
+  - Cache hit ratio per query
+  - Status thresholds: warning >1s mean, critical >5s mean
+  - Graceful degradation when pg_stat_statements not installed
+  - Full JSON support with `pgcrate.diagnostics.queries` schema
+
+- **`pgcrate connections`**: Connection usage analysis
+  - Usage vs max_connections with percentage
+  - Breakdown by state (active, idle, idle in transaction)
+  - Group by user, database, or application (`--by-user`, `--by-database`, `--by-application`)
+  - Status thresholds: warning >75%, critical >90%
+  - Full JSON support with `pgcrate.diagnostics.connections` schema
+
+### Capabilities
+
+- `diagnostics.queries` - Available when pg_stat_statements extension is installed
+- `diagnostics.connections` - Always available (uses pg_stat_activity)
+
+---
+
+**Phase 3b: Bloat + Replication Diagnostics**
+
+### New Commands
+
+- **`pgcrate bloat`**: Estimate table and index bloat
+  - Statistical index bloat estimation (ioguix-style, works without extensions)
+  - Table bloat from dead tuple ratios (pg_stat_user_tables)
+  - Recommendations for VACUUM FULL and REINDEX when critical
+  - `--limit` option to control number of results
+  - Full JSON support with `pgcrate.diagnostics.bloat` schema
+
+- **`pgcrate replication`**: Monitor streaming replication health
+  - Server role detection (primary vs standby)
+  - Replica lag monitoring (write, flush, replay lag)
+  - Replication slot status and WAL retention
+  - WAL receiver info (standby only)
+  - Warning: replay_lag >30s or inactive slot retaining >1GB
+  - Critical: replay_lag >5min or wal_status='lost'
+  - Full JSON support with `pgcrate.diagnostics.replication` schema
+
+### Bug Fixes
+
+- Fix UTF-8 string slicing in `bloat` and `sequences` display (prevents panic on non-ASCII names)
+- Fix XID age type overflow in triage (i32 → i64 for databases with high XID age)
+- Fix triage sequences percentage calculation to match `sequences` command (consistent rounding)
+- Add better error context for XID command on empty databases
+
+### UX Improvements
+
+- Add `migration` as alias for `migrate` command (reduces confusion)
+- Add `create` as alias for `migrate new` command
+
+---
+
 **Phase 2a: Fix Commands**
 
 Complete the diagnose→fix→verify loop with safe remediation commands.

README.md

@@ -143,6 +143,12 @@ 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 bloat                         # Estimate table and index bloat
+pgcrate replication                   # Streaming replication health
+pgcrate queries                       # Top queries (requires pg_stat_statements)
+pgcrate queries --by mean             # Sort by mean execution time
+pgcrate connections                   # Connection usage vs max_connections
+pgcrate connections --by-user         # Group by user
 ```
 
 All diagnostic commands support timeout flags for production safety:
@@ -309,6 +315,10 @@ DROP TABLE users;
 | `pgcrate sequences` | Sequence exhaustion check |
 | `pgcrate indexes` | Missing, unused, duplicate indexes |
 | `pgcrate vacuum` | Table bloat and vacuum health |
+| `pgcrate bloat` | Estimate table and index bloat |
+| `pgcrate replication` | Streaming replication health monitoring |
+| `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,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 bloat                    # Estimate table and index bloat
+pgcrate replication              # Streaming replication health
 
 # Connection context
 pgcrate context --json           # Connection info, server version, privileges
@@ -837,6 +839,8 @@ Currently, `--json` is supported for these commands:
 - `sequences` - Sequence exhaustion check
 - `indexes` - Index health analysis
 - `vacuum` - Table bloat analysis
+- `bloat` - Table and index bloat estimation
+- `replication` - Streaming replication health
 - `fix sequence` - Sequence upgrade result
 - `fix index` - Index drop result
 - `fix vacuum` - Vacuum result