pg_reports 0.5.4 → 0.6.1

data/lib/pg_reports/modules/schema_analysis.rb

@@ -64,6 +64,155 @@ module PgReports
         )
       end
 
+      # Polymorphic associations missing a composite (type, id) index
+      # @return [Report]
+      def polymorphic_without_index(**_params)
+        eager_load_models!
+        results = []
+
+        each_concrete_model do |model|
+          polymorphic_belongs_to(model).each do |assoc|
+            type_col = "#{assoc.name}_type"
+            id_col = "#{assoc.name}_id"
+
+            next unless model.column_names.include?(type_col) && model.column_names.include?(id_col)
+
+            # Expression/functional indexes report `columns` as a String — drop them; we only care about column-list indexes.
+            indexes = ActiveRecord::Base.connection.indexes(model.table_name).select { |i| i.columns.is_a?(Array) }
+            composite = indexes.find { |idx| (idx.columns & [type_col, id_col]).size == 2 }
+            next if composite
+
+            results << {
+              "schema" => "public",
+              "table_name" => model.table_name,
+              "model_name" => model.name,
+              "association" => assoc.name.to_s,
+              "type_column" => type_col,
+              "id_column" => id_col,
+              "coverage" => coverage_label(indexes, type_col, id_col),
+              "suggestion" => "add_index :#{model.table_name}, [:#{type_col}, :#{id_col}]"
+            }
+          end
+        end
+
+        Report.new(
+          title: "Polymorphic Associations Without Composite Index",
+          data: results,
+          columns: %w[table_name model_name association coverage suggestion]
+        )
+      end
+
+      # belongs_to ..., counter_cache: ... whose counter column is missing on the parent
+      # @return [Report]
+      def counter_cache_issues(**_params)
+        eager_load_models!
+        results = []
+
+        each_concrete_model do |model|
+          counter_belongs_to(model).each do |assoc|
+            counter_col = counter_cache_column_name(model, assoc)
+            parent = parent_class_for(assoc)
+            next unless parent && parent.table_exists?
+
+            unless parent.column_names.include?(counter_col)
+              results << {
+                "schema" => "public",
+                "child_model" => model.name,
+                "child_table" => model.table_name,
+                "parent_model" => parent.name,
+                "parent_table" => parent.table_name,
+                "expected_column" => counter_col,
+                "issue" => "missing_column",
+                "suggestion" => "add_column :#{parent.table_name}, :#{counter_col}, :integer, default: 0, null: false"
+              }
+            end
+          end
+        end
+
+        Report.new(
+          title: "Counter Cache Issues",
+          data: results,
+          columns: %w[child_model parent_model expected_column issue suggestion]
+        )
+      end
+
+      # Tables with soft-delete column but no model scope filtering it
+      # @return [Report]
+      def soft_delete_without_scope(**_params)
+        eager_load_models!
+        soft_delete_columns = %w[deleted_at discarded_at archived_at]
+        results = []
+
+        ActiveRecord::Base.connection.tables.each do |table|
+          next if internal_table?(table)
+
+          columns = ActiveRecord::Base.connection.columns(table).map(&:name)
+          soft_col = (columns & soft_delete_columns).first
+          next unless soft_col
+
+          model = find_model_for_table(table)
+          if model.nil?
+            results << {
+              "schema" => "public",
+              "table_name" => table,
+              "model_name" => "(no model)",
+              "soft_delete_column" => soft_col,
+              "status" => "no_model",
+              "suggestion" => "Create a model or filter manually in queries"
+            }
+            next
+          end
+
+          next if model_filters_soft_delete?(model, soft_col)
+
+          results << {
+            "schema" => "public",
+            "table_name" => table,
+            "model_name" => model.name,
+            "soft_delete_column" => soft_col,
+            "status" => "no_scope",
+            "suggestion" => "default_scope { where(#{soft_col}: nil) } or use discard/paranoia"
+          }
+        end
+
+        Report.new(
+          title: "Soft Delete Without Scope",
+          data: results,
+          columns: %w[table_name model_name soft_delete_column status suggestion]
+        )
+      end
+
+      # Tables with no corresponding Rails model (legacy or HABTM)
+      # @return [Report]
+      def orphan_tables(**_params)
+        eager_load_models!
+        results = []
+
+        ActiveRecord::Base.connection.tables.each do |table|
+          next if internal_table?(table)
+          next if find_model_for_table(table)
+
+          columns = ActiveRecord::Base.connection.columns(table)
+          row_count = approximate_row_count(table)
+
+          results << {
+            "schema" => "public",
+            "table_name" => table,
+            "row_count" => row_count,
+            "column_count" => columns.size,
+            "classification" => classify_orphan(columns)
+          }
+        end
+
+        results.sort_by! { |r| -r["row_count"].to_i }
+
+        Report.new(
+          title: "Orphan Tables (No Rails Model)",
+          data: results,
+          columns: %w[table_name row_count column_count classification]
+        )
+      end
+
       private
 
       def executor
@@ -125,7 +274,7 @@ module PgReports
         if column_names.size > 1
           # For composite indexes, we need to check if there's a validation with scope
           primary_column = column_names.first.to_sym
-          scope_columns = column_names[1..-1].map(&:to_sym)
+          scope_columns = column_names[1..].map(&:to_sym)
 
           has_composite = uniqueness_validators.any? do |validator|
             validator.attributes.include?(primary_column) &&
@@ -145,10 +294,120 @@ module PgReports
           "validates :#{column_names.first}, uniqueness: true"
         else
           primary = column_names.first
-          scopes = column_names[1..-1]
+          scopes = column_names[1..]
           "validates :#{primary}, uniqueness: { scope: #{scopes.inspect} }"
         end
       end
+
+      # Eager-load all application models so descendants is complete in development
+      def eager_load_models!
+        return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        Rails.application.eager_load!
+      rescue
+        # Best-effort; don't crash the report if a model fails to autoload
+      end
+
+      # Yield each concrete (non-abstract) ActiveRecord model that has a backing table
+      def each_concrete_model
+        ActiveRecord::Base.descendants.each do |model|
+          next if model.abstract_class?
+          next if model.name.nil?
+          next unless model.table_exists?
+          yield model
+        rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+          # Skip models whose table cannot be inspected
+        end
+      end
+
+      def polymorphic_belongs_to(model)
+        model.reflect_on_all_associations(:belongs_to).select { |a| a.options[:polymorphic] }
+      end
+
+      def counter_belongs_to(model)
+        model.reflect_on_all_associations(:belongs_to).reject { |a| a.options[:polymorphic] }.select { |a| a.options[:counter_cache] }
+      end
+
+      # Resolve the counter_cache column name from belongs_to options.
+      # counter_cache: true                                 → "<child_table_name>_count" (Rails default)
+      # counter_cache: :col                                 → "col"
+      # counter_cache: "col"                                → "col"
+      # counter_cache: { active: true, column: "col" }      → "col" (Rails 7.1+ form)
+      # counter_cache: { active: true }                     → falls back to default
+      def counter_cache_column_name(child_model, assoc)
+        opt = assoc.options[:counter_cache]
+        column = case opt
+        when true
+          nil
+        when Hash
+          opt[:column] || opt["column"]
+        else
+          opt
+        end
+        return column.to_s if column
+
+        "#{child_model.table_name.split(".").last}_count"
+      end
+
+      def parent_class_for(assoc)
+        assoc.klass
+      rescue NameError
+        nil
+      end
+
+      # Does the model's default scope filter out soft-deleted rows on the given column?
+      # Detects: paranoia, discard, hand-rolled default_scope referencing the column.
+      def model_filters_soft_delete?(model, column)
+        return true if model.respond_to?(:paranoid?) && model.paranoid?
+        return true if model.respond_to?(:discard_column) && model.discard_column.to_s == column
+
+        default_sql = model.all.to_sql
+        default_sql.include?(column)
+      rescue
+        false
+      end
+
+      def coverage_label(indexes, type_col, id_col)
+        column_list_indexes = indexes.select { |i| i.columns.is_a?(Array) }
+        type_indexed = column_list_indexes.any? { |i| i.columns.first == type_col }
+        id_indexed = column_list_indexes.any? { |i| i.columns.first == id_col }
+
+        if type_indexed && id_indexed
+          "type and id indexed separately"
+        elsif type_indexed
+          "only type indexed"
+        elsif id_indexed
+          "only id indexed"
+        else
+          "neither indexed"
+        end
+      end
+
+      def internal_table?(name)
+        %w[schema_migrations ar_internal_metadata].include?(name)
+      end
+
+      def approximate_row_count(table)
+        sql = "SELECT n_live_tup FROM pg_stat_user_tables WHERE relname = #{ActiveRecord::Base.connection.quote(table)}"
+        ActiveRecord::Base.connection.select_value(sql).to_i
+      rescue
+        0
+      end
+
+      # Classify an orphan table based on column shape.
+      # Two FK columns + nothing else (or just timestamps) → likely HABTM join table.
+      def classify_orphan(columns)
+        col_names = columns.map(&:name)
+        fk_cols = col_names.select { |c| c.end_with?("_id") }
+        non_meta = col_names - %w[id created_at updated_at]
+
+        if fk_cols.size == 2 && (non_meta - fk_cols).empty?
+          "join_table_candidate"
+        elsif fk_cols.size >= 2
+          "join_model_without_class"
+        else
+          "legacy"
+        end
+      end
     end
   end
 end

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,16 +16,20 @@ 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
-    end
+    attr_reader :enabled
 
-    def session_id
-      cache_read(CACHE_KEY_SESSION_ID)
-    end
+    attr_reader :session_id
 
     def start
       @mutex.synchronize do
@@ -37,7 +41,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 +60,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 +72,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 +85,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 +189,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 +212,38 @@ module PgReports
     end
 
     def handle_sql_event(name, started, finished, unique_id, payload)
-      return unless enabled
+      # 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
 
-      # 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)
+      @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 +345,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/report_definition.rb

@@ -120,33 +120,29 @@ module PgReports
       params = {}
 
       # Parameters from parameters section
-      if config["parameters"]
-        config["parameters"].each do |name, param_config|
-          params[name] = {
-            type: param_config["type"],
-            default: param_config["default"],
-            description: param_config["description"],
-            label: name.to_s.titleize
-          }
-        end
+      config["parameters"]&.each do |name, param_config|
+        params[name] = {
+          type: param_config["type"],
+          default: param_config["default"],
+          description: I18n.t("pg_reports.parameters.#{name}.description", default: param_config["description"]),
+          label: I18n.t("pg_reports.parameters.#{name}.label", default: name.to_s.titleize)
+        }
       end
 
       # Add threshold parameters from filters (config-based)
-      if config["filters"]
-        config["filters"].each do |filter|
-          if filter["value"]["source"] == "config"
-            config_key = filter["value"]["key"]
-            field_name = filter["field"]
-
-            params["#{field_name}_threshold"] = {
-              type: filter["cast"] || "integer",
-              default: PgReports.config.public_send(config_key),
-              description: "Override threshold for #{field_name}",
-              label: "#{field_name.titleize} Threshold",
-              current_config: PgReports.config.public_send(config_key),
-              is_threshold: true
-            }
-          end
+      config["filters"]&.each do |filter|
+        if filter["value"]["source"] == "config"
+          config_key = filter["value"]["key"]
+          field_name = filter["field"]
+
+          params["#{field_name}_threshold"] = {
+            type: filter["cast"] || "integer",
+            default: PgReports.config.public_send(config_key),
+            description: I18n.t("pg_reports.parameters.threshold_description", field: field_name),
+            label: I18n.t("pg_reports.parameters.threshold_label", field: field_name.titleize),
+            current_config: PgReports.config.public_send(config_key),
+            is_threshold: true
+          }
         end
       end
 

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;