pg_reports 0.5.3 → 0.6.0

data/lib/pg_reports/modules/tables.rb

@@ -14,6 +14,7 @@ module PgReports
       # - row_counts(limit: 50)
       # - cache_hit_ratios(limit: 50)
       # - seq_scans(limit: 20)
+      # - tables_without_pk(limit: 50)
       # - recently_modified(limit: 20)
 
       private

data/lib/pg_reports/query_monitor.rb

@@ -8,65 +8,99 @@ module PgReports
   class QueryMonitor
     include Singleton
 
-    attr_reader :enabled, :session_id
+    CACHE_KEY_ENABLED = "pg_reports:query_monitor:enabled"
+    CACHE_KEY_SESSION_ID = "pg_reports:query_monitor:session_id"
+    CACHE_TTL = 24.hours
 
     def initialize
-      @enabled = false
       @subscriber = nil
       @mutex = Mutex.new
-      @session_id = nil
       @queries = []
+      @handling_event = false
+
+      # Local state — used by the event handler to avoid cache reads
+      # (which generate SQL events and cause infinite recursion with DB-backed caches)
+      @enabled = false
+      @session_id = nil
+
+      sync_from_cache
+      ensure_subscription_if_enabled
+    end
+
+    def enabled
+      @enabled
+    end
+
+    def session_id
+      @session_id
     end
 
     def start
       @mutex.synchronize do
-        if @enabled
+        if enabled
+          Rails.logger.info("PgReports: Monitoring already active, session_id=#{session_id}") if defined?(Rails)
           return {success: false, message: "Monitoring already active"}
         end
 
-        @session_id = SecureRandom.uuid
+        new_session_id = SecureRandom.uuid
         @queries = []
+
+        # Update local state first (used by event handler — no cache round-trip)
         @enabled = true
+        @session_id = new_session_id
 
-        # Subscribe to sql.active_record events
-        @subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |name, started, finished, unique_id, payload|
-          handle_sql_event(name, started, finished, unique_id, payload)
-        end
+        # Store state in cache so other processes can see it
+        cache_write(CACHE_KEY_ENABLED, true)
+        cache_write(CACHE_KEY_SESSION_ID, new_session_id)
+
+        Rails.logger.info("PgReports: Monitoring started, session_id=#{new_session_id}") if defined?(Rails)
+
+        # Subscribe to sql.active_record events in THIS process
+        ensure_subscription
 
         # Write session start marker to file
         write_session_marker("session_start")
 
-        {success: true, message: "Query monitoring started", session_id: @session_id}
+        {success: true, message: "Query monitoring started", session_id: new_session_id}
       end
     rescue => e
       @enabled = false
+      @session_id = nil
+      cache_write(CACHE_KEY_ENABLED, false)
       {success: false, error: e.message}
     end
 
     def stop
       @mutex.synchronize do
-        unless @enabled
+        unless enabled
           return {success: false, message: "Monitoring not active"}
         end
 
-        # Unsubscribe from notifications
+        current_session_id = @session_id
+
+        # Clear local state immediately — stops event handler from processing
+        @enabled = false
+        @session_id = nil
+
+        # Unsubscribe from notifications in THIS process
         if @subscriber
           ActiveSupport::Notifications.unsubscribe(@subscriber)
           @subscriber = nil
         end
 
         # Write session end marker to file
-        write_session_marker("session_end")
+        write_session_marker("session_end", current_session_id)
 
         # Flush queries to file
         flush_to_file
 
-        @enabled = false
+        # Clear state from cache so other processes see it
+        cache_delete(CACHE_KEY_ENABLED)
+        cache_delete(CACHE_KEY_SESSION_ID)
+
         @queries = []
-        session_id = @session_id
-        @session_id = nil
 
-        {success: true, message: "Query monitoring stopped", session_id: session_id}
+        {success: true, message: "Query monitoring stopped", session_id: current_session_id}
       end
     rescue => e
       {success: false, error: e.message}
@@ -74,8 +108,8 @@ module PgReports
 
     def status
       {
-        enabled: @enabled,
-        session_id: @session_id,
+        enabled: enabled,
+        session_id: session_id,
         query_count: @queries.size
       }
     end
@@ -130,31 +164,90 @@ module PgReports
 
     private
 
-    def handle_sql_event(name, started, finished, unique_id, payload)
+    # Cache helpers - work with or without Rails.cache
+    def cache_read(key)
+      return nil unless cache_available?
+      Rails.cache.read(key)
+    rescue => e
+      Rails.logger.warn("PgReports: Cache read failed: #{e.message}") if defined?(Rails.logger)
+      nil
+    end
+
+    def cache_write(key, value)
+      return false unless cache_available?
+      Rails.cache.write(key, value, expires_in: CACHE_TTL)
+    rescue => e
+      Rails.logger.warn("PgReports: Cache write failed: #{e.message}") if defined?(Rails.logger)
+      false
+    end
+
+    def cache_delete(key)
+      return false unless cache_available?
+      Rails.cache.delete(key)
+    rescue => e
+      Rails.logger.warn("PgReports: Cache delete failed: #{e.message}") if defined?(Rails.logger)
+      false
+    end
+
+    def cache_available?
+      defined?(Rails) && defined?(Rails.cache)
+    end
+
+    # Sync local state from shared cache (called on initialize for multi-process support)
+    def sync_from_cache
+      @enabled = enabled
+      @session_id = session_id
+    end
+
+    # Ensure this process is subscribed to notifications if monitoring is enabled
+    def ensure_subscription_if_enabled
       return unless @enabled
+      ensure_subscription
+    end
 
-      # Skip if should be filtered
-      return if should_skip?(payload)
+    def ensure_subscription
+      return if @subscriber # Already subscribed
 
-      duration_ms = ((finished - started) * 1000).round(2)
-      sql = payload[:sql]
-      query_name = payload[:name]
-
-      # Extract source location
-      source_location = extract_source_location
-
-      # Build query entry
-      query_entry = {
-        type: "query",
-        session_id: @session_id,
-        sql: sql,
-        duration_ms: duration_ms,
-        name: query_name,
-        source_location: source_location,
-        timestamp: Time.current.iso8601
-      }
+      @subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |name, started, finished, unique_id, payload|
+        handle_sql_event(name, started, finished, unique_id, payload)
+      end
 
-      add_to_buffer(query_entry)
+      Rails.logger.debug("PgReports: Subscribed to sql.active_record in process #{Process.pid}") if defined?(Rails.logger)
+    end
+
+    def handle_sql_event(name, started, finished, unique_id, payload)
+      # Use local @enabled instead of enabled (which hits cache and may generate SQL,
+      # causing infinite recursion with database-backed cache stores like SolidCache)
+      return unless @enabled
+      return if @handling_event
+
+      @handling_event = true
+      begin
+        # Skip if should be filtered
+        return if should_skip?(payload)
+
+        duration_ms = ((finished - started) * 1000).round(2)
+        sql = payload[:sql]
+        query_name = payload[:name]
+
+        # Extract source location
+        source_location = extract_source_location
+
+        # Build query entry
+        query_entry = {
+          type: "query",
+          session_id: @session_id,
+          sql: sql,
+          duration_ms: duration_ms,
+          name: query_name,
+          source_location: source_location,
+          timestamp: Time.current.iso8601
+        }
+
+        add_to_buffer(query_entry)
+      ensure
+        @handling_event = false
+      end
     end
 
     def should_skip?(payload)
@@ -197,6 +290,10 @@ module PgReports
         # Exclude test paths
         next if path.include?("/spec/")
 
+        # IMPORTANT: Exclude query_monitor.rb itself to prevent false positives
+        # when gem is installed from RubyGems
+        next if path.include?("/query_monitor.rb")
+
         # Filter queries from pg_reports internal modules only:
         # - Installed gem: /gems/pg_reports-X.Y.Z/lib/
         # - Local gem: /pg_reports/lib/pg_reports/modules/
@@ -252,12 +349,12 @@ module PgReports
       end
     end
 
-    def write_session_marker(marker_type)
+    def write_session_marker(marker_type, sid = @session_id)
       return unless log_file_enabled?
 
       marker = {
         type: marker_type,
-        session_id: @session_id,
+        session_id: sid,
         timestamp: Time.current.iso8601
       }
 

data/lib/pg_reports/sql/indexes/fk_without_indexes.sql

@@ -0,0 +1,23 @@
+-- Foreign keys without indexes on the referencing (child) table
+-- Missing indexes cause sequential scans on DELETE/UPDATE of parent rows
+
+SELECT
+  c.conname AS constraint_name,
+  c.conrelid::regclass::text AS child_table,
+  a.attname AS child_column,
+  c.confrelid::regclass::text AS parent_table,
+  pa.attname AS parent_column,
+  pg_size_pretty(pg_relation_size(c.conrelid)) AS child_table_size,
+  ROUND(pg_relation_size(c.conrelid) / 1024.0 / 1024.0, 2) AS child_table_size_mb
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+JOIN pg_attribute pa ON pa.attrelid = c.confrelid AND pa.attnum = ANY(c.confkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1
+    FROM pg_index i
+    WHERE i.indrelid = c.conrelid
+      AND a.attnum = ANY(i.indkey)
+      AND i.indkey[0] = a.attnum
+  )
+ORDER BY pg_relation_size(c.conrelid) DESC;

data/lib/pg_reports/sql/indexes/index_correlation.sql

@@ -0,0 +1,27 @@
+-- Index correlation: how well physical row order matches index order
+-- Low correlation on frequently range-scanned columns means excessive random I/O
+
+SELECT
+  s.schemaname AS schema,
+  s.tablename AS table_name,
+  s.attname AS column_name,
+  i.indexrelname AS index_name,
+  ROUND(s.correlation::numeric, 4) AS correlation,
+  ABS(s.correlation) AS abs_correlation,
+  s.n_distinct,
+  pg_size_pretty(pg_relation_size(c.oid)) AS table_size,
+  ROUND(pg_relation_size(c.oid) / 1024.0 / 1024.0, 2) AS table_size_mb,
+  si.idx_scan
+FROM pg_stats s
+JOIN pg_class c ON c.relname = s.tablename
+  AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = s.schemaname)
+JOIN pg_index idx ON idx.indrelid = c.oid
+JOIN pg_attribute a ON a.attrelid = c.oid AND a.attname = s.attname
+  AND a.attnum = idx.indkey[0]
+JOIN pg_stat_user_indexes i ON i.indexrelid = idx.indexrelid
+JOIN pg_stat_user_indexes si ON si.indexrelid = idx.indexrelid
+WHERE s.schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND ABS(s.correlation) < 0.5
+  AND pg_relation_size(c.oid) > 10 * 1024 * 1024
+  AND si.idx_scan > 100
+ORDER BY ABS(s.correlation) ASC, pg_relation_size(c.oid) DESC;

data/lib/pg_reports/sql/indexes/inefficient_indexes.sql

@@ -0,0 +1,22 @@
+-- Inefficient index scans: indexes that are used but read far more entries than they fetch
+-- A high idx_tup_read / idx_tup_fetch ratio indicates the index column order
+-- does not match query predicates, forcing PostgreSQL to scan large index ranges
+-- Reference: https://www.datadoghq.com/blog/detect-inefficient-index-scans-with-dbm/
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  indexrelname AS index_name,
+  idx_scan,
+  idx_tup_read,
+  idx_tup_fetch,
+  ROUND((idx_tup_read::numeric / NULLIF(idx_tup_fetch, 0)), 1) AS read_to_fetch_ratio,
+  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
+  ROUND(pg_relation_size(indexrelid) / 1024.0 / 1024.0, 2) AS index_size_mb,
+  pg_get_indexdef(indexrelid) AS index_definition
+FROM pg_stat_user_indexes
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND idx_scan > 0
+  AND idx_tup_fetch > 0
+  AND (idx_tup_read::numeric / NULLIF(idx_tup_fetch, 0)) > 10
+ORDER BY (idx_tup_read::numeric / NULLIF(idx_tup_fetch, 0)) DESC;

data/lib/pg_reports/sql/queries/temp_file_queries.sql

@@ -0,0 +1,16 @@
+-- Queries that spill to disk via temporary files
+-- High temp file usage indicates insufficient work_mem for these queries
+
+SELECT
+  queryid,
+  LEFT(query, :max_query_length) AS query,
+  calls,
+  ROUND(temp_blks_written::numeric * 8 / 1024, 2) AS temp_mb_written,
+  ROUND(temp_blks_read::numeric * 8 / 1024, 2) AS temp_mb_read,
+  ROUND((total_exec_time / 1000)::numeric, 2) AS total_time_sec,
+  ROUND((mean_exec_time)::numeric, 2) AS mean_time_ms,
+  rows
+FROM pg_stat_statements
+WHERE temp_blks_written > 0
+  AND dbid = (SELECT oid FROM pg_database WHERE datname = current_database())
+ORDER BY temp_blks_written DESC;

data/lib/pg_reports/sql/system/checkpoint_stats.sql

@@ -0,0 +1,20 @@
+-- Checkpoint and background writer statistics (PostgreSQL 17+)
+-- Uses pg_stat_checkpointer (introduced in PG 17) + pg_stat_bgwriter for bgwriter-only stats
+
+SELECT
+  pg_stat_get_checkpointer_num_timed() AS checkpoints_timed,
+  pg_stat_get_checkpointer_num_requested() AS checkpoints_requested,
+  ROUND(pg_stat_get_checkpointer_write_time()::numeric / 1000, 2) AS checkpoint_write_time_sec,
+  ROUND(pg_stat_get_checkpointer_sync_time()::numeric / 1000, 2) AS checkpoint_sync_time_sec,
+  pg_stat_get_checkpointer_buffers_written() AS buffers_checkpoint,
+  pg_stat_get_bgwriter_buf_written_clean() AS buffers_clean,
+  pg_stat_get_bgwriter_maxwritten_clean() AS bgwriter_stops,
+  pg_stat_get_buf_alloc() AS buffers_alloc,
+  CASE
+    WHEN (pg_stat_get_checkpointer_num_timed() + pg_stat_get_checkpointer_num_requested()) > 0
+    THEN ROUND(
+      pg_stat_get_checkpointer_num_requested()::numeric /
+      (pg_stat_get_checkpointer_num_timed() + pg_stat_get_checkpointer_num_requested()) * 100, 1)
+    ELSE 0
+  END AS requested_pct,
+  pg_stat_get_bgwriter_stat_reset_time() AS stats_reset;

data/lib/pg_reports/sql/system/checkpoint_stats_legacy.sql

@@ -0,0 +1,19 @@
+-- Checkpoint and background writer statistics (PostgreSQL < 17)
+-- All stats from pg_stat_bgwriter (before checkpoint columns were moved out)
+
+SELECT
+  checkpoints_timed,
+  checkpoints_req AS checkpoints_requested,
+  ROUND(checkpoint_write_time::numeric / 1000, 2) AS checkpoint_write_time_sec,
+  ROUND(checkpoint_sync_time::numeric / 1000, 2) AS checkpoint_sync_time_sec,
+  buffers_checkpoint,
+  buffers_clean,
+  maxwritten_clean AS bgwriter_stops,
+  buffers_alloc,
+  CASE
+    WHEN (checkpoints_timed + checkpoints_req) > 0
+    THEN ROUND(checkpoints_req::numeric / (checkpoints_timed + checkpoints_req) * 100, 1)
+    ELSE 0
+  END AS requested_pct,
+  stats_reset
+FROM pg_stat_bgwriter;

data/lib/pg_reports/sql/system/wraparound_risk.sql

@@ -0,0 +1,21 @@
+-- Transaction ID wraparound risk
+-- When age(datfrozenxid) approaches 2 billion, PostgreSQL will shut down
+-- to prevent data corruption. Monitor this to trigger preventive VACUUM FREEZE.
+
+SELECT
+  d.datname AS database_name,
+  age(d.datfrozenxid) AS xid_age,
+  ROUND(age(d.datfrozenxid)::numeric / 2147483647 * 100, 2) AS pct_towards_wraparound,
+  2147483647 - age(d.datfrozenxid) AS remaining_xids,
+  current_setting('autovacuum_freeze_max_age')::bigint AS freeze_max_age,
+  CASE
+    WHEN age(d.datfrozenxid) > current_setting('autovacuum_freeze_max_age')::bigint
+    THEN 'CRITICAL - exceeds freeze_max_age'
+    WHEN age(d.datfrozenxid) > current_setting('autovacuum_freeze_max_age')::bigint * 0.75
+    THEN 'WARNING - approaching freeze_max_age'
+    ELSE 'OK'
+  END AS status,
+  pg_size_pretty(pg_database_size(d.datname)) AS database_size
+FROM pg_database d
+WHERE d.datallowconn = true
+ORDER BY age(d.datfrozenxid) DESC;

data/lib/pg_reports/sql/tables/tables_without_pk.sql

@@ -0,0 +1,20 @@
+-- Tables without primary keys
+-- Missing PKs break logical replication and make row identification unreliable
+
+SELECT
+  n.nspname AS schema,
+  c.relname AS table_name,
+  c.reltuples::bigint AS estimated_rows,
+  pg_size_pretty(pg_relation_size(c.oid)) AS table_size,
+  ROUND(pg_relation_size(c.oid) / 1024.0 / 1024.0, 2) AS table_size_mb
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND NOT EXISTS (
+    SELECT 1
+    FROM pg_index i
+    WHERE i.indrelid = c.oid
+      AND i.indisprimary
+  )
+ORDER BY pg_relation_size(c.oid) DESC;

data/lib/pg_reports/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgReports
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

data/lib/pg_reports.rb

@@ -6,6 +6,7 @@ require "active_record"
 
 require_relative "pg_reports/version"
 require_relative "pg_reports/error"
+require_relative "pg_reports/compatibility"
 require_relative "pg_reports/configuration"
 require_relative "pg_reports/sql_loader"
 require_relative "pg_reports/executor"
@@ -138,3 +139,7 @@ end
 
 # Generate YAML-based methods on load
 PgReports::ModuleGenerator.generate!
+
+# Check Ruby and Rails versions immediately (no DB needed)
+PgReports::Compatibility.check_ruby!
+PgReports::Compatibility.check_rails!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_reports
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Eldar Avatov
@@ -161,6 +161,7 @@ files:
 - config/routes.rb
 - lib/pg_reports.rb
 - lib/pg_reports/annotation_parser.rb
+- lib/pg_reports/compatibility.rb
 - lib/pg_reports/configuration.rb
 - lib/pg_reports/dashboard/reports_registry.rb
 - lib/pg_reports/definitions/connections/active_connections.yml
@@ -175,8 +176,11 @@ files:
 - lib/pg_reports/definitions/connections/pool_wait_times.yml
 - lib/pg_reports/definitions/indexes/bloated_indexes.yml
 - lib/pg_reports/definitions/indexes/duplicate_indexes.yml
+- lib/pg_reports/definitions/indexes/fk_without_indexes.yml
+- lib/pg_reports/definitions/indexes/index_correlation.yml
 - lib/pg_reports/definitions/indexes/index_sizes.yml
 - lib/pg_reports/definitions/indexes/index_usage.yml
+- lib/pg_reports/definitions/indexes/inefficient_indexes.yml
 - lib/pg_reports/definitions/indexes/invalid_indexes.yml
 - lib/pg_reports/definitions/indexes/missing_indexes.yml
 - lib/pg_reports/definitions/indexes/unused_indexes.yml
@@ -186,17 +190,20 @@ files:
 - lib/pg_reports/definitions/queries/low_cache_hit_queries.yml
 - lib/pg_reports/definitions/queries/missing_index_queries.yml
 - lib/pg_reports/definitions/queries/slow_queries.yml
+- lib/pg_reports/definitions/queries/temp_file_queries.yml
 - lib/pg_reports/definitions/system/activity_overview.yml
 - lib/pg_reports/definitions/system/cache_stats.yml
 - lib/pg_reports/definitions/system/database_sizes.yml
 - lib/pg_reports/definitions/system/extensions.yml
 - lib/pg_reports/definitions/system/settings.yml
+- lib/pg_reports/definitions/system/wraparound_risk.yml
 - lib/pg_reports/definitions/tables/bloated_tables.yml
 - lib/pg_reports/definitions/tables/cache_hit_ratios.yml
 - lib/pg_reports/definitions/tables/recently_modified.yml
 - lib/pg_reports/definitions/tables/row_counts.yml
 - lib/pg_reports/definitions/tables/seq_scans.yml
 - lib/pg_reports/definitions/tables/table_sizes.yml
+- lib/pg_reports/definitions/tables/tables_without_pk.yml
 - lib/pg_reports/definitions/tables/vacuum_needed.yml
 - lib/pg_reports/engine.rb
 - lib/pg_reports/error.rb
@@ -226,8 +233,11 @@ files:
 - lib/pg_reports/sql/connections/pool_wait_times.sql
 - lib/pg_reports/sql/indexes/bloated_indexes.sql
 - lib/pg_reports/sql/indexes/duplicate_indexes.sql
+- lib/pg_reports/sql/indexes/fk_without_indexes.sql
+- lib/pg_reports/sql/indexes/index_correlation.sql
 - lib/pg_reports/sql/indexes/index_sizes.sql
 - lib/pg_reports/sql/indexes/index_usage.sql
+- lib/pg_reports/sql/indexes/inefficient_indexes.sql
 - lib/pg_reports/sql/indexes/invalid_indexes.sql
 - lib/pg_reports/sql/indexes/missing_indexes.sql
 - lib/pg_reports/sql/indexes/unused_indexes.sql
@@ -237,20 +247,25 @@ files:
 - lib/pg_reports/sql/queries/low_cache_hit_queries.sql
 - lib/pg_reports/sql/queries/missing_index_queries.sql
 - lib/pg_reports/sql/queries/slow_queries.sql
+- lib/pg_reports/sql/queries/temp_file_queries.sql
 - lib/pg_reports/sql/schema_analysis/unique_indexes.sql
 - lib/pg_reports/sql/system/activity_overview.sql
 - lib/pg_reports/sql/system/cache_stats.sql
+- lib/pg_reports/sql/system/checkpoint_stats.sql
+- lib/pg_reports/sql/system/checkpoint_stats_legacy.sql
 - lib/pg_reports/sql/system/database_sizes.sql
 - lib/pg_reports/sql/system/databases_list.sql
 - lib/pg_reports/sql/system/extensions.sql
 - lib/pg_reports/sql/system/live_metrics.sql
 - lib/pg_reports/sql/system/settings.sql
+- lib/pg_reports/sql/system/wraparound_risk.sql
 - lib/pg_reports/sql/tables/bloated_tables.sql
 - lib/pg_reports/sql/tables/cache_hit_ratios.sql
 - lib/pg_reports/sql/tables/recently_modified.sql
 - lib/pg_reports/sql/tables/row_counts.sql
 - lib/pg_reports/sql/tables/seq_scans.sql
 - lib/pg_reports/sql/tables/table_sizes.sql
+- lib/pg_reports/sql/tables/tables_without_pk.sql
 - lib/pg_reports/sql/tables/vacuum_needed.sql
 - lib/pg_reports/sql_loader.rb
 - lib/pg_reports/telegram_sender.rb