pg_reports 0.5.4 → 0.6.0

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

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

@@ -16,15 +16,23 @@ module PgReports
       @subscriber = nil
       @mutex = Mutex.new
       @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
-      cache_read(CACHE_KEY_ENABLED) || false
+      @enabled
     end
 
     def session_id
-      cache_read(CACHE_KEY_SESSION_ID)
+      @session_id
     end
 
     def start
@@ -37,7 +45,11 @@ module PgReports
         new_session_id = SecureRandom.uuid
         @queries = []
 
-        # Store state in cache so all processes can see it
+        # Update local state first (used by event handler — no cache round-trip)
+        @enabled = true
+        @session_id = new_session_id
+
+        # 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)
 
@@ -52,6 +64,8 @@ module PgReports
         {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
@@ -62,7 +76,11 @@ module PgReports
           return {success: false, message: "Monitoring not active"}
         end
 
-        current_session_id = session_id
+        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
@@ -71,12 +89,12 @@ module PgReports
         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
 
-        # Clear state from cache
+        # Clear state from cache so other processes see it
         cache_delete(CACHE_KEY_ENABLED)
         cache_delete(CACHE_KEY_SESSION_ID)
 
@@ -175,9 +193,15 @@ module PgReports
       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
+      return unless @enabled
       ensure_subscription
     end
 
@@ -192,30 +216,38 @@ module PgReports
     end
 
     def handle_sql_event(name, started, finished, unique_id, payload)
-      return unless enabled
-
-      # Skip if should be filtered
-      return if should_skip?(payload)
-
-      duration_ms = ((finished - started) * 1000).round(2)
-      sql = payload[:sql]
-      query_name = payload[:name]
+      # 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
 
-      # 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)
+      @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)
@@ -317,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;