pg_reports 0.5.3 → 0.6.0

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."

data/lib/pg_reports/compatibility.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PgReports
+  # Checks runtime environment and warns about outdated or unsupported versions.
+  # Called once at boot (Ruby/Rails) and lazily on first DB access (PostgreSQL).
+  module Compatibility
+    # Keep in sync with gemspec constraints
+    MINIMUM_RUBY_VERSION     = "2.7"
+    MINIMUM_RAILS_VERSION    = "5.0"
+    MINIMUM_PG_VERSION       = 12_00_00  # server_version_num format
+    MINIMUM_PG_VERSION_LABEL = "12"
+
+    class << self
+      def check_ruby!
+        return if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new(MINIMUM_RUBY_VERSION)
+
+        warn "[pg_reports] Ruby #{RUBY_VERSION} is not supported. " \
+             "Minimum required version is Ruby #{MINIMUM_RUBY_VERSION}."
+      end
+
+      def check_rails!
+        return unless defined?(Rails::VERSION::STRING)
+        return if Gem::Version.new(Rails::VERSION::STRING) >= Gem::Version.new(MINIMUM_RAILS_VERSION)
+
+        warn "[pg_reports] Rails #{Rails::VERSION::STRING} is not supported. " \
+             "Minimum required version is Rails #{MINIMUM_RAILS_VERSION}."
+      end
+
+      def check_postgresql!
+        version_num = pg_version_num
+        return if version_num.nil? # no connection yet — skip silently
+        return if version_num >= MINIMUM_PG_VERSION
+
+        label = pg_version_label(version_num)
+        warn "[pg_reports] PostgreSQL #{label} is not supported. " \
+             "Minimum required version is PostgreSQL #{MINIMUM_PG_VERSION_LABEL}. " \
+             "Some reports may return errors or incomplete data."
+      end
+
+      def check_all!
+        check_ruby!
+        check_rails!
+        check_postgresql!
+      end
+
+      private
+
+      def pg_version_num
+        connection = PgReports.config.connection
+        result = connection.exec_query("SELECT current_setting('server_version_num')::int AS v")
+        result.first&.fetch("v", 0).to_i
+      rescue
+        nil
+      end
+
+      def pg_version_label(version_num)
+        major = version_num / 1_00_00
+        minor = (version_num % 1_00_00) / 100
+        "#{major}.#{minor}"
+      end
+    end
+  end
+end

data/lib/pg_reports/configuration.rb

@@ -13,6 +13,7 @@ module PgReports
 
     # Index analysis thresholds
     attr_accessor :unused_index_threshold_scans # Index with fewer scans is unused
+    attr_accessor :inefficient_index_threshold_ratio # Read/fetch ratio above this is inefficient
 
     # Table analysis thresholds
     attr_accessor :bloat_threshold_percent      # Tables with more bloat are problematic
@@ -53,6 +54,7 @@ module PgReports
 
       # Index thresholds
       @unused_index_threshold_scans = 50
+      @inefficient_index_threshold_ratio = 10
 
       # Table thresholds
       @bloat_threshold_percent = 20

data/lib/pg_reports/dashboard/reports_registry.rb

@@ -32,6 +32,10 @@ module PgReports
           thresholds: {},
           problem_fields: []
         },
+        temp_file_queries: {
+          thresholds: {temp_mb_written: {warning: 100, critical: 1000}},
+          problem_fields: ["temp_mb_written"]
+        },
 
         # === INDEXES ===
         unused_indexes: {
@@ -50,6 +54,10 @@ module PgReports
           thresholds: {seq_scan_ratio: {warning: 0.5, critical: 0.9}},
           problem_fields: ["seq_scan", "seq_tup_read"]
         },
+        inefficient_indexes: {
+          thresholds: {read_to_fetch_ratio: {warning: 10, critical: 100}},
+          problem_fields: ["read_to_fetch_ratio"]
+        },
         index_usage: {
           thresholds: {},
           problem_fields: []
@@ -62,6 +70,14 @@ module PgReports
           thresholds: {size_bytes: {warning: 1073741824, critical: 10737418240}},
           problem_fields: ["size_bytes"]
         },
+        fk_without_indexes: {
+          thresholds: {},
+          problem_fields: ["child_table_size_mb"]
+        },
+        index_correlation: {
+          thresholds: {correlation: {warning: 0.5, critical: 0.2, inverted: true}},
+          problem_fields: ["correlation"]
+        },
 
         # === TABLES ===
         table_sizes: {
@@ -92,6 +108,10 @@ module PgReports
           thresholds: {},
           problem_fields: []
         },
+        tables_without_pk: {
+          thresholds: {},
+          problem_fields: []
+        },
 
         # === CONNECTIONS ===
         active_connections: {
@@ -159,6 +179,14 @@ module PgReports
           thresholds: {cache_hit_ratio: {warning: 0.95, critical: 0.90, inverted: true}},
           problem_fields: ["cache_hit_ratio"]
         },
+        wraparound_risk: {
+          thresholds: {pct_towards_wraparound: {warning: 50, critical: 75}},
+          problem_fields: ["pct_towards_wraparound"]
+        },
+        checkpoint_stats: {
+          thresholds: {requested_pct: {warning: 50, critical: 75}},
+          problem_fields: ["requested_pct"]
+        },
 
         # === SCHEMA ANALYSIS ===
         missing_validations: {
@@ -178,6 +206,7 @@ module PgReports
             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", new: true},
             all_queries: {name: "All Queries", description: "All query statistics"}
           }
         },
@@ -190,8 +219,11 @@ module PgReports
             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", new: true},
             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", new: true},
+            index_correlation: {name: "Index Correlation", description: "Low physical correlation indexes", new: true},
             index_sizes: {name: "Index Sizes", description: "Index disk usage"}
           }
         },
@@ -206,6 +238,7 @@ module PgReports
             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", new: true},
             recently_modified: {name: "Recently Modified", description: "Tables with recent activity"}
           }
         },
@@ -235,6 +268,8 @@ module PgReports
             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", new: true},
+            checkpoint_stats: {name: "Checkpoint Stats", description: "Checkpoint and bgwriter statistics", new: true},
             cache_stats: {name: "Cache Stats", description: "Database cache statistics"}
           }
         },
@@ -272,6 +307,7 @@ module PgReports
           what: I18n.t("#{i18n_key}.what", default: ""),
           how: I18n.t("#{i18n_key}.how", default: ""),
           nuances: I18n.t("#{i18n_key}.nuances", default: []),
+          ai_prompt: I18n.t("#{i18n_key}.ai_prompt", default: nil),
           thresholds: config[:thresholds],
           problem_fields: config[:problem_fields]
         }

data/lib/pg_reports/definitions/indexes/fk_without_indexes.yml

@@ -0,0 +1,30 @@
+# Foreign keys without indexes on the child table
+# Missing indexes cause sequential scans on parent DELETE/UPDATE
+
+report:
+  name: fk_without_indexes
+  module: indexes
+  description: "Foreign keys missing indexes on the referencing table"
+
+  sql:
+    category: indexes
+    file: fk_without_indexes
+
+  title: "Foreign Keys Without Indexes"
+
+  columns:
+    - constraint_name
+    - child_table
+    - child_column
+    - parent_table
+    - parent_column
+    - child_table_size_mb
+
+  parameters:
+    limit:
+      type: integer
+      default: 50
+      description: "Maximum number of results"
+
+  problem_explanations:
+    child_table_size_mb: fk_without_index

data/lib/pg_reports/definitions/indexes/index_correlation.yml

@@ -0,0 +1,31 @@
+# Index correlation analysis
+# Low correlation means physical row order doesn't match index order, causing random I/O
+
+report:
+  name: index_correlation
+  module: indexes
+  description: "Indexes with low physical correlation causing excessive random I/O"
+
+  sql:
+    category: indexes
+    file: index_correlation
+
+  title: "Index Correlation (tables > 10MB, scans > 100)"
+
+  columns:
+    - schema
+    - table_name
+    - column_name
+    - index_name
+    - correlation
+    - table_size_mb
+    - idx_scan
+
+  parameters:
+    limit:
+      type: integer
+      default: 50
+      description: "Maximum number of results"
+
+  problem_explanations:
+    correlation: low_correlation

data/lib/pg_reports/definitions/indexes/inefficient_indexes.yml

@@ -0,0 +1,45 @@
+# Inefficient indexes - indexes that are used but scan far more entries than they fetch
+# High read-to-fetch ratio indicates misaligned composite index column order
+
+report:
+  name: inefficient_indexes
+  module: indexes
+  description: "Indexes with high read-to-fetch ratio indicating inefficient scans"
+
+  sql:
+    category: indexes
+    file: inefficient_indexes
+
+  title: "Inefficient Indexes (read/fetch ratio > ${threshold})"
+  title_vars:
+    threshold:
+      source: config
+      key: inefficient_index_threshold_ratio
+
+  columns:
+    - schema
+    - table_name
+    - index_name
+    - idx_scan
+    - idx_tup_read
+    - idx_tup_fetch
+    - read_to_fetch_ratio
+    - index_size_mb
+    - index_definition
+
+  parameters:
+    limit:
+      type: integer
+      default: 50
+      description: "Maximum number of results"
+
+  filters:
+    - field: read_to_fetch_ratio
+      operator: gte
+      value:
+        source: config
+        key: inefficient_index_threshold_ratio
+      cast: float
+
+  problem_explanations:
+    read_to_fetch_ratio: inefficient_index

data/lib/pg_reports/definitions/queries/temp_file_queries.yml

@@ -0,0 +1,39 @@
+# Temp file heavy queries
+# Queries that spill to disk due to insufficient work_mem
+
+report:
+  name: temp_file_queries
+  module: queries
+  description: "Queries spilling data to temporary files on disk"
+
+  sql:
+    category: queries
+    file: temp_file_queries
+    params:
+      max_query_length:
+        source: config
+        key: max_query_length
+
+  title: "Temp File Queries"
+
+  columns:
+    - query
+    - calls
+    - temp_mb_written
+    - temp_mb_read
+    - total_time_sec
+    - mean_time_ms
+    - rows
+
+  parameters:
+    limit:
+      type: integer
+      default: 20
+      description: "Maximum number of results"
+
+  enrichment:
+    module: queries
+    hook: enrich_with_annotations
+
+  problem_explanations:
+    temp_mb_written: temp_file_heavy

data/lib/pg_reports/definitions/system/wraparound_risk.yml

@@ -0,0 +1,31 @@
+# Transaction ID wraparound risk
+# Monitors proximity to the 2-billion XID limit that triggers emergency shutdown
+
+report:
+  name: wraparound_risk
+  module: system
+  description: "Transaction ID wraparound risk for all databases"
+
+  sql:
+    category: system
+    file: wraparound_risk
+
+  title: "Transaction ID Wraparound Risk"
+
+  columns:
+    - database_name
+    - xid_age
+    - pct_towards_wraparound
+    - remaining_xids
+    - freeze_max_age
+    - status
+    - database_size
+
+  parameters:
+    limit:
+      type: integer
+      default: 50
+      description: "Maximum number of results"
+
+  problem_explanations:
+    pct_towards_wraparound: wraparound_risk

data/lib/pg_reports/definitions/tables/tables_without_pk.yml

@@ -0,0 +1,28 @@
+# Tables without primary keys
+# Missing PKs break logical replication and make row identification unreliable
+
+report:
+  name: tables_without_pk
+  module: tables
+  description: "Tables missing a primary key"
+
+  sql:
+    category: tables
+    file: tables_without_pk
+
+  title: "Tables Without Primary Keys"
+
+  columns:
+    - schema
+    - table_name
+    - estimated_rows
+    - table_size_mb
+
+  parameters:
+    limit:
+      type: integer
+      default: 50
+      description: "Maximum number of results"
+
+  problem_explanations:
+    table_name: missing_pk

data/lib/pg_reports/engine.rb

@@ -13,6 +13,12 @@ module PgReports
       config.i18n.load_path += Dir[root.join("config", "locales", "*.yml")]
     end
 
+    initializer "pg_reports.compatibility_check" do
+      ActiveSupport.on_load(:active_record) do
+        PgReports::Compatibility.check_postgresql!
+      end
+    end
+
     initializer "pg_reports.assets" do |_app|
       # Assets are inline in views, no precompilation needed
     end

data/lib/pg_reports/modules/indexes.rb

@@ -12,6 +12,9 @@ module PgReports
       # - duplicate_indexes
       # - invalid_indexes
       # - missing_indexes(limit: 20)
+      # - inefficient_indexes(limit: 50)
+      # - fk_without_indexes(limit: 50)
+      # - index_correlation(limit: 50)
       # - index_usage(limit: 50)
       # - bloated_indexes(limit: 20)
       # - index_sizes(limit: 50)

data/lib/pg_reports/modules/queries.rb

@@ -13,6 +13,7 @@ module PgReports
       # - expensive_queries(limit: 20)
       # - missing_index_queries(limit: 20)
       # - low_cache_hit_queries(limit: 20, min_calls: 100)
+      # - temp_file_queries(limit: 20)
       # - all_queries(limit: 50)
 
       # Reset pg_stat_statements statistics

data/lib/pg_reports/modules/system.rb

@@ -12,7 +12,11 @@ module PgReports
       # - settings
       # - extensions
       # - activity_overview
+      # - wraparound_risk(limit: 50)
       # - cache_stats
+      #
+      # Manually implemented (version-dependent SQL):
+      # - checkpoint_stats(limit: 10)
 
       # pg_stat_statements availability check
       # @return [Boolean] Whether pg_stat_statements is available
@@ -132,6 +136,22 @@ module PgReports
         end
       end
 
+      # Checkpoint stats — uses version-specific SQL because PostgreSQL 17+
+      # moved checkpoint columns from pg_stat_bgwriter to pg_stat_checkpointer
+      def checkpoint_stats(limit: 10)
+        sql_file = pg_version >= 170_000 ? :checkpoint_stats : :checkpoint_stats_legacy
+        data = executor.execute_from_file(:system, sql_file)
+        data = data.first(limit) if limit
+
+        Report.new(
+          title: "Checkpoint Statistics",
+          data: data,
+          columns: %w[checkpoints_timed checkpoints_requested checkpoint_write_time_sec
+                      checkpoint_sync_time_sec buffers_checkpoint buffers_clean
+                      bgwriter_stops buffers_alloc requested_pct stats_reset]
+        )
+      end
+
       # Get list of all databases
       # @return [Array<Hash>] List of databases with sizes
       def databases_list
@@ -152,6 +172,13 @@ module PgReports
 
       private
 
+      def pg_version
+        @pg_version ||= begin
+          result = executor.execute("SELECT current_setting('server_version_num')::int AS v")
+          result.first&.fetch("v", 0).to_i
+        end
+      end
+
       def executor
         @executor ||= Executor.new
       end