claudekit/reports/agent-research/database/postgres-expert-matrix.csv

CLI tools for Claude Code development workflow

Category,Symptom/Error,Root Cause,Fix 1,Fix 2,Fix 3,Diagnostic Command,Validation Step,Official Link
Performance,Query taking too long,Missing or inefficient indexes,Add basic index on WHERE clause columns,Create composite index for multi-column queries,Analyze query plan and create optimal index strategy with partial indexes,EXPLAIN ANALYZE SELECT ...,Check execution time and plan cost,https://www.postgresql.org/docs/current/sql-explain.html
Performance,Sequential scan on large table,No suitable index available,CREATE INDEX on frequently queried columns,Create composite index matching query patterns,Implement covering index with INCLUDE clause,EXPLAIN (ANALYZE BUFFERS) SELECT ...,Verify index scan is used instead of seq scan,https://www.postgresql.org/docs/current/indexes-types.html
Performance,High shared_buffers cache miss,Insufficient shared memory allocation,Increase shared_buffers to 25% of RAM,Tune effective_cache_size to total available memory,Optimize work_mem and maintenance_work_mem based on workload,SELECT * FROM pg_stat_bgwriter,Monitor blks_hit ratio >95%,https://www.postgresql.org/docs/current/runtime-config-resource.html
JSONB,JSONB queries are slow,Missing GIN index on JSONB column,CREATE INDEX USING GIN on JSONB column,Use jsonb_path_ops for containment queries,Create expression indexes for specific JSON paths,EXPLAIN SELECT * FROM table WHERE jsonb_col @> '{}',Verify GIN index is used in query plan,https://www.postgresql.org/docs/current/datatype-json.html
JSONB,JSONPath query not using index,Incompatible operator class for query type,Use jsonb_ops for key existence queries,Create appropriate expression index for path,Optimize query to use indexable operators,EXPLAIN SELECT * FROM table WHERE jsonb_col @? '$.path',Check if Bitmap Heap Scan is used,https://www.postgresql.org/docs/current/functions-json.html
Indexing,Index not being used,Query doesn't match index columns,Reorder WHERE clause columns to match index,Create multi-column index with correct column order,Add partial index with WHERE condition for filtered queries,EXPLAIN SELECT * FROM table WHERE col1 = ? AND col2 = ?,Verify Index Scan or Bitmap Index Scan in plan,https://www.postgresql.org/docs/current/indexes-multicolumn.html
Indexing,Duplicate or unused indexes,Multiple indexes serving same purpose,Drop obviously redundant indexes,Analyze index usage with pg_stat_user_indexes,Implement comprehensive index audit and cleanup strategy,SELECT * FROM pg_stat_user_indexes WHERE idx_scan = 0,Confirm idx_scan increases for remaining indexes,https://www.postgresql.org/docs/current/monitoring-stats.html
Connection,Too many connections error,max_connections limit exceeded,Increase max_connections temporarily,Implement connection pooling with PgBouncer,Configure connection pooling + optimize application connection handling,SELECT count(*) FROM pg_stat_activity,Monitor active connections <80% of max,https://www.postgresql.org/docs/current/runtime-config-connection.html
Connection,Connection timeouts,Long-running queries blocking connections,Set statement_timeout to reasonable value,Optimize slow queries causing timeouts,Implement query timeout + connection pooling + query optimization,SELECT pid query_start query FROM pg_stat_activity WHERE state = 'active',Verify no queries run longer than expected timeout,https://www.postgresql.org/docs/current/runtime-config-client.html
Autovacuum,Table bloat increasing,Autovacuum not keeping up with updates,Run manual VACUUM on heavily updated tables,Tune autovacuum_vacuum_scale_factor for table,Configure per-table autovacuum settings + monitor dead tuple ratio,SELECT relname n_dead_tup n_tup_upd FROM pg_stat_user_tables,Monitor n_dead_tup decreases after vacuum,https://www.postgresql.org/docs/current/routine-vacuuming.html
Autovacuum,Autovacuum taking too long,Insufficient maintenance_work_mem,Increase maintenance_work_mem for sessions,Set higher maintenance_work_mem globally,Optimize vacuum cost delay + parallel vacuum for large indexes,SELECT * FROM pg_stat_progress_vacuum,Check blocks_vacuumed progress and completion,https://www.postgresql.org/docs/current/progress-reporting.html
Replication,Replication lag increasing,Primary generating WAL faster than standby can replay,Check network bandwidth and standby I/O,Tune wal_sender_timeout and recovery settings,Optimize standby hardware + parallel recovery + compression,SELECT * FROM pg_stat_replication,Monitor flush_lag and replay_lag metrics,https://www.postgresql.org/docs/current/monitoring-stats.html
Replication,Replication slot retention,Logical replication slot preventing WAL cleanup,Advance or drop unused replication slots,Monitor slot lag with pg_replication_slots,Implement automated slot management + monitoring alerts,SELECT slot_name restart_lsn FROM pg_replication_slots,Verify restart_lsn advances with commits,https://www.postgresql.org/docs/current/logicaldecoding-explanation.html
Partitioning,Partition pruning not working,Query not using partition key in WHERE clause,Add partition key to WHERE clause,Rewrite query to enable constraint exclusion,Redesign partitioning strategy to match query patterns,EXPLAIN SELECT * FROM partitioned_table WHERE date_col = ?,Check for constraint exclusion in plan,https://www.postgresql.org/docs/current/ddl-partitioning.html
Partitioning,Query scanning all partitions,Partition elimination disabled or ineffective,Enable enable_partition_pruning,Ensure WHERE clause uses partition key with appropriate operators,Create partition-wise joins + optimize partition key usage,SHOW enable_partition_pruning,Verify only relevant partitions in query plan,https://www.postgresql.org/docs/current/runtime-config-query.html
Locking,Deadlock errors,Concurrent transactions locking resources in different orders,Add explicit lock ordering in application,Use lower isolation levels where appropriate,Implement retry logic + optimize transaction scope + lock timeout,SELECT * FROM pg_locks WHERE NOT granted,Monitor for lock waits and blocking queries,https://www.postgresql.org/docs/current/explicit-locking.html
Locking,Lock wait timeouts,Long-running transactions holding locks,Identify and terminate blocking queries,Reduce transaction scope and duration,Implement connection pooling + query optimization + lock monitoring,SELECT blocked.pid blocked_by.query FROM pg_stat_activity blocked JOIN pg_locks ON blocked.pid = relation,Verify lock wait times decrease,https://www.postgresql.org/docs/current/monitoring-locks.html
Statistics,Query planner choosing poor plan,Outdated table statistics,Run ANALYZE on affected tables,Schedule regular ANALYZE or enable autovacuum,Implement automated statistics maintenance + custom statistics targets,ANALYZE table_name; EXPLAIN query,Check row estimates match actual in query plan,https://www.postgresql.org/docs/current/planner-stats.html
Statistics,Wrong cardinality estimates,Default statistics target too low,Increase default_statistics_target,Set per-column statistics targets with ALTER TABLE,Implement histogram analysis + correlation statistics + expression statistics,ALTER TABLE table_name ALTER COLUMN column_name SET STATISTICS 1000,Compare estimated vs actual rows in EXPLAIN ANALYZE,https://www.postgresql.org/docs/current/sql-altertable.html
Extension,pg_stat_statements not tracking queries,Extension not installed or configured,CREATE EXTENSION pg_stat_statements,Add pg_stat_statements to shared_preload_libraries,Configure statement tracking parameters + restart required,SELECT * FROM pg_stat_statements LIMIT 1,Verify queries appear in pg_stat_statements view,https://www.postgresql.org/docs/current/pgstatstatements.html
Extension,PostGIS queries are slow,Missing spatial indexes,CREATE INDEX USING GIST on geometry columns,Analyze spatial query patterns and create appropriate indexes,Implement spatial partitioning + optimize SRID + use spatial operators,EXPLAIN SELECT * FROM table WHERE ST_Intersects(geom ?),Verify GiST index usage in spatial queries,https://postgis.net/docs/using_postgis_dbmanagement.html
Backup,pg_dump taking too long,Large database with single-threaded dump,Use parallel dump with -j option,Exclude unnecessary data with --exclude-table-data,Implement incremental backup strategy + pg_basebackup for large datasets,pg_dump --verbose -j 4 -Fd -f backup_dir dbname,Monitor dump progress and completion time,https://www.postgresql.org/docs/current/app-pgdump.html
Backup,Point-in-time recovery failing,WAL files missing or corrupted,Check WAL archive completeness,Verify archive_command and restore_command settings,Implement WAL-E or pgBackRest + continuous WAL archiving + recovery testing,SELECT * FROM pg_stat_archiver,Verify archived WAL files and recovery timeline,https://www.postgresql.org/docs/current/continuous-archiving.html
Configuration,Checkpoint warnings in log,Checkpoints happening too frequently,Increase max_wal_size,Tune checkpoint_completion_target to 0.9,Optimize checkpoint timing + WAL settings + background writer,SELECT * FROM pg_stat_checkpointer,Monitor checkpoint timing and write rate,https://www.postgresql.org/docs/current/wal-configuration.html
Configuration,Out of memory errors,work_mem or maintenance_work_mem too small,Increase work_mem for sessions,Tune memory parameters based on workload,Implement memory monitoring + dynamic work_mem + connection pooling,SELECT * FROM pg_stat_activity WHERE state = 'active',Monitor memory usage and query completion,https://www.postgresql.org/docs/current/runtime-config-resource.html
Security,Authentication failures,pg_hba.conf misconfiguration,Check connection method and address matching,Verify user exists and has proper roles,Implement proper authentication method + SSL/TLS + connection logging,SELECT * FROM pg_stat_activity WHERE state = 'active',Verify successful connections in pg_log,https://www.postgresql.org/docs/current/auth-pg-hba-conf.html
Security,SSL connection errors,Certificate or SSL configuration issues,Check SSL certificate validity,Configure proper SSL mode and certificates,Implement full SSL/TLS setup + certificate management + connection encryption,SELECT * FROM pg_stat_ssl,Verify SSL connections are established,https://www.postgresql.org/docs/current/ssl-tcp.html
Monitoring,Missing performance metrics,Statistics collection disabled,Enable track_activities and track_counts,Install and configure pg_stat_statements,Implement comprehensive monitoring with pg_stat_monitor + custom metrics collection,SHOW track_activities; SHOW track_counts,Verify statistics views are populated,https://www.postgresql.org/docs/current/runtime-config-statistics.html
Monitoring,High WAL generation,Excessive write activity,Identify write-heavy queries,Optimize bulk operations and batch updates,Implement WAL compression + optimize checkpoint settings + monitor WAL usage,SELECT * FROM pg_stat_wal,Monitor WAL generation rate and size,https://www.postgresql.org/docs/current/monitoring-stats.html