pg_reports 0.5.4 → 0.6.1

data/config/locales/en.yml

@@ -11,6 +11,7 @@ en:
           - "High mean time can be caused by: missing index, suboptimal plan, locks, disk I/O load."
           - "For composite indexes, column order matters — index (a, b) is effective for WHERE a = ? and WHERE a = ? AND b = ?, but not for WHERE b = ?."
           - "Queries with LIKE '%pattern%' cannot use B-tree indexes — consider pg_trgm or full-text search."
+        ai_prompt: "Optimize these slow PostgreSQL queries. For each query: analyze the query plan, identify missing indexes, suggest query rewrites. If an index is needed, generate a Rails migration. If the query can be rewritten, show the optimized version."
 
       heavy_queries:
         title: "Heavy Queries"
@@ -21,6 +22,7 @@ en:
           - "N+1 problem: if you see many similar queries with different IDs — this is a sign of N+1, need eager loading."
           - "Consider batch operations instead of multiple single queries."
           - "Prepared statements can reduce parsing overhead for frequent queries."
+        ai_prompt: "Reduce the call frequency of these heavy PostgreSQL queries. For each query: identify the caller in application code, suggest caching strategies (Redis/Memcached), detect N+1 patterns and suggest eager loading fixes. Show code changes needed."
 
       expensive_queries:
         title: "Expensive Queries"
@@ -30,6 +32,7 @@ en:
           - "A query can be fast but called so often that it takes a lot of time in total."
           - "Optimizing expensive queries has the greatest effect on overall system performance."
           - "Consider: adding indexes, rewriting the query, caching results, materialized views."
+        ai_prompt: "Optimize these expensive PostgreSQL queries that consume the most total database time. For each query: analyze the execution plan, suggest indexes or query rewrites, estimate the expected improvement. Generate Rails migrations for any new indexes."
 
       missing_index_queries:
         title: "Missing Index Queries"
@@ -40,6 +43,7 @@ en:
           - "Composite index (a, b, c) covers: WHERE a, WHERE a AND b, WHERE a AND b AND c, but does NOT cover WHERE b or WHERE c."
           - "EXPLAIN ANALYZE will show the actual query execution plan."
           - "Partial indexes (CREATE INDEX ... WHERE condition) save space and speed up specific queries."
+        ai_prompt: "Add missing indexes for these PostgreSQL queries that perform sequential scans. For each table: analyze the query pattern, determine optimal index columns, generate a Rails migration with add_index. Consider partial indexes where appropriate."
 
       low_cache_hit_queries:
         title: "Low Cache Hit Queries"
@@ -50,6 +54,18 @@ en:
           - "Low cache hit may indicate: insufficient shared_buffers, tables too large, inefficient queries scanning too much data."
           - "Increasing shared_buffers helps, but there's a limit to effectiveness (typically 25% of RAM)."
           - "Covering indexes (INCLUDE) allow index-only scans without accessing the table."
+        ai_prompt: "Improve cache hit ratio for these PostgreSQL queries. For each query: suggest covering indexes (with INCLUDE columns) to enable index-only scans, or suggest query rewrites to reduce the data scanned. Generate Rails migrations for new indexes."
+
+      temp_file_queries:
+        title: "Temp File Queries"
+        what: "Queries that spill intermediate results to temporary files on disk."
+        how: "Analyzes temp_blks_written and temp_blks_read from pg_stat_statements. Temporary files are created when work_mem is insufficient for sorting, hashing, or materializing."
+        nuances:
+          - "Temp file writes are orders of magnitude slower than in-memory operations."
+          - "Increasing work_mem can eliminate temp files, but affects all sessions — use SET LOCAL for specific queries."
+          - "Common causes: large sorts (ORDER BY), hash joins on big tables, DISTINCT on many rows, complex CTEs."
+          - "Consider adding indexes to avoid sorts, or rewriting queries to reduce intermediate result sets."
+        ai_prompt: "Fix these PostgreSQL queries that spill to temporary files on disk. For each query: identify the cause (large sort, hash join, DISTINCT), suggest an index to avoid the sort, or suggest SET LOCAL work_mem for specific code paths. Show the code changes."
 
       all_queries:
         title: "All Queries"
@@ -70,6 +86,7 @@ en:
           - "Indexes are still updated on INSERT/UPDATE/DELETE, even if not used for reading — this is overhead."
           - "Unique indexes (UNIQUE) may have 0 scans but are needed for constraints."
           - "Foreign key indexes are important for DELETE/UPDATE performance on parent tables."
+        ai_prompt: "Remove these unused PostgreSQL indexes. For each index: generate a Rails migration with remove_index. Group related indexes into one migration. Add a safety comment noting the index can be recreated if needed."
 
       duplicate_indexes:
         title: "Duplicate Indexes"
@@ -79,6 +96,7 @@ en:
           - "Duplicates waste disk space and slow down INSERT/UPDATE/DELETE."
           - "However, sometimes a 'duplicate' is needed: different index types (B-tree vs GIN), partial vs full index."
           - "Index (a, b) does NOT fully replace (b, a) — column order is critical."
+        ai_prompt: "Remove these duplicate PostgreSQL indexes. For each pair: determine which index is redundant (the shorter prefix), generate a Rails migration with remove_index for the redundant one. Verify the remaining index covers all use cases."
 
       invalid_indexes:
         title: "Invalid Indexes"
@@ -88,6 +106,7 @@ en:
           - "Usually appear after a failed CREATE INDEX CONCURRENTLY."
           - "Solution: DROP INDEX and recreate."
           - "REINDEX CONCURRENTLY can help for existing invalid indexes (PostgreSQL 12+)."
+        ai_prompt: "Fix these invalid PostgreSQL indexes. For each index: generate a Rails migration that drops the invalid index and recreates it using `algorithm: :concurrently` to avoid locking the table."
 
       missing_indexes:
         title: "Missing Indexes"
@@ -97,6 +116,7 @@ en:
           - "Not all seq_scans are bad — for small tables it's optimal."
           - "Analyze specific queries via pg_stat_statements to understand which columns to index."
           - "Use EXPLAIN ANALYZE to verify if an index will be used."
+        ai_prompt: "Add missing indexes for these PostgreSQL tables with high sequential scan counts. For each table: analyze the common query patterns, determine optimal index columns, generate a Rails migration with add_index using `algorithm: :concurrently`."
 
       index_usage:
         title: "Index Usage"
@@ -107,6 +127,18 @@ en:
           - "idx_tup_read — rows read from the index."
           - "idx_tup_fetch — rows fetched from table after index scan (for non-covering indexes)."
 
+      inefficient_indexes:
+        title: "Inefficient Indexes"
+        what: "Indexes that are used but scan far more entries than they actually fetch."
+        how: "Compares idx_tup_read (index entries scanned) vs idx_tup_fetch (heap rows fetched) from pg_stat_user_indexes. A high ratio means the index column order doesn't match query predicates, forcing PostgreSQL to scan large index ranges."
+        nuances:
+          - "A read-to-fetch ratio >10 means the index reads 10x more entries than it returns — strong sign of misaligned column order."
+          - "For composite indexes (a, b, c), queries filtering on (b) or (c) without (a) cannot seek directly and must scan wider ranges."
+          - "Solution: create a targeted index with columns matching the most selective WHERE predicates first."
+          - "Use EXPLAIN ANALYZE to confirm the index scan is reading excessive entries before making changes."
+          - "Index-only scans (where idx_tup_fetch = 0) are excluded — they indicate covering indexes working efficiently."
+        ai_prompt: "Fix these inefficient PostgreSQL index scans. For each index: analyze the index definition and identify the misaligned column order, create a new targeted index with columns matching the most selective WHERE predicates first, generate a Rails migration that adds the new index and removes the old one."
+
       bloated_indexes:
         title: "Bloated Indexes"
         what: "Indexes with high bloat level due to dead tuples."
@@ -116,6 +148,30 @@ en:
           - "Regular VACUUM keeps bloat at acceptable levels."
           - "pg_repack allows rebuilding indexes without locks."
           - "Bloat >30-50% — reason for action."
+        ai_prompt: "Rebuild these bloated PostgreSQL indexes. Generate a rake task or Rails migration that runs REINDEX CONCURRENTLY for each bloated index to reclaim disk space without locking the table."
+
+      fk_without_indexes:
+        title: "FK Without Indexes"
+        what: "Foreign keys on child tables that lack a supporting index."
+        how: "Compares pg_constraint (foreign keys) with pg_index to find FK columns without a matching leading index column."
+        nuances:
+          - "Without an index, DELETE or UPDATE on the parent table triggers a sequential scan on the child table."
+          - "On large child tables this can cause severe lock contention and slow cascading operations."
+          - "The index must have the FK column as the leading (first) column to be effective."
+          - "Small tables (< 10K rows) may not benefit from adding an index — PostgreSQL will prefer seq scan anyway."
+        ai_prompt: "Add missing indexes on foreign key columns in these PostgreSQL tables. For each FK: generate a Rails migration with add_index on the child table's FK column. Use `algorithm: :concurrently` for large tables."
+
+      index_correlation:
+        title: "Index Correlation"
+        what: "Indexes where physical row order poorly matches the index order."
+        how: "Reads pg_stats.correlation for leading index columns. Correlation near 0 means random physical order relative to the index, causing excessive random I/O on range scans."
+        nuances:
+          - "Correlation ranges from -1 to 1. Values near 0 mean random order; near 1 or -1 mean ordered."
+          - "Low correlation mainly impacts range scans (BETWEEN, >, <) and ORDER BY — point lookups are less affected."
+          - "CLUSTER table USING index physically reorders rows but locks the table and is not maintained automatically."
+          - "For append-only tables with timestamp columns, correlation is naturally high — no action needed."
+          - "Only tables > 10MB with > 100 index scans are shown to reduce noise."
+        ai_prompt: "Address low physical correlation for these PostgreSQL indexes. For each: evaluate if CLUSTER is appropriate (for read-heavy tables), or suggest switching to BRIN index for range-scanned timestamp columns. If CLUSTER is chosen, generate a rake task since it locks the table and should be run during maintenance."
 
       index_sizes:
         title: "Index Sizes"
@@ -145,6 +201,7 @@ en:
           - "VACUUM FULL physically reduces file size, but locks the table."
           - "autovacuum should handle this automatically — check its settings if you see high bloat."
           - "Dead tuple ratio >20% — signal of vacuum problems."
+        ai_prompt: "Fix bloat on these PostgreSQL tables with high dead tuple percentage. Generate a rake task that runs VACUUM ANALYZE on each table. For severely bloated tables, suggest VACUUM FULL during maintenance window. Also review autovacuum settings."
 
       vacuum_needed:
         title: "Vacuum Needed"
@@ -154,6 +211,7 @@ en:
           - "last_vacuum and last_autovacuum show when vacuum last ran."
           - "If autovacuum can't keep up, you can: lower autovacuum_vacuum_threshold, increase autovacuum_vacuum_scale_factor, add workers."
           - "For critical tables, you can set individual parameters: ALTER TABLE SET (autovacuum_vacuum_threshold = 1000)."
+        ai_prompt: "Fix vacuum issues on these PostgreSQL tables. Generate a rake task that runs VACUUM ANALYZE on each table. For tables with extreme dead rows, suggest tuning per-table autovacuum parameters via a Rails migration using execute."
 
       row_counts:
         title: "Row Counts"
@@ -172,6 +230,7 @@ en:
           - "Target value: >95% for actively used tables."
           - "Low cache hit: table too large for cache or rarely used."
           - "Solutions: increase shared_buffers, optimize queries, add indexes to reduce scanned data."
+        ai_prompt: "Improve cache hit ratios for these PostgreSQL tables. Suggest specific shared_buffers tuning, recommend indexes to reduce data scanned, and identify queries hitting these tables that could benefit from optimization."
 
       seq_scans:
         title: "Sequential Scans"
@@ -182,6 +241,18 @@ en:
           - "seq_tup_read shows how many rows were read — this is more important than scan count."
           - "High seq_tup_read/seq_scan = many rows per scan = probably normal."
           - "Low seq_tup_read/seq_scan = many small scans = possibly N+1."
+        ai_prompt: "Add indexes for these PostgreSQL tables with high sequential scan counts. For each table: identify the queries causing sequential scans, determine optimal index columns, generate a Rails migration with add_index."
+
+      tables_without_pk:
+        title: "Tables Without Primary Keys"
+        what: "Tables that have no primary key defined."
+        how: "Checks pg_index for missing indisprimary entries on user tables."
+        nuances:
+          - "Logical replication requires a primary key or REPLICA IDENTITY to identify rows."
+          - "Without a PK, UPDATE and DELETE need another way to uniquely identify rows, often resulting in full table scans."
+          - "Join tables (many-to-many) often lack PKs intentionally — consider adding a composite PK."
+          - "Some ORMs (e.g., Rails) assume an 'id' primary key — tables without it may cause framework errors."
+        ai_prompt: "Add primary keys to these PostgreSQL tables. For each table: determine the appropriate primary key (auto-increment id or composite key for join tables), generate a Rails migration that adds the primary key."
 
       recently_modified:
         title: "Recently Modified"
@@ -192,6 +263,31 @@ en:
           - "High UPDATE activity creates dead tuples — monitor vacuum."
           - "HOT updates (Heap Only Tuple) are more efficient — indexes are not updated."
 
+      update_hotspots:
+        title: "Update Hotspots"
+        what: "Tables where the same rows are updated repeatedly, or where indexed columns are being hot-updated."
+        how: "Computes two ratios from pg_stat_user_tables: updates_per_row = n_tup_upd / n_live_tup (signal for write amplification on individual rows) and hot_update_pct = n_tup_hot_upd / n_tup_upd (low value means an indexed column is in the SET clause, defeating HOT)."
+        nuances:
+          - "updates_per_row >> 1 means individual rows are being rewritten many times — common with counters, status flags, last_seen_at, position trackers."
+          - "Refactor patterns for hot rows: move the volatile column to a sibling 1:1 'state' table; use an event/log table with periodic rollups; batch writes via a background buffer; debounce updates application-side."
+          - "Low hot_update_pct (e.g. <50%) means indexed columns are being updated. Either drop the index or move that column to a less-indexed table."
+          - "PostgreSQL does not track per-column UPDATE counts. To find which column is the culprit, parse pg_stat_statements for UPDATE queries on the table and look at SET clauses (queries are normalized but column names are preserved)."
+          - "Hot rows + low fillfactor (default 100) eliminates HOT optimization. ALTER TABLE ... SET (fillfactor=80) leaves room for in-place updates."
+          - "High n_dead_tup correlates with hot rows — autovacuum must keep up or bloat will grow fast."
+        ai_prompt: "Reduce write amplification on these PostgreSQL tables. For each: identify the columns most commonly updated by parsing pg_stat_statements UPDATE queries, propose a refactor (split hot/cold columns into a sibling table, switch to an append-only event table, batch writes), and generate the migration. If hot_update_pct is low, identify the indexed column being updated and recommend either dropping the index or moving the column."
+
+      unused_tables:
+        title: "Unused Tables"
+        what: "Tables with zero seq_scan and zero idx_scan since the last statistics reset — application code never reads them."
+        how: "Filters pg_stat_user_tables for seq_scan = 0 AND idx_scan = 0. Cross-references db_stats_since (pg_stat_database.stats_reset) so you know how much history the verdict is based on."
+        nuances:
+          - "Verify db_stats_since covers a representative window — at minimum a full week, ideally a full reporting/billing cycle. A recent stats_reset, restart, or PG upgrade invalidates the result."
+          - "Tables read only by replicas are NOT counted on the primary. Check replicas separately before dropping."
+          - "Tables touched only by COPY, pg_dump, or logical replication slots may still appear unused — these don't increment scan counters."
+          - "Foreign keys referencing the table can keep it 'in use' through cascades even without direct queries."
+          - "Safe sequence: rename → wait one full cycle → drop. Or move to a separate archive schema first."
+        ai_prompt: "Archive these unread PostgreSQL tables. For each: verify the table is not referenced by FKs, code, or scheduled jobs, then generate a Rails migration that either drops the table or moves it to an `archive` schema. Add a rollback that restores the table. Recommend resetting pg_stat_user_tables before final removal to confirm zero reads over a fresh window."
+
       # === CONNECTIONS ===
       active_connections:
         title: "Active Connections"
@@ -220,6 +316,7 @@ en:
           - "Long queries can hold locks and interfere with other processes."
           - "statement_timeout can automatically terminate queries running too long."
           - "For reports/analytics, use a read replica or configure a separate connection pool."
+        ai_prompt: "Investigate and optimize these long-running PostgreSQL queries. For each query: analyze the execution plan, suggest indexes or query rewrites, recommend statement_timeout configuration. If the query is analytical, suggest moving it to a read replica."
 
       blocking_queries:
         title: "Blocking Queries"
@@ -230,6 +327,7 @@ en:
           - "Common causes: long transactions, missing indexes on UPDATE/DELETE with FK."
           - "pg_cancel_backend(pid) cancels query, pg_terminate_backend(pid) terminates connection."
           - "Consider optimistic locking at the application level."
+        ai_prompt: "Resolve these blocking query chains in PostgreSQL. Identify the root blocker, suggest application-level fixes (shorter transactions, optimistic locking, advisory locks), and recommend indexes on FK columns to speed up cascading operations."
 
       locks:
         title: "Locks"
@@ -248,6 +346,7 @@ en:
           - "A moderate number of idle connections is normal for connection pooling."
           - "Too many idle = application not closing connections or pool is too large."
           - "idle_session_timeout (PostgreSQL 14+) can automatically close idle connections."
+        ai_prompt: "Reduce idle PostgreSQL connections. Suggest database.yml pool size tuning, recommend idle_session_timeout or PgBouncer configuration, and identify application code that may be leaking connections."
 
       pool_usage:
         title: "Connection Pool Usage"
@@ -278,6 +377,7 @@ en:
           - "High idle in transaction count = application transaction handling issues."
           - "superuser_reserved_connections reduce available pool capacity."
           - "Monitor trends — sudden spikes may indicate connection leaks."
+        ai_prompt: "Fix connection pool saturation in PostgreSQL. Suggest specific max_connections and pool size tuning for database.yml, recommend PgBouncer setup if not present, and identify application patterns causing pool exhaustion."
 
       connection_churn:
         title: "Connection Churn Analysis"
@@ -288,6 +388,7 @@ en:
           - "Churn rate over 50% = missing/misconfigured connection pooling."
           - "Many short connections = increased CPU and authentication overhead."
           - "Web apps should maintain connection pools, not create per-request connections."
+        ai_prompt: "Fix excessive connection churn in PostgreSQL. Configure PgBouncer or Rails connection pooling properly, identify application code creating short-lived connections, suggest database.yml pool and checkout_timeout tuning."
 
       # === SYSTEM ===
       database_sizes:
@@ -326,6 +427,30 @@ en:
           - "Useful for quick assessment of database state."
           - "Compare with baseline to identify anomalies."
 
+      wraparound_risk:
+        title: "Wraparound Risk"
+        what: "Transaction ID age proximity to the 2-billion wraparound limit."
+        how: "Reads age(datfrozenxid) from pg_database. When this approaches 2^31 (~2.1 billion), PostgreSQL will shut down to prevent data corruption."
+        nuances:
+          - "autovacuum_freeze_max_age (default 200M) triggers aggressive anti-wraparound VACUUM automatically."
+          - "If age exceeds freeze_max_age, anti-wraparound VACUUM should already be running — if not, investigate why."
+          - "Long-running transactions prevent VACUUM from advancing the frozen XID — monitor idle-in-transaction."
+          - "In emergencies, run VACUUM FREEZE on the largest/oldest tables first."
+          - "Pct > 50% is a warning; > 75% is critical and requires immediate action."
+        ai_prompt: "Address transaction ID wraparound risk on these PostgreSQL databases. Generate a rake task that runs VACUUM FREEZE on the affected databases, prioritizing by pct_towards_wraparound. Include monitoring checks to verify the XID age decreased after the operation."
+
+      checkpoint_stats:
+        title: "Checkpoint Stats"
+        what: "Checkpoint frequency and background writer performance metrics."
+        how: "Data from pg_stat_bgwriter shows checkpoint counts, timing, and buffer write distribution."
+        nuances:
+          - "checkpoints_timed = scheduled checkpoints (healthy); checkpoints_req = forced checkpoints (under pressure)."
+          - "High requested_pct means WAL fills up before checkpoint_timeout — increase max_wal_size."
+          - "buffers_backend > 0 means backends write dirty buffers themselves — increase shared_buffers or bgwriter activity."
+          - "bgwriter_stops (maxwritten_clean) > 0 means bgwriter hit its per-round limit — increase bgwriter_lru_maxpages."
+          - "Stats accumulate since stats_reset — compare over time for meaningful analysis."
+        ai_prompt: "Optimize PostgreSQL checkpoint and background writer configuration based on these stats. Suggest specific postgresql.conf parameter changes (max_wal_size, checkpoint_completion_target, bgwriter_lru_maxpages) with recommended values and explain the expected impact."
+
       cache_stats:
         title: "Cache Stats"
         what: "Database caching statistics."
@@ -334,8 +459,82 @@ en:
           - "Cache hit ratio = blks_hit / (blks_hit + blks_read)."
           - "Target value: >99% for OLTP, >95% for mixed workload."
           - "Low cache hit: increase shared_buffers (up to 25% RAM), or the problem is in queries."
+        ai_prompt: "Improve PostgreSQL cache hit ratio. Suggest specific shared_buffers and effective_cache_size tuning for postgresql.conf based on the current stats. Recommend application-level caching for frequently accessed data."
 
       # === SCHEMA ANALYSIS ===
+      unused_columns:
+        title: "Unused Columns"
+        what: "Columns whose data has only ever held a single distinct value — strong sign nothing in the application updates them anymore."
+        how: "Reads pg_stats.n_distinct = 1 (only one value across all sampled rows) and joins with pg_attrdef to show the column default. Excludes primary keys and unique-index columns to avoid noise."
+        nuances:
+          - "n_distinct is a sample-based estimate — ANALYZE the table before trusting the result. Stale stats can produce false positives."
+          - "Tables under ~1000 rows are excluded because a single value across few rows is statistically meaningless."
+          - "False positives: feature flags, enum columns where only one value has shipped so far, columns defaulted in code with one valid option."
+          - "True positives: columns whose Ruby/ORM accessor was deleted but the migration to drop the column was never written; status fields replaced by a different mechanism but left in the schema."
+          - "PostgreSQL has no per-column write tracking, so this is a heuristic. Confirm by grepping the codebase for the column name before dropping."
+          - "Consider also `always_null_columns` — same diagnosis from a different angle."
+        ai_prompt: "Drop these unused PostgreSQL columns. For each column: search the application code for any reference to the column name (Ruby, SQL, fixtures, views), and only if zero references found generate a Rails migration that removes the column with a `safety_assured` block. Include the column type and default in the rollback."
+
+      always_null_columns:
+        title: "Always-NULL Columns"
+        what: "Nullable columns where 100% of rows are NULL — the application has stopped (or never started) writing them."
+        how: "Reads pg_stats.null_frac >= 0.999 (effectively all NULL) and excludes columns with a NOT NULL constraint. Joins pg_attrdef to surface any leftover column default."
+        nuances:
+          - "null_frac is sampled — run ANALYZE first if you doubt the value. Re-check after a representative workload window."
+          - "A column may be NULL because the writing code path is rarely hit (e.g. premium-only fields, opt-in features). Check before dropping."
+          - "If null_pct = 100 AND there is a non-NULL default, the default is unused — also worth removing alongside the column."
+          - "Some ORMs serialize empty strings as '' rather than NULL; this report won't catch always-empty columns. Add a separate report or query if you need that signal."
+          - "Compare with `unused_columns` — that report catches single-value columns; this one catches all-NULL columns. Together they cover the most common dead-column patterns."
+        ai_prompt: "Drop these always-NULL PostgreSQL columns. For each: confirm via codebase search that no writer references the column, then generate a Rails migration removing the column. If the rollback should restore data, note that there is none — the column was empty."
+
+      polymorphic_without_index:
+        title: "Polymorphic Without Index"
+        what: "Polymorphic `belongs_to` associations whose `(*_type, *_id)` pair has no composite index."
+        how: "Walks `ActiveRecord::Base.descendants`, collects `belongs_to` reflections with `polymorphic: true`, and checks `pg_index` for an index covering both the type and id columns."
+        nuances:
+          - "PostgreSQL cannot use two single-column indexes as efficiently as one composite index for `WHERE x_type = ? AND x_id = ?` lookups — this is the canonical fetch pattern for polymorphic associations."
+          - "Coverage hint clarifies the gap: \"neither indexed\" / \"only id indexed\" / \"only type indexed\" / \"type and id indexed separately\". The last two are partial fixes, not full ones."
+          - "On small association tables this is harmless; on large ones (Comment, Note, Activity, AuditLog) it turns every association load into a seq scan."
+          - "The suggested migration uses the `(type, id)` order — type usually has lower cardinality so the index tree narrows faster."
+          - "Eager-loads the application before walking models so dev environments produce a complete result."
+        ai_prompt: "Add composite indexes for these polymorphic associations. For each: generate a Rails migration with `add_index :<table>, [:<x>_type, :<x>_id]` using `algorithm: :concurrently` for large tables. Verify the existing single-column indexes (if any) can be dropped after the composite is in place."
+
+      counter_cache_issues:
+        title: "Counter Cache Issues"
+        what: "`belongs_to ..., counter_cache: ...` declarations whose target column is missing on the parent table."
+        how: "Walks all models, finds `belongs_to` with a `counter_cache` option, resolves the expected column name (`<child_table>_count` for `counter_cache: true`, or the explicit symbol/string), and checks the parent's columns."
+        nuances:
+          - "Missing column = the counter is silently broken: writes go nowhere, `parent.<assoc>_count` returns nil, and any code reading the cached value gets stale or zero."
+          - "Reverse direction (a `*_count` column with no `counter_cache` declaration pointing at it) is intentionally not flagged — too many false positives from manually maintained counters."
+          - "Resolves the parent class via `assoc.klass`; if the class is missing or fails to load, the row is skipped."
+          - "Default name for `counter_cache: true`: parent gets a column named after the **child** table pluralized + `_count`. Example: `Comment belongs_to :user, counter_cache: true` → `users.comments_count`."
+          - "Eager-loads the application before walking models so dev environments produce a complete result."
+        ai_prompt: "Fix these broken counter caches. For each row: generate a Rails migration that adds the missing column with `default: 0, null: false`, then a backfill task that runs `Parent.find_each { |p| Parent.reset_counters(p.id, :<assoc>) }`. Run the backfill before deploying any code that reads the counter."
+
+      soft_delete_without_scope:
+        title: "Soft Delete Without Scope"
+        what: "Tables with a `deleted_at` / `discarded_at` / `archived_at` column whose model has no scope filtering soft-deleted rows."
+        how: "For each table, checks if any of the canonical soft-delete column names exist. If so, finds the model and checks for `acts_as_paranoid` (paranoia gem), `discard_column` (discard gem), or a `default_scope` whose generated SQL references the column."
+        nuances:
+          - "Without a default scope, every plain `Model.where(...)` query returns soft-deleted rows. This silently leaks 'deleted' data into reports, indexes, search results, and exports."
+          - "If the team has decided **against** a default scope (because they prefer explicit `kept`/`with_deleted` calls everywhere), this report will produce one row per such model — those are intentional and can be ignored."
+          - "Detection method for default_scope: builds `model.all.to_sql` and looks for the column name. Catches `default_scope { where(deleted_at: nil) }` and equivalents but misses scopes added at runtime via concerns that aren't loaded yet."
+          - "Tables without a Rails model are reported separately with status `no_model` — usually means the table is queried only by raw SQL and needs manual review."
+          - "Eager-loads the application before walking models so dev environments produce a complete result."
+        ai_prompt: "Add soft-delete scopes to these Rails models. For each: add `default_scope { where(<column>: nil) }` and a `with_deleted` unscoped helper, OR adopt the `discard` gem (`include Discard::Model; self.discard_column = :<column>`). Verify no production code path expects to see soft-deleted rows by default."
+
+      orphan_tables:
+        title: "Orphan Tables"
+        what: "Database tables with no corresponding Rails model class."
+        how: "Lists all tables from `pg_class` (excluding `schema_migrations` and `ar_internal_metadata`) and tries common naming conventions to find a model. Tables that resolve to nothing are reported."
+        nuances:
+          - "Three classifications: `join_table_candidate` (exactly two `*_id` columns and nothing else — likely a legitimate HABTM table), `join_model_without_class` (multiple FK columns plus extra fields — was probably meant to be a join model), and `legacy` (everything else)."
+          - "`join_table_candidate` is usually intentional — Rails doesn't require a model for HABTM. Skim and ignore."
+          - "`legacy` rows are the interesting ones: tables created before the Rails model was added, renamed-but-not-dropped, created out-of-band by another service, or owned by a removed feature."
+          - "Cross-reference with `unused_tables` (Tables category) — a table that's both orphan AND has zero reads is a strong drop candidate."
+          - "False positives: namespaced models (`Admin::User` → `admin_users`), STI subclasses sharing a base table, models declared inside engines that aren't eager-loaded."
+          - "Row count is approximate (n_live_tup from pg_stat_user_tables) — newly written tables may show 0 until the next ANALYZE."
+
       missing_validations:
         title: "Missing Validations"
         what: "Unique indexes in the database without corresponding uniqueness validations in Rails models."
@@ -347,6 +546,7 @@ en:
           - "Some tables may not have models — this is normal for join tables or legacy tables."
           - "Validations in concerns and parent models are also detected."
           - "Primary keys don't need validations — they are automatically unique."
+        ai_prompt: "Add missing uniqueness validations to these Rails models. For each unique index: add `validates :column, uniqueness: true` (or with `scope:` for composite indexes) to the corresponding model. Handle STI and concern-based models correctly."
 
     # Problem explanations for highlighting
     problems:
@@ -356,6 +556,13 @@ en:
       low_cache_hit: "Low cache hit ratio. Query frequently reads from disk instead of cache."
       high_seq_scan: "Many sequential scans. Possibly missing an index."
       unused_index: "Index is not used. Candidate for removal."
+      inefficient_index: "Index reads far more entries than it fetches. Composite index column order likely misaligned with query predicates."
+      fk_without_index: "Foreign key column has no supporting index. DELETE/UPDATE on parent table will cause sequential scan."
+      low_correlation: "Low physical correlation between index and row order. Range scans will cause excessive random I/O."
+      temp_file_heavy: "Query spills data to temporary files on disk. Consider increasing work_mem or optimizing the query."
+      missing_pk: "Table has no primary key. This breaks logical replication and may cause issues with ORMs."
+      wraparound_risk: "Transaction ID age is approaching the wraparound limit. VACUUM FREEZE required."
+      high_checkpoint_req: "High percentage of forced checkpoints. Consider increasing max_wal_size."
       high_bloat: "High bloat. REINDEX or VACUUM required."
       many_dead_tuples: "Many dead tuples. VACUUM required."
       long_running: "Long-running query. May block other operations."
@@ -366,3 +573,393 @@ en:
       pool_saturation: "Connection pool is saturated. Risk of connection exhaustion and application errors."
       high_connection_churn: "High connection churn rate. Implement connection pooling to reduce overhead."
       too_many_short_connections: "Too many short-lived connections. Application should reuse connections via pooling."
+      unused_column: "Column has only one distinct value across all rows. Likely never updated since creation — candidate for removal."
+      always_null_column: "Column is 100% NULL. Application no longer writes to this field — candidate for removal."
+      hot_rows: "Same rows are updated repeatedly. Consider splitting hot/cold columns, batching writes, or using an event-log table."
+      low_hot_update: "HOT update rate is low — indexed columns are being updated. Drop the index or move the column to reduce write amplification."
+      unused_table: "Table has zero reads since the last stats reset. Candidate for archival or removal — verify the stats window first."
+      polymorphic_no_index: "Polymorphic association lacks a composite (type, id) index. Lookups will seq-scan as the table grows."
+      counter_cache_missing_column: "Counter cache column is missing on the parent table. The counter is silently broken — writes go nowhere."
+      soft_delete_unprotected: "Soft-delete column has no model scope filtering it. Plain queries return deleted rows."
+      orphan_table_legacy: "Table has no Rails model. Likely legacy — verify before dropping."
+
+    # UI strings shown in the dashboard chrome (buttons, modals, toasts, etc.)
+    ui:
+      branding:
+        title: "PgReports"
+        subtitle: "PostgreSQL Analysis Dashboard"
+        page_title: "PgReports Dashboard"
+      navigation:
+        dashboard: "Dashboard"
+        back: "← Back"
+      actions:
+        cancel: "Cancel"
+        retry: "Retry"
+        copy: "📋 Copy"
+        copy_query: "📋 Copy Query"
+        copy_code: "📋 Copy Code"
+        copy_to_clipboard_title: "Copy to clipboard"
+        copied_feedback: "✓ Copied!"
+        clear_all: "Clear All"
+        run_report: "▶ Run Report"
+        export: "⬇ Export"
+        download_text: "📄 Text (.txt)"
+        download_csv: "📊 CSV (.csv)"
+        download_json: "📋 JSON (.json)"
+        download: "📥 Download"
+        copy_ai_prompt: "Copy Prompt"
+        send_telegram: "📨 Telegram"
+        sending: "Sending..."
+        reset_statistics: "🗑️ Reset Statistics"
+        resetting: "Resetting..."
+        confirm_reset: "Yes, Reset"
+        create_extension: "⚡ Create Extension"
+        creating: "Creating..."
+        ide_settings_button_title: "IDE Settings"
+        explain_analyze: "📊 EXPLAIN ANALYZE"
+        execute_query: "▶ Execute Query"
+        create_migration_file: "📁 Create File & Open in IDE"
+        start_monitoring: "▶ Start Monitoring"
+        stop_monitoring: "⏹ Stop Monitoring"
+        starting: "Starting..."
+        stopping: "Stopping..."
+        load_history: "📜 Load History (50)"
+        loading: "Loading..."
+        running: "Running..."
+        save_for_comparison: "📌 Save for Comparison"
+        saved_marker: "📌 Saved"
+      status:
+        pg_stat_ready: "pg_stat_statements ready"
+        extension_installed: "Extension installed, not preloaded"
+        preloaded: "Preloaded, extension not created"
+        not_configured: "Not configured"
+        monitoring_unavailable: "Live Monitoring Unavailable"
+      modals:
+        enable_pg_stat_title: "Enable pg_stat_statements"
+        enable_pg_stat_intro: "To enable pg_stat_statements, follow these steps:"
+        edit_postgresql_conf: "Edit postgresql.conf:"
+        restart_postgresql: "Restart PostgreSQL:"
+        create_extension_step: "Create extension:"
+        enable_button_note: "Or click \"Enable\" button after restart."
+        reset_stats_title: "⚠️ Reset Statistics"
+        reset_stats_confirm: "Are you sure you want to reset pg_stat_statements statistics?"
+        reset_stats_warning: "This action will clear all collected query statistics and cannot be undone."
+        ide_settings_title: "⚙️ IDE Settings"
+        problem_detected_title: "⚠️ Problem Detected"
+        query_analyzer_title: "📊 Query Analyzer"
+        query_label: "Query:"
+        parameters_label: "Parameters:"
+        migration_title: "🗑️ Drop Index Migration"
+        migration_subtitle: "Generated migration to remove the index:"
+        migration_warning: "Creating a migration will generate a migration file in your project. Running this migration will drop the index from the database, which may significantly impact application performance."
+        migration_warning_dev_only: "This operation should only be performed in a local development environment."
+        query_execution_disabled_title: "⚠️ Query execution is disabled"
+        query_execution_disabled_intro: "To enable this feature, add to your configuration:"
+      settings:
+        default_ide_label: "Default IDE for source links:"
+        ide_show_menu: "Show menu (default)"
+        ide_vscode_wsl: "VS Code (WSL)"
+        ide_vscode: "VS Code"
+        ide_rubymine: "RubyMine"
+        ide_intellij: "IntelliJ IDEA"
+        ide_cursor_wsl: "Cursor (WSL)"
+        ide_cursor: "Cursor"
+      monitoring:
+        live_title: "Live Monitoring"
+        update_interval: "Updates every 5s"
+        toggle_title: "Toggle live monitoring"
+        query_monitor_title: "SQL Query Monitor"
+        session_label: "Session:"
+        queries_label: "Queries:"
+        feed_empty: "Click \"Start Monitoring\" to begin capturing SQL queries"
+        feed_no_queries: "No queries captured yet..."
+        unknown_source: "Unknown source"
+        expand_collapse_title: "Expand/Collapse"
+      metrics:
+        connections_label: "Connections"
+        tps_label: "TPS"
+        tps_unit: "tx/s"
+        commit_label: "commit:"
+        rollback_label: "rollback:"
+        cache_hit_label: "Cache Hit"
+        cache_hit_detail: "heap blocks from cache"
+        long_queries_label: "Long Queries"
+        queries_unit: "queries"
+        long_running_threshold: "> 60s runtime"
+        blocked_label: "Blocked"
+        processes_unit: "processes"
+        waiting_for_locks: "waiting for locks"
+        percent_used_suffix: "% used"
+      categories:
+        requires_pg_stat: "🔒 Requires pg_stat_statements"
+        reports_count_suffix: "reports"
+      documentation:
+        toggle_title: "📖 What does this report show?"
+        what_section: "📋 What"
+        why_section: "❓ Why It Matters"
+        nuances_section: "⚠️ Nuances"
+        thresholds_section: "📊 Thresholds"
+        threshold_warning_label: "⚠️ Warning:"
+        threshold_critical_label: "🔴 Critical:"
+        threshold_inverted_note: "(lower is worse)"
+      filters:
+        title: "🔍 Filter Parameters"
+        current_value: "current"
+      saved:
+        title: "📌 Saved for Comparison"
+        saved_at_prefix: "▸ Saved:"
+        click_to_expand: "Click to expand"
+        confirm_clear_all: "Remove all saved records for this report?"
+        remove_title: "Remove"
+      results:
+        title: "Results"
+        click_run_hint: "Click \"Run Report\" to fetch data"
+        empty_message: "No issues found. Everything looks good!"
+        showing_first_of_total: "Showing first %{count} of %{total} rows"
+        no_rows_returned: "No rows returned"
+        rows_label: "Rows:"
+        execution_time_label: "Execution time:"
+        null_placeholder: "<null>"
+      sections:
+        recommendation: "💡 Recommendation"
+        detected_issues: "⚠️ Detected Issues"
+        execution_plan: "📊 Execution Plan"
+        line_label: "Line"
+        current_label: "Current:"
+        threshold_label: "Threshold:"
+        threshold_inverted_long: "(inverted: lower values are worse)"
+        warning_eq: "warning"
+        critical_eq: "critical"
+      levels:
+        critical: "🔴 Critical"
+        warning: "⚠️ Warning"
+      errors:
+        error_prefix: "Error:"
+        unable_fetch_metrics: "Unable to fetch database statistics."
+        possible_causes: "This may be due to:"
+        cause_permissions: "Insufficient database permissions"
+        cause_views: "Database statistics views not accessible"
+        cause_connection: "Connection issues"
+        fetch_metrics_failed: "Failed to fetch live metrics"
+        fetch_metrics_check_perms: "Unable to fetch database statistics. Check database permissions."
+        insufficient_database_perms: "Insufficient database permissions to access statistics views"
+        network_error_prefix: "Network error:"
+        copy_failed: "Failed to copy"
+        run_report_first: "Run the report first"
+        run_report_failed: "Failed to run report"
+        report_not_found: "Report not found"
+        send_telegram_failed: "Failed to send to Telegram"
+        reset_stats_failed: "Failed to reset statistics"
+        start_monitoring_failed: "Failed to start monitoring"
+        stop_monitoring_failed: "Failed to stop monitoring"
+        load_history_failed: "Failed to load history:"
+        no_query_history: "No query history found"
+        decode_query_failed: "Failed to decode query"
+        explain_analyze_failed: "Failed to run EXPLAIN ANALYZE"
+        execute_query_failed: "Failed to execute query"
+        create_migration_failed: "Failed to create migration"
+        explain_disabled_toast: "⚠️ EXPLAIN ANALYZE is disabled. Enable in configuration: config.allow_raw_query_execution = true"
+        execute_disabled_toast: "⚠️ Query execution is disabled. Enable in configuration: config.allow_raw_query_execution = true"
+        query_monitoring_error: "Query monitoring error"
+        query_hash_required: "Query hash is required"
+        query_execution_disabled: "Query execution from dashboard is disabled. Enable it in configuration with 'config.allow_raw_query_execution = true'"
+        query_not_found_expired: "Query not found or expired. Please refresh the page."
+        security_violation_prefix: "Security violation:"
+        trigger_variables_not_allowed: "Cannot EXPLAIN ANALYZE queries with trigger variables (NEW, OLD). These are only available within trigger functions."
+        missing_parameter_values: "Please provide values for all parameter placeholders ($1, $2, etc.)"
+        migration_dev_only: "Migration creation is only allowed in development environment"
+        filename_code_required: "File name and code are required"
+        invalid_filename_format: "Invalid migration file name format"
+        migrations_dir_not_found: "Migrations directory not found"
+      success:
+        statistics_reset: "Statistics have been reset successfully"
+        report_generated: "Report generated successfully"
+        ai_prompt_copied: "AI prompt copied to clipboard"
+        explain_copied: "EXPLAIN output copied to clipboard"
+        migration_copied: "Migration code copied to clipboard"
+        migration_created: "Migration created successfully"
+        telegram_sent: "Report sent to Telegram"
+        queries_loaded: "Loaded %{count} queries from history"
+        record_saved: "Record saved for comparison"
+        record_removed: "Record removed"
+        record_removed_saved: "Record removed from saved"
+        all_saved_cleared: "All saved records cleared"
+
+    # Category names (shown on the dashboard grid)
+    categories:
+      queries: "Queries"
+      indexes: "Indexes"
+      tables: "Tables"
+      connections: "Connections"
+      system: "System"
+      schema_analysis: "Schema Analysis"
+
+    # Report names and short descriptions (shown on the dashboard listing)
+    reports:
+      slow_queries:
+        name: "Slow Queries"
+        description: "Queries with high mean execution time"
+      heavy_queries:
+        name: "Heavy Queries"
+        description: "Most frequently called queries"
+      expensive_queries:
+        name: "Expensive Queries"
+        description: "Queries consuming most total time"
+      missing_index_queries:
+        name: "Missing Index Queries"
+        description: "Queries potentially missing indexes"
+      low_cache_hit_queries:
+        name: "Low Cache Hit"
+        description: "Queries with poor cache utilization"
+      temp_file_queries:
+        name: "Temp File Queries"
+        description: "Queries spilling to disk"
+      all_queries:
+        name: "All Queries"
+        description: "All query statistics"
+      unused_indexes:
+        name: "Unused Indexes"
+        description: "Indexes rarely or never scanned"
+      duplicate_indexes:
+        name: "Duplicate Indexes"
+        description: "Redundant indexes"
+      invalid_indexes:
+        name: "Invalid Indexes"
+        description: "Indexes that failed to build"
+      missing_indexes:
+        name: "Missing Indexes"
+        description: "Tables potentially missing indexes"
+      inefficient_indexes:
+        name: "Inefficient Indexes"
+        description: "Indexes with high read-to-fetch ratio"
+      index_usage:
+        name: "Index Usage"
+        description: "Index scan statistics"
+      bloated_indexes:
+        name: "Bloated Indexes"
+        description: "Indexes with high bloat"
+      fk_without_indexes:
+        name: "FK Without Indexes"
+        description: "Foreign keys missing indexes"
+      index_correlation:
+        name: "Index Correlation"
+        description: "Low physical correlation indexes"
+      index_sizes:
+        name: "Index Sizes"
+        description: "Index disk usage"
+      table_sizes:
+        name: "Table Sizes"
+        description: "Table disk usage"
+      bloated_tables:
+        name: "Bloated Tables"
+        description: "Tables with high dead tuple ratio"
+      vacuum_needed:
+        name: "Vacuum Needed"
+        description: "Tables needing vacuum"
+      row_counts:
+        name: "Row Counts"
+        description: "Table row counts"
+      cache_hit_ratios:
+        name: "Cache Hit Ratios"
+        description: "Table cache statistics"
+      seq_scans:
+        name: "Sequential Scans"
+        description: "Tables with high sequential scans"
+      tables_without_pk:
+        name: "No Primary Key"
+        description: "Tables missing primary keys"
+      recently_modified:
+        name: "Recently Modified"
+        description: "Tables with recent activity"
+      update_hotspots:
+        name: "Update Hotspots"
+        description: "Same rows or indexed columns updated repeatedly"
+      unused_tables:
+        name: "Unused Tables"
+        description: "Tables never queried since the last stats reset"
+      active_connections:
+        name: "Active Connections"
+        description: "Current database connections"
+      connection_stats:
+        name: "Connection Stats"
+        description: "Connection statistics by state"
+      long_running_queries:
+        name: "Long Running"
+        description: "Queries running for extended period"
+      blocking_queries:
+        name: "Blocking Queries"
+        description: "Queries blocking others"
+      locks:
+        name: "Locks"
+        description: "Current database locks"
+      idle_connections:
+        name: "Idle Connections"
+        description: "Idle connections"
+      pool_usage:
+        name: "Pool Usage"
+        description: "Connection pool utilization"
+      pool_wait_times:
+        name: "Wait Times"
+        description: "Resource wait analysis"
+      pool_saturation:
+        name: "Pool Saturation"
+        description: "Pool health warnings"
+      connection_churn:
+        name: "Connection Churn"
+        description: "Connection lifecycle analysis"
+      database_sizes:
+        name: "Database Sizes"
+        description: "Size of all databases"
+      settings:
+        name: "Settings"
+        description: "PostgreSQL configuration"
+      extensions:
+        name: "Extensions"
+        description: "Installed extensions"
+      activity_overview:
+        name: "Activity Overview"
+        description: "Current activity summary"
+      wraparound_risk:
+        name: "Wraparound Risk"
+        description: "Transaction ID wraparound proximity"
+      checkpoint_stats:
+        name: "Checkpoint Stats"
+        description: "Checkpoint and bgwriter statistics"
+      cache_stats:
+        name: "Cache Stats"
+        description: "Database cache statistics"
+      missing_validations:
+        name: "Missing Validations"
+        description: "Unique indexes without model validations"
+      unused_columns:
+        name: "Unused Columns"
+        description: "Columns that have only ever held a single value"
+      always_null_columns:
+        name: "Always-NULL Columns"
+        description: "Nullable columns that contain only NULL"
+      polymorphic_without_index:
+        name: "Polymorphic Without Index"
+        description: "Polymorphic associations missing composite index"
+      counter_cache_issues:
+        name: "Counter Cache Issues"
+        description: "counter_cache declarations whose target column is missing"
+      soft_delete_without_scope:
+        name: "Soft Delete Without Scope"
+        description: "Soft-delete columns with no model scope filtering them"
+      orphan_tables:
+        name: "Orphan Tables"
+        description: "DB tables without a corresponding Rails model"
+
+    # Filter parameter labels and descriptions
+    parameters:
+      limit:
+        label: "Limit"
+        description: "Maximum number of results"
+      min_calls:
+        label: "Min Calls"
+        description: "Minimum number of query calls"
+      min_duration_seconds:
+        label: "Min Duration (seconds)"
+        description: "Minimum query duration in seconds"
+      threshold_label: "%{field} Threshold"
+      threshold_description: "Override threshold for %{field}"