pg_reports 0.5.4 → 0.6.0

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"
@@ -220,6 +291,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 +302,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 +321,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 +352,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 +363,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 +402,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,6 +434,7 @@ 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 ===
       missing_validations:
@@ -347,6 +448,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 +458,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."

data/config/locales/ru.yml

@@ -51,6 +51,16 @@ ru:
           - "Увеличение shared_buffers помогает, но есть предел эффективности (обычно 25% RAM)."
           - "Covering indexes (INCLUDE) позволяют выполнять index-only scan без обращения к таблице."
 
+      temp_file_queries:
+        title: "Temp File Queries"
+        what: "Запросы, сбрасывающие промежуточные результаты во временные файлы на диск."
+        how: "Анализирует temp_blks_written и temp_blks_read из pg_stat_statements. Временные файлы создаются, когда work_mem недостаточен для сортировки, хеширования или материализации."
+        nuances:
+          - "Запись во временные файлы на порядки медленнее, чем операции в памяти."
+          - "Увеличение work_mem может устранить временные файлы, но влияет на все сессии — используйте SET LOCAL для конкретных запросов."
+          - "Частые причины: большие сортировки (ORDER BY), hash join на больших таблицах, DISTINCT на множестве строк, сложные CTE."
+          - "Рассмотрите добавление индексов для устранения сортировок или переписывание запросов для уменьшения промежуточных результатов."
+
       all_queries:
         title: "All Queries"
         what: "Полная статистика по всем запросам из pg_stat_statements."
@@ -107,6 +117,17 @@ ru:
           - "idx_tup_read — строки прочитанные из индекса."
           - "idx_tup_fetch — строки извлечённые из таблицы после index scan (для non-covering indexes)."
 
+      inefficient_indexes:
+        title: "Inefficient Indexes"
+        what: "Индексы, которые используются, но сканируют гораздо больше записей, чем реально извлекают."
+        how: "Сравнивает idx_tup_read (записей прочитано из индекса) и idx_tup_fetch (строк извлечено из heap) из pg_stat_user_indexes. Высокое соотношение означает, что порядок колонок индекса не соответствует предикатам запроса, вынуждая PostgreSQL сканировать большие диапазоны индекса."
+        nuances:
+          - "Соотношение read/fetch >10 означает, что индекс читает в 10+ раз больше записей, чем возвращает — явный признак неправильного порядка колонок."
+          - "Для составных индексов (a, b, c) запросы, фильтрующие по (b) или (c) без (a), не могут выполнить точный seek и вынуждены сканировать широкие диапазоны."
+          - "Решение: создать целевой индекс с колонками, соответствующими наиболее селективным WHERE-предикатам в первую очередь."
+          - "Используйте EXPLAIN ANALYZE для подтверждения, что index scan читает избыточное количество записей, прежде чем вносить изменения."
+          - "Index-only scans (где idx_tup_fetch = 0) исключены — они указывают на эффективно работающие covering indexes."
+
       bloated_indexes:
         title: "Bloated Indexes"
         what: "Индексы с высоким уровнем bloat (раздувания) из-за мёртвых кортежей."
@@ -117,6 +138,27 @@ ru:
           - "pg_repack позволяет перестроить индексы без блокировок."
           - "Bloat >30-50% — повод для действий."
 
+      fk_without_indexes:
+        title: "FK Without Indexes"
+        what: "Внешние ключи на дочерних таблицах без поддерживающего индекса."
+        how: "Сравнивает pg_constraint (внешние ключи) с pg_index для поиска FK-колонок без соответствующего ведущего индекса."
+        nuances:
+          - "Без индекса DELETE или UPDATE родительской таблицы вызывает sequential scan дочерней таблицы."
+          - "На больших дочерних таблицах это может вызвать серьёзную конкуренцию блокировок и замедлить каскадные операции."
+          - "Индекс должен иметь FK-колонку как ведущую (первую) для эффективности."
+          - "Маленькие таблицы (< 10K строк) могут не выиграть от добавления индекса — PostgreSQL предпочтёт seq scan."
+
+      index_correlation:
+        title: "Index Correlation"
+        what: "Индексы, где физический порядок строк плохо соответствует порядку индекса."
+        how: "Читает pg_stats.correlation для ведущих колонок индексов. Корреляция около 0 означает случайный физический порядок относительно индекса, что вызывает избыточный random I/O при range scan."
+        nuances:
+          - "Корреляция от -1 до 1. Значения около 0 — случайный порядок; около 1 или -1 — упорядоченный."
+          - "Низкая корреляция в основном влияет на range scan (BETWEEN, >, <) и ORDER BY — точечные поиски затронуты меньше."
+          - "CLUSTER table USING index физически переупорядочивает строки, но блокирует таблицу и не поддерживается автоматически."
+          - "Для append-only таблиц с timestamp колонками корреляция естественно высокая — действий не требуется."
+          - "Показаны только таблицы > 10MB с > 100 index scan для снижения шума."
+
       index_sizes:
         title: "Index Sizes"
         what: "Размеры индексов на диске."
@@ -183,6 +225,16 @@ ru:
           - "Высокий seq_tup_read/seq_scan = много строк за один scan = возможно норма."
           - "Низкий seq_tup_read/seq_scan = много scan маленьких объёмов = возможно N+1."
 
+      tables_without_pk:
+        title: "Tables Without Primary Keys"
+        what: "Таблицы без первичного ключа."
+        how: "Проверяет pg_index на отсутствие indisprimary записей для пользовательских таблиц."
+        nuances:
+          - "Логическая репликация требует первичный ключ или REPLICA IDENTITY для идентификации строк."
+          - "Без PK операции UPDATE и DELETE требуют иного способа уникальной идентификации строк, часто приводя к полным сканам таблицы."
+          - "Join-таблицы (many-to-many) часто намеренно без PK — рассмотрите добавление составного PK."
+          - "Некоторые ORM (например, Rails) предполагают наличие 'id' первичного ключа — таблицы без него могут вызвать ошибки фреймворка."
+
       recently_modified:
         title: "Recently Modified"
         what: "Таблицы с недавней активностью INSERT/UPDATE/DELETE."
@@ -326,6 +378,28 @@ ru:
           - "Полезно для быстрой оценки состояния базы."
           - "Сравнивайте с baseline для выявления аномалий."
 
+      wraparound_risk:
+        title: "Wraparound Risk"
+        what: "Близость возраста Transaction ID к лимиту wraparound в 2 миллиарда."
+        how: "Читает age(datfrozenxid) из pg_database. Когда значение приближается к 2^31 (~2.1 млрд), PostgreSQL остановится для предотвращения повреждения данных."
+        nuances:
+          - "autovacuum_freeze_max_age (по умолчанию 200M) автоматически запускает агрессивный anti-wraparound VACUUM."
+          - "Если age превышает freeze_max_age, anti-wraparound VACUUM уже должен работать — если нет, расследуйте причину."
+          - "Долгоживущие транзакции не дают VACUUM продвинуть frozen XID — мониторьте idle-in-transaction."
+          - "В экстренных случаях запустите VACUUM FREEZE на самых больших/старых таблицах первыми."
+          - "Pct > 50% — предупреждение; > 75% — критично, требует немедленных действий."
+
+      checkpoint_stats:
+        title: "Checkpoint Stats"
+        what: "Частота чекпоинтов и метрики производительности background writer."
+        how: "Данные из pg_stat_bgwriter показывают количество чекпоинтов, тайминги и распределение записи буферов."
+        nuances:
+          - "checkpoints_timed = запланированные чекпоинты (нормально); checkpoints_req = вынужденные чекпоинты (под нагрузкой)."
+          - "Высокий requested_pct означает, что WAL заполняется до checkpoint_timeout — увеличьте max_wal_size."
+          - "buffers_backend > 0 означает, что бэкенды сами пишут грязные буферы — увеличьте shared_buffers или активность bgwriter."
+          - "bgwriter_stops (maxwritten_clean) > 0 означает, что bgwriter достиг лимита за раунд — увеличьте bgwriter_lru_maxpages."
+          - "Статистика накапливается с момента stats_reset — сравнивайте за периоды для осмысленного анализа."
+
       cache_stats:
         title: "Cache Stats"
         what: "Статистика кэширования базы данных."
@@ -356,6 +430,13 @@ ru:
       low_cache_hit: "Низкий cache hit ratio. Запрос часто читает с диска вместо кэша."
       high_seq_scan: "Много sequential scan. Возможно не хватает индекса."
       unused_index: "Индекс не используется. Кандидат на удаление."
+      inefficient_index: "Индекс читает гораздо больше записей, чем извлекает. Вероятно, порядок колонок составного индекса не соответствует предикатам запроса."
+      fk_without_index: "FK-колонка без поддерживающего индекса. DELETE/UPDATE родительской таблицы вызовет sequential scan."
+      low_correlation: "Низкая физическая корреляция между индексом и порядком строк. Range scan вызовет избыточный random I/O."
+      temp_file_heavy: "Запрос сбрасывает данные во временные файлы на диск. Рассмотрите увеличение work_mem или оптимизацию запроса."
+      missing_pk: "Таблица без первичного ключа. Это ломает логическую репликацию и может вызвать проблемы с ORM."
+      wraparound_risk: "Возраст Transaction ID приближается к лимиту wraparound. Требуется VACUUM FREEZE."
+      high_checkpoint_req: "Высокий процент вынужденных чекпоинтов. Рассмотрите увеличение max_wal_size."
       high_bloat: "Высокий bloat. Требуется REINDEX или VACUUM."
       many_dead_tuples: "Много мёртвых строк. Требуется VACUUM."
       long_running: "Долго выполняющийся запрос. Может блокировать другие операции."

data/config/locales/uk.yml

@@ -51,6 +51,16 @@ uk:
           - "Збільшення shared_buffers допомагає, але є межа ефективності (зазвичай 25% RAM)."
           - "Covering indexes (INCLUDE) дозволяють виконувати index-only scan без звернення до таблиці."
 
+      temp_file_queries:
+        title: "Temp File Queries"
+        what: "Запити, що скидають проміжні результати у тимчасові файли на диск."
+        how: "Аналізує temp_blks_written та temp_blks_read з pg_stat_statements. Тимчасові файли створюються, коли work_mem недостатній для сортування, хешування або матеріалізації."
+        nuances:
+          - "Запис у тимчасові файли на порядки повільніший за операції в пам'яті."
+          - "Збільшення work_mem може усунути тимчасові файли, але впливає на всі сесії — використовуйте SET LOCAL для конкретних запитів."
+          - "Часті причини: великі сортування (ORDER BY), hash join на великих таблицях, DISTINCT на багатьох рядках, складні CTE."
+          - "Розгляньте додавання індексів для усунення сортувань або переписування запитів для зменшення проміжних результатів."
+
       all_queries:
         title: "All Queries"
         what: "Повна статистика по всіх запитах з pg_stat_statements."
@@ -107,6 +117,17 @@ uk:
           - "idx_tup_read — рядки прочитані з індексу."
           - "idx_tup_fetch — рядки отримані з таблиці після index scan (для non-covering indexes)."
 
+      inefficient_indexes:
+        title: "Inefficient Indexes"
+        what: "Індекси, які використовуються, але сканують значно більше записів, ніж реально витягують."
+        how: "Порівнює idx_tup_read (записів прочитано з індексу) та idx_tup_fetch (рядків витягнуто з heap) з pg_stat_user_indexes. Високе співвідношення означає, що порядок колонок індексу не відповідає предикатам запиту, змушуючи PostgreSQL сканувати великі діапазони індексу."
+        nuances:
+          - "Співвідношення read/fetch >10 означає, що індекс читає в 10+ разів більше записів, ніж повертає — явна ознака неправильного порядку колонок."
+          - "Для складених індексів (a, b, c) запити, що фільтрують по (b) або (c) без (a), не можуть виконати точний seek і змушені сканувати широкі діапазони."
+          - "Рішення: створити цільовий індекс з колонками, що відповідають найбільш селективним WHERE-предикатам у першу чергу."
+          - "Використовуйте EXPLAIN ANALYZE для підтвердження, що index scan читає надлишкову кількість записів, перш ніж вносити зміни."
+          - "Index-only scans (де idx_tup_fetch = 0) виключені — вони вказують на ефективно працюючі covering indexes."
+
       bloated_indexes:
         title: "Bloated Indexes"
         what: "Індекси з високим рівнем bloat (роздування) через мертві кортежі."
@@ -117,6 +138,27 @@ uk:
           - "pg_repack дозволяє перебудувати індекси без блокувань."
           - "Bloat >30-50% — привід для дій."
 
+      fk_without_indexes:
+        title: "FK Without Indexes"
+        what: "Зовнішні ключі на дочірніх таблицях без підтримуючого індексу."
+        how: "Порівнює pg_constraint (зовнішні ключі) з pg_index для пошуку FK-колонок без відповідного ведучого індексу."
+        nuances:
+          - "Без індексу DELETE або UPDATE батьківської таблиці викликає sequential scan дочірньої таблиці."
+          - "На великих дочірніх таблицях це може спричинити серйозну конкуренцію блокувань та сповільнити каскадні операції."
+          - "Індекс повинен мати FK-колонку як ведучу (першу) для ефективності."
+          - "Маленькі таблиці (< 10K рядків) можуть не виграти від додавання індексу — PostgreSQL віддасть перевагу seq scan."
+
+      index_correlation:
+        title: "Index Correlation"
+        what: "Індекси, де фізичний порядок рядків погано відповідає порядку індексу."
+        how: "Читає pg_stats.correlation для ведучих колонок індексів. Кореляція близько 0 означає випадковий фізичний порядок відносно індексу, що спричиняє надлишковий random I/O при range scan."
+        nuances:
+          - "Кореляція від -1 до 1. Значення близько 0 — випадковий порядок; близько 1 або -1 — впорядкований."
+          - "Низька кореляція переважно впливає на range scan (BETWEEN, >, <) та ORDER BY — точкові пошуки зачіпаються менше."
+          - "CLUSTER table USING index фізично переупорядковує рядки, але блокує таблицю та не підтримується автоматично."
+          - "Для append-only таблиць з timestamp колонками кореляція природно висока — дій не потрібно."
+          - "Показані лише таблиці > 10MB з > 100 index scan для зниження шуму."
+
       index_sizes:
         title: "Index Sizes"
         what: "Розміри індексів на диску."
@@ -183,6 +225,16 @@ uk:
           - "Високий seq_tup_read/seq_scan = багато рядків за один scan = можливо норма."
           - "Низький seq_tup_read/seq_scan = багато scan маленьких об'ємів = можливо N+1."
 
+      tables_without_pk:
+        title: "Tables Without Primary Keys"
+        what: "Таблиці без первинного ключа."
+        how: "Перевіряє pg_index на відсутність indisprimary записів для користувацьких таблиць."
+        nuances:
+          - "Логічна реплікація потребує первинний ключ або REPLICA IDENTITY для ідентифікації рядків."
+          - "Без PK операції UPDATE та DELETE потребують іншого способу унікальної ідентифікації рядків, часто призводячи до повних сканів таблиці."
+          - "Join-таблиці (many-to-many) часто навмисно без PK — розгляньте додавання складеного PK."
+          - "Деякі ORM (наприклад, Rails) передбачають наявність 'id' первинного ключа — таблиці без нього можуть спричинити помилки фреймворку."
+
       recently_modified:
         title: "Recently Modified"
         what: "Таблиці з недавньою активністю INSERT/UPDATE/DELETE."
@@ -249,6 +301,46 @@ uk:
           - "Занадто багато idle = застосунок не закриває з'єднання або пул занадто великий."
           - "idle_session_timeout (PostgreSQL 14+) може автоматично закривати idle з'єднання."
 
+      pool_usage:
+        title: "Використання пулу з'єднань"
+        what: "Поточне використання пулу з'єднань з показниками активних, idle та доступних з'єднань по базах даних."
+        how: "Аналіз станів з'єднань в pg_stat_activity та порівняння з лімітом max_connections."
+        nuances:
+          - "Утилізація вище 70% означає наближення до ліміту — розгляньте масштабування."
+          - "Idle in transaction з'єднання витрачають ресурси та блокують VACUUM."
+          - "max_connections — глобальне налаштування для всієї БД, а не для кожної бази окремо."
+          - "Connection pooler'и (PgBouncer/pgpool) дозволяють мати більше з'єднань на рівні застосунку."
+
+      pool_wait_times:
+        title: "Аналіз часу очікування"
+        what: "Запити, що очікують ресурсів (блокування, I/O, мережа)."
+        how: "Аналіз wait_event та wait_event_type з pg_stat_activity для не-idle з'єднань."
+        nuances:
+          - "ClientRead очікування = повільний клієнт не встигає споживати дані."
+          - "Lock очікування = конкуренція між конкурентними запитами."
+          - "IO очікування = проблеми продуктивності диска або недостатній кеш."
+          - "Очікування понад 60 секунд критичні та потребують негайного розслідування."
+
+      pool_saturation:
+        title: "Попередження про насичення пулу"
+        what: "Загальні метрики здоров'я пулу з'єднань з попередженнями про насичення та рекомендаціями."
+        how: "Розрахунок відсотків утилізації для total, active, idle та проблемних з'єднань."
+        nuances:
+          - "Постійна утилізація вище 70% = необхідність налаштування пулу або масштабування."
+          - "Висока кількість idle in transaction = проблеми обробки транзакцій застосунком."
+          - "superuser_reserved_connections зменшують доступну ємність пулу."
+          - "Відстежуйте тренди — різкі стрибки можуть вказувати на витоки з'єднань."
+
+      connection_churn:
+        title: "Аналіз оборотності з'єднань"
+        what: "Аналіз патернів життєвого циклу з'єднань для виявлення надлишкового churn (часте підключення/відключення)."
+        how: "Вивчення віку з'єднань для ідентифікації короткоживучих з'єднань та розрахунку churn rate по застосунках."
+        nuances:
+          - "З'єднання молодші 10 секунд = короткоживучі."
+          - "Churn rate вище 50% = відсутність або неправильне налаштування connection pooling."
+          - "Багато коротких з'єднань = збільшене навантаження на CPU та автентифікацію."
+          - "Веб-застосунки повинні підтримувати пул з'єднань, а не створювати з'єднання на кожен запит."
+
       # === SYSTEM ===
       database_sizes:
         title: "Database Sizes"
@@ -286,6 +378,28 @@ uk:
           - "Корисно для швидкої оцінки стану бази."
           - "Порівнюйте з baseline для виявлення аномалій."
 
+      wraparound_risk:
+        title: "Wraparound Risk"
+        what: "Близькість віку Transaction ID до ліміту wraparound у 2 мільярди."
+        how: "Читає age(datfrozenxid) з pg_database. Коли значення наближається до 2^31 (~2.1 млрд), PostgreSQL зупиниться для запобігання пошкодження даних."
+        nuances:
+          - "autovacuum_freeze_max_age (за замовчуванням 200M) автоматично запускає агресивний anti-wraparound VACUUM."
+          - "Якщо age перевищує freeze_max_age, anti-wraparound VACUUM вже повинен працювати — якщо ні, розслідуйте причину."
+          - "Довготривалі транзакції не дають VACUUM просунути frozen XID — моніторте idle-in-transaction."
+          - "В екстрених випадках запустіть VACUUM FREEZE на найбільших/найстаріших таблицях першими."
+          - "Pct > 50% — попередження; > 75% — критично, потребує негайних дій."
+
+      checkpoint_stats:
+        title: "Checkpoint Stats"
+        what: "Частота чекпоінтів та метрики продуктивності background writer."
+        how: "Дані з pg_stat_bgwriter показують кількість чекпоінтів, тайминги та розподіл запису буферів."
+        nuances:
+          - "checkpoints_timed = заплановані чекпоінти (нормально); checkpoints_req = вимушені чекпоінти (під навантаженням)."
+          - "Високий requested_pct означає, що WAL заповнюється до checkpoint_timeout — збільште max_wal_size."
+          - "buffers_backend > 0 означає, що бекенди самі пишуть брудні буфери — збільште shared_buffers або активність bgwriter."
+          - "bgwriter_stops (maxwritten_clean) > 0 означає, що bgwriter досяг ліміту за раунд — збільште bgwriter_lru_maxpages."
+          - "Статистика накопичується з моменту stats_reset — порівнюйте за періоди для осмисленого аналізу."
+
       cache_stats:
         title: "Cache Stats"
         what: "Статистика кешування бази даних."
@@ -316,8 +430,20 @@ uk:
       low_cache_hit: "Низький cache hit ratio. Запит часто читає з диска замість кешу."
       high_seq_scan: "Багато sequential scan. Можливо не вистачає індексу."
       unused_index: "Індекс не використовується. Кандидат на видалення."
+      inefficient_index: "Індекс читає значно більше записів, ніж витягує. Ймовірно, порядок колонок складеного індексу не відповідає предикатам запиту."
+      fk_without_index: "FK-колонка без підтримуючого індексу. DELETE/UPDATE батьківської таблиці спричинить sequential scan."
+      low_correlation: "Низька фізична кореляція між індексом та порядком рядків. Range scan спричинить надлишковий random I/O."
+      temp_file_heavy: "Запит скидає дані у тимчасові файли на диск. Розгляньте збільшення work_mem або оптимізацію запиту."
+      missing_pk: "Таблиця без первинного ключа. Це ламає логічну реплікацію та може спричинити проблеми з ORM."
+      wraparound_risk: "Вік Transaction ID наближається до ліміту wraparound. Потрібен VACUUM FREEZE."
+      high_checkpoint_req: "Високий відсоток вимушених чекпоінтів. Розгляньте збільшення max_wal_size."
       high_bloat: "Високий bloat. Потрібен REINDEX або VACUUM."
       many_dead_tuples: "Багато мертвих рядків. Потрібен VACUUM."
       long_running: "Довго виконуваний запит. Може блокувати інші операції."
       blocking: "Блокує інші запити. Потребує уваги."
       idle_in_transaction: "Відкрита транзакція без активності. Блокує VACUUM та утримує локи."
+      high_pool_usage: "Висока утилізація пулу з'єднань. Збільште max_connections або впровадьте connection pooling."
+      long_wait_time: "Запит занадто довго очікує ресурсів. Перевірте конкуренцію блокувань або проблеми I/O."
+      pool_saturation: "Пул з'єднань насичений. Ризик вичерпання з'єднань та помилок застосунку."
+      high_connection_churn: "Висока оборотність з'єднань. Впровадьте connection pooling для зниження накладних витрат."
+      too_many_short_connections: "Занадто багато короткоживучих з'єднань. Застосунок повинен перевикористовувати з'єднання через pooling."