pg_reports 0.6.0 → 0.6.2

data/lib/pg_reports/dashboard/reports_registry.rb

@@ -192,6 +192,43 @@ module PgReports
         missing_validations: {
           thresholds: {},
           problem_fields: []
+        },
+        unused_columns: {
+          thresholds: {},
+          problem_fields: ["column_name"]
+        },
+        always_null_columns: {
+          thresholds: {null_pct: {warning: 99, critical: 100}},
+          problem_fields: ["column_name", "null_pct"]
+        },
+        polymorphic_without_index: {
+          thresholds: {},
+          problem_fields: ["coverage"]
+        },
+        counter_cache_issues: {
+          thresholds: {},
+          problem_fields: ["issue", "expected_column"]
+        },
+        soft_delete_without_scope: {
+          thresholds: {},
+          problem_fields: ["status", "soft_delete_column"]
+        },
+        orphan_tables: {
+          thresholds: {},
+          problem_fields: ["classification"]
+        },
+
+        # === TABLES (extra) ===
+        update_hotspots: {
+          thresholds: {
+            updates_per_row: {warning: 10, critical: 100},
+            hot_update_pct: {warning: 50, critical: 20, inverted: true}
+          },
+          problem_fields: ["updates_per_row", "hot_update_pct"]
+        },
+        unused_tables: {
+          thresholds: {total_size_mb: {warning: 10, critical: 100}},
+          problem_fields: ["table_name"]
         }
       }.freeze
 
@@ -206,7 +243,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},
+            temp_file_queries: {name: "Temp File Queries", description: "Queries spilling to disk"},
             all_queries: {name: "All Queries", description: "All query statistics"}
           }
         },
@@ -219,11 +256,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},
+            inefficient_indexes: {name: "Inefficient Indexes", description: "Indexes with high read-to-fetch ratio"},
             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},
+            fk_without_indexes: {name: "FK Without Indexes", description: "Foreign keys missing indexes"},
+            index_correlation: {name: "Index Correlation", description: "Low physical correlation indexes"},
             index_sizes: {name: "Index Sizes", description: "Index disk usage"}
           }
         },
@@ -238,8 +275,10 @@ 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"}
+            tables_without_pk: {name: "No Primary Key", description: "Tables missing primary keys"},
+            recently_modified: {name: "Recently Modified", description: "Tables with recent activity"},
+            update_hotspots: {name: "Update Hotspots", description: "Same rows or indexed columns updated repeatedly", new: true},
+            unused_tables: {name: "Unused Tables", description: "Tables never queried since the last stats reset", new: true}
           }
         },
         connections: {
@@ -268,8 +307,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},
+            wraparound_risk: {name: "Wraparound Risk", description: "Transaction ID wraparound proximity"},
+            checkpoint_stats: {name: "Checkpoint Stats", description: "Checkpoint and bgwriter statistics"},
             cache_stats: {name: "Cache Stats", description: "Database cache statistics"}
           }
         },
@@ -278,21 +317,53 @@ module PgReports
           icon: "🔍",
           color: "#06b6d4",
           reports: {
-            missing_validations: {name: "Missing Validations", description: "Unique indexes without model validations"}
+            missing_validations: {name: "Missing Validations", description: "Unique indexes without model validations"},
+            unused_columns: {name: "Unused Columns", description: "Columns that have only ever held a single value", new: true},
+            always_null_columns: {name: "Always-NULL Columns", description: "Nullable columns that contain only NULL", new: true},
+            polymorphic_without_index: {name: "Polymorphic Without Index", description: "Polymorphic associations missing composite index", new: true},
+            counter_cache_issues: {name: "Counter Cache Issues", description: "counter_cache declarations whose target column is missing", new: true},
+            soft_delete_without_scope: {name: "Soft Delete Without Scope", description: "Soft-delete columns with no model scope filtering them", new: true},
+            orphan_tables: {name: "Orphan Tables", description: "DB tables without a corresponding Rails model", new: true}
           }
         }
       }.freeze
 
       def self.all
-        REPORTS
+        REPORTS.each_with_object({}) do |(cat_key, cat), result|
+          result[cat_key] = localized_category(cat_key, cat)
+        end
       end
 
       def self.find(category, report)
-        REPORTS.dig(category.to_sym, :reports, report.to_sym)
+        rep = REPORTS.dig(category.to_sym, :reports, report.to_sym)
+        return nil unless rep
+
+        localized_report(report.to_sym, rep)
       end
 
       def self.category(category)
-        REPORTS[category.to_sym]
+        cat = REPORTS[category.to_sym]
+        return nil unless cat
+
+        localized_category(category.to_sym, cat)
+      end
+
+      # Build category hash with localized name and report names
+      def self.localized_category(cat_key, cat)
+        cat.merge(
+          name: I18n.t("pg_reports.categories.#{cat_key}", default: cat[:name]),
+          reports: cat[:reports].each_with_object({}) do |(rep_key, rep), reports|
+            reports[rep_key] = localized_report(rep_key, rep)
+          end
+        )
+      end
+
+      # Build report hash with localized name and description
+      def self.localized_report(rep_key, rep)
+        rep.merge(
+          name: I18n.t("pg_reports.reports.#{rep_key}.name", default: rep[:name]),
+          description: I18n.t("pg_reports.reports.#{rep_key}.description", default: rep[:description])
+        )
       end
 
       # Returns full documentation for a report including I18n translations

data/lib/pg_reports/definitions/schema_analysis/always_null_columns.yml

@@ -0,0 +1,31 @@
+# Columns where 100% of rows are NULL
+# Strong indicator the application no longer populates these fields
+
+report:
+  name: always_null_columns
+  module: schema_analysis
+  description: "Nullable columns that contain only NULL values"
+
+  sql:
+    category: schema_analysis
+    file: always_null_columns
+
+  title: "Always-NULL Columns"
+
+  columns:
+    - schema
+    - table_name
+    - column_name
+    - data_type
+    - null_pct
+    - column_default
+    - estimated_rows
+
+  parameters:
+    limit:
+      type: integer
+      default: 100
+      description: "Maximum number of results"
+
+  problem_explanations:
+    column_name: always_null_column

data/lib/pg_reports/definitions/schema_analysis/unused_columns.yml

@@ -0,0 +1,32 @@
+# Columns whose value has never changed since table creation
+# Detects dead fields that the application code no longer touches
+
+report:
+  name: unused_columns
+  module: schema_analysis
+  description: "Columns that appear to have never been updated (still hold a single value)"
+
+  sql:
+    category: schema_analysis
+    file: unused_columns
+
+  title: "Unused Columns"
+
+  columns:
+    - schema
+    - table_name
+    - column_name
+    - data_type
+    - sole_value
+    - column_default
+    - null_pct
+    - estimated_rows
+
+  parameters:
+    limit:
+      type: integer
+      default: 100
+      description: "Maximum number of results"
+
+  problem_explanations:
+    column_name: unused_column

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

@@ -0,0 +1,30 @@
+# Tables never read since the last stats reset
+# Zero seq_scan and zero idx_scan -- code does not query them
+
+report:
+  name: unused_tables
+  module: tables
+  description: "Tables with zero read activity since the last statistics reset"
+
+  sql:
+    category: tables
+    file: unused_tables
+
+  title: "Unused Tables"
+
+  columns:
+    - schema
+    - table_name
+    - live_rows
+    - total_size_mb
+    - last_analyzed
+    - db_stats_since
+
+  parameters:
+    limit:
+      type: integer
+      default: 50
+      description: "Maximum number of results"
+
+  problem_explanations:
+    table_name: unused_table

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

@@ -0,0 +1,32 @@
+# Tables with disproportionately heavy update activity
+# High updates_per_row signals same rows updated repeatedly; low hot_update_pct signals indexed columns are being updated
+
+report:
+  name: update_hotspots
+  module: tables
+  description: "Tables with high update-to-row ratio or poor HOT update efficiency"
+
+  sql:
+    category: tables
+    file: update_hotspots
+
+  title: "Update Hotspots"
+
+  columns:
+    - schema
+    - table_name
+    - live_rows
+    - updates
+    - updates_per_row
+    - hot_update_pct
+    - dead_rows
+
+  parameters:
+    limit:
+      type: integer
+      default: 30
+      description: "Maximum number of results"
+
+  problem_explanations:
+    updates_per_row: hot_rows
+    hot_update_pct: low_hot_update

data/lib/pg_reports/module_generator.rb

@@ -17,7 +17,8 @@ module PgReports
     private
 
     def self.get_module(module_name)
-      PgReports::Modules.const_get(module_name.capitalize)
+      const_name = module_name.to_s.split("_").map(&:capitalize).join
+      PgReports::Modules.const_get(const_name)
     rescue NameError
       # Module doesn't exist, skip it
       # We don't auto-create modules to avoid conflicts

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

@@ -139,7 +139,7 @@ module PgReports
       # 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
+        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
 
@@ -147,8 +147,8 @@ module PgReports
           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]
+            checkpoint_sync_time_sec buffers_checkpoint buffers_clean
+            bgwriter_stops buffers_alloc requested_pct stats_reset]
         )
       end
 

data/lib/pg_reports/query_monitor.rb

@@ -27,13 +27,9 @@ module PgReports
       ensure_subscription_if_enabled
     end
 
-    def enabled
-      @enabled
-    end
+    attr_reader :enabled
 
-    def session_id
-      @session_id
-    end
+    attr_reader :session_id
 
     def start
       @mutex.synchronize do

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