pg_reports 0.5.4 → 0.6.1

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,11 +179,56 @@ 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: {
           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
 
@@ -178,6 +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"},
             all_queries: {name: "All Queries", description: "All query statistics"}
           }
         },
@@ -190,8 +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"},
             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"},
+            index_correlation: {name: "Index Correlation", description: "Low physical correlation indexes"},
             index_sizes: {name: "Index Sizes", description: "Index disk usage"}
           }
         },
@@ -206,7 +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"},
-            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: {
@@ -235,6 +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"},
+            checkpoint_stats: {name: "Checkpoint Stats", description: "Checkpoint and bgwriter statistics"},
             cache_stats: {name: "Cache Stats", description: "Database cache statistics"}
           }
         },
@@ -243,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
@@ -272,6 +378,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/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/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/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/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/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/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