pg_reports 0.1.0

data/lib/pg_reports/dashboard/reports_registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Dashboard
+    # Registry of all available reports for the dashboard
+    module ReportsRegistry
+      REPORTS = {
+        queries: {
+          name: "Queries",
+          icon: "⚡",
+          color: "#6366f1",
+          reports: {
+            slow_queries: {name: "Slow Queries", description: "Queries with high mean execution time"},
+            heavy_queries: {name: "Heavy Queries", description: "Most frequently called queries"},
+            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"},
+            all_queries: {name: "All Queries", description: "All query statistics"}
+          }
+        },
+        indexes: {
+          name: "Indexes",
+          icon: "📇",
+          color: "#10b981",
+          reports: {
+            unused_indexes: {name: "Unused Indexes", description: "Indexes rarely or never scanned"},
+            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"},
+            index_usage: {name: "Index Usage", description: "Index scan statistics"},
+            bloated_indexes: {name: "Bloated Indexes", description: "Indexes with high bloat"},
+            index_sizes: {name: "Index Sizes", description: "Index disk usage"}
+          }
+        },
+        tables: {
+          name: "Tables",
+          icon: "📊",
+          color: "#f59e0b",
+          reports: {
+            table_sizes: {name: "Table Sizes", description: "Table disk usage"},
+            bloated_tables: {name: "Bloated Tables", description: "Tables with high dead tuple ratio"},
+            vacuum_needed: {name: "Vacuum Needed", description: "Tables needing vacuum"},
+            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"}
+          }
+        },
+        connections: {
+          name: "Connections",
+          icon: "🔌",
+          color: "#ec4899",
+          reports: {
+            active_connections: {name: "Active Connections", description: "Current database connections"},
+            connection_stats: {name: "Connection Stats", description: "Connection statistics by state"},
+            long_running_queries: {name: "Long Running", description: "Queries running for extended period"},
+            blocking_queries: {name: "Blocking Queries", description: "Queries blocking others"},
+            locks: {name: "Locks", description: "Current database locks"},
+            idle_connections: {name: "Idle Connections", description: "Idle connections"}
+          }
+        },
+        system: {
+          name: "System",
+          icon: "🖥️",
+          color: "#8b5cf6",
+          reports: {
+            database_sizes: {name: "Database Sizes", description: "Size of all databases"},
+            settings: {name: "Settings", description: "PostgreSQL configuration"},
+            extensions: {name: "Extensions", description: "Installed extensions"},
+            activity_overview: {name: "Activity Overview", description: "Current activity summary"},
+            cache_stats: {name: "Cache Stats", description: "Database cache statistics"}
+          }
+        }
+      }.freeze
+
+      def self.all
+        REPORTS
+      end
+
+      def self.find(category, report)
+        REPORTS.dig(category.to_sym, :reports, report.to_sym)
+      end
+
+      def self.category(category)
+        REPORTS[category.to_sym]
+      end
+    end
+  end
+end

data/lib/pg_reports/engine.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PgReports
+  class Engine < ::Rails::Engine
+    isolate_namespace PgReports
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "pg_reports.assets" do |_app|
+      # Assets are inline in views, no precompilation needed
+    end
+
+    initializer "pg_reports.append_routes" do |app|
+      # Allow mounting at custom path
+      app.routes.append do
+        # Routes are mounted by the user in their routes.rb
+      end
+    end
+  end
+end

data/lib/pg_reports/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PgReports
+  # Base error class for PgReports
+  class Error < StandardError; end
+
+  # Raised when Telegram is not configured
+  class TelegramNotConfiguredError < Error; end
+
+  # Raised when SQL file is not found
+  class SqlFileNotFoundError < Error; end
+
+  # Raised when database connection fails
+  class ConnectionError < Error; end
+end

data/lib/pg_reports/executor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PgReports
+  # Executes SQL queries and returns results
+  class Executor
+    def initialize(connection: nil)
+      @connection = connection || PgReports.config.connection
+    end
+
+    # Execute SQL from a file and return results as array of hashes
+    def execute_from_file(category, name, **params)
+      sql = SqlLoader.load(category, name)
+      execute(sql, **params)
+    end
+
+    # Execute raw SQL and return results as array of hashes
+    def execute(sql, **params)
+      processed_sql = interpolate_params(sql, params)
+      result = @connection.exec_query(processed_sql)
+      result.to_a
+    end
+
+    private
+
+    # Simple parameter interpolation for SQL
+    # Replaces :param_name with quoted values
+    def interpolate_params(sql, params)
+      return sql if params.empty?
+
+      params.reduce(sql) do |query, (key, value)|
+        quoted_value = quote_value(value)
+        query.gsub(":#{key}", quoted_value)
+      end
+    end
+
+    def quote_value(value)
+      case value
+      when nil
+        "NULL"
+      when Integer, Float
+        value.to_s
+      when String
+        @connection.quote(value)
+      when Array
+        "(#{value.map { |v| quote_value(v) }.join(", ")})"
+      else
+        @connection.quote(value.to_s)
+      end
+    end
+  end
+end

data/lib/pg_reports/modules/connections.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Modules
+    # Connection and lock analysis module
+    module Connections
+      extend self
+
+      # Active connections
+      # @return [Report] Report with active connections
+      def active_connections
+        data = executor.execute_from_file(:connections, :active_connections)
+
+        Report.new(
+          title: "Active Connections",
+          data: data,
+          columns: %w[pid database username application state query_start state_change query]
+        )
+      end
+
+      # Connection statistics by state
+      # @return [Report] Report with connection counts by state
+      def connection_stats
+        data = executor.execute_from_file(:connections, :connection_stats)
+
+        Report.new(
+          title: "Connection Statistics",
+          data: data,
+          columns: %w[database state count]
+        )
+      end
+
+      # Long running queries
+      # @return [Report] Report with long running queries
+      def long_running_queries(min_duration_seconds: 60)
+        data = executor.execute_from_file(:connections, :long_running_queries)
+
+        filtered = data.select { |row| row["duration_seconds"].to_f >= min_duration_seconds }
+
+        Report.new(
+          title: "Long Running Queries (>= #{min_duration_seconds}s)",
+          data: filtered,
+          columns: %w[pid database username duration_seconds state query]
+        )
+      end
+
+      # Blocking queries - queries that are blocking others
+      # @return [Report] Report with blocking queries
+      def blocking_queries
+        data = executor.execute_from_file(:connections, :blocking_queries)
+
+        Report.new(
+          title: "Blocking Queries",
+          data: data,
+          columns: %w[blocked_pid blocking_pid blocked_query blocking_query blocked_duration]
+        )
+      end
+
+      # Lock statistics
+      # @return [Report] Report with lock statistics
+      def locks
+        data = executor.execute_from_file(:connections, :locks)
+
+        Report.new(
+          title: "Current Locks",
+          data: data,
+          columns: %w[pid database relation locktype mode granted waiting]
+        )
+      end
+
+      # Idle connections
+      # @return [Report] Report with idle connections
+      def idle_connections
+        data = executor.execute_from_file(:connections, :idle_connections)
+
+        Report.new(
+          title: "Idle Connections",
+          data: data,
+          columns: %w[pid database username application idle_duration state_change]
+        )
+      end
+
+      # Kill a specific backend process
+      # @param pid [Integer] Process ID to terminate
+      # @return [Boolean] Success status
+      def kill_connection(pid)
+        result = executor.execute("SELECT pg_terminate_backend(:pid)", pid: pid)
+        result.first&.fetch("pg_terminate_backend", false) || false
+      end
+
+      # Cancel a specific query (softer than kill)
+      # @param pid [Integer] Process ID to cancel
+      # @return [Boolean] Success status
+      def cancel_query(pid)
+        result = executor.execute("SELECT pg_cancel_backend(:pid)", pid: pid)
+        result.first&.fetch("pg_cancel_backend", false) || false
+      end
+
+      private
+
+      def executor
+        @executor ||= Executor.new
+      end
+    end
+  end
+end

data/lib/pg_reports/modules/indexes.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Modules
+    # Index analysis module
+    module Indexes
+      extend self
+
+      # Unused indexes - indexes that are rarely or never scanned
+      # @return [Report] Report with unused indexes
+      def unused_indexes(limit: 50)
+        data = executor.execute_from_file(:indexes, :unused_indexes)
+        threshold = PgReports.config.unused_index_threshold_scans
+
+        filtered = data.select { |row| row["idx_scan"].to_i <= threshold }
+          .first(limit)
+
+        Report.new(
+          title: "Unused Indexes (scans <= #{threshold})",
+          data: filtered,
+          columns: %w[schema table_name index_name idx_scan index_size_mb]
+        )
+      end
+
+      # Duplicate indexes - indexes that may be redundant
+      # @return [Report] Report with duplicate indexes
+      def duplicate_indexes
+        data = executor.execute_from_file(:indexes, :duplicate_indexes)
+
+        Report.new(
+          title: "Duplicate Indexes",
+          data: data,
+          columns: %w[table_name index_name duplicate_of index_size_mb]
+        )
+      end
+
+      # Invalid indexes - indexes that are not valid (e.g., failed to build)
+      # @return [Report] Report with invalid indexes
+      def invalid_indexes
+        data = executor.execute_from_file(:indexes, :invalid_indexes)
+
+        Report.new(
+          title: "Invalid Indexes",
+          data: data,
+          columns: %w[schema table_name index_name index_definition]
+        )
+      end
+
+      # Missing indexes - tables with high sequential scans
+      # @return [Report] Report suggesting missing indexes
+      def missing_indexes(limit: 20)
+        data = executor.execute_from_file(:indexes, :missing_indexes)
+          .first(limit)
+
+        Report.new(
+          title: "Tables Potentially Missing Indexes",
+          data: data,
+          columns: %w[schema table_name seq_scan seq_tup_read idx_scan table_size_mb]
+        )
+      end
+
+      # Index usage statistics
+      # @return [Report] Report with index usage statistics
+      def index_usage(limit: 50)
+        data = executor.execute_from_file(:indexes, :index_usage)
+          .first(limit)
+
+        Report.new(
+          title: "Index Usage Statistics",
+          data: data,
+          columns: %w[schema table_name index_name idx_scan idx_tup_read index_size_mb]
+        )
+      end
+
+      # Bloated indexes - indexes with high bloat
+      # @return [Report] Report with bloated indexes
+      def bloated_indexes(limit: 20)
+        data = executor.execute_from_file(:indexes, :bloated_indexes)
+        threshold = PgReports.config.bloat_threshold_percent
+
+        filtered = data.select { |row| row["bloat_percent"].to_f >= threshold }
+          .first(limit)
+
+        Report.new(
+          title: "Bloated Indexes (bloat >= #{threshold}%)",
+          data: filtered,
+          columns: %w[schema table_name index_name index_size_mb bloat_size_mb bloat_percent]
+        )
+      end
+
+      # Index sizes
+      # @return [Report] Report with index sizes
+      def index_sizes(limit: 50)
+        data = executor.execute_from_file(:indexes, :index_sizes)
+          .first(limit)
+
+        Report.new(
+          title: "Index Sizes (top #{limit})",
+          data: data,
+          columns: %w[schema table_name index_name index_size_mb]
+        )
+      end
+
+      private
+
+      def executor
+        @executor ||= Executor.new
+      end
+    end
+  end
+end

data/lib/pg_reports/modules/queries.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Modules
+    # Query analysis module - analyzes pg_stat_statements data
+    module Queries
+      extend self
+
+      # Slow queries - queries with high mean execution time
+      # @return [Report] Report with slow queries
+      def slow_queries(limit: 20)
+        data = executor.execute_from_file(:queries, :slow_queries)
+        threshold = PgReports.config.slow_query_threshold_ms
+
+        filtered = data.select { |row| row["mean_time_ms"].to_f >= threshold }
+          .first(limit)
+
+        enriched = enrich_with_annotations(filtered)
+
+        Report.new(
+          title: "Slow Queries (mean time >= #{threshold}ms)",
+          data: enriched,
+          columns: %w[query source calls mean_time_ms total_time_ms rows_per_call]
+        )
+      end
+
+      # Heavy queries - queries called most frequently
+      # @return [Report] Report with heavy queries
+      def heavy_queries(limit: 20)
+        data = executor.execute_from_file(:queries, :heavy_queries)
+        threshold = PgReports.config.heavy_query_threshold_calls
+
+        filtered = data.select { |row| row["calls"].to_i >= threshold }
+          .first(limit)
+
+        enriched = enrich_with_annotations(filtered)
+
+        Report.new(
+          title: "Heavy Queries (calls >= #{threshold})",
+          data: enriched,
+          columns: %w[query source calls total_time_ms mean_time_ms cache_hit_ratio]
+        )
+      end
+
+      # Expensive queries - queries consuming most total time
+      # @return [Report] Report with expensive queries
+      def expensive_queries(limit: 20)
+        data = executor.execute_from_file(:queries, :expensive_queries)
+        threshold = PgReports.config.expensive_query_threshold_ms
+
+        filtered = data.select { |row| row["total_time_ms"].to_f >= threshold }
+          .first(limit)
+
+        enriched = enrich_with_annotations(filtered)
+
+        Report.new(
+          title: "Expensive Queries (total time >= #{threshold}ms)",
+          data: enriched,
+          columns: %w[query source calls total_time_ms percent_of_total mean_time_ms]
+        )
+      end
+
+      # Queries missing indexes - sequential scans on large tables
+      # @return [Report] Report with queries likely missing indexes
+      def missing_index_queries(limit: 20)
+        data = executor.execute_from_file(:queries, :missing_index_queries)
+          .first(limit)
+
+        enriched = enrich_with_annotations(data)
+
+        Report.new(
+          title: "Queries Potentially Missing Indexes",
+          data: enriched,
+          columns: %w[query source calls seq_scan_count rows_examined table_name]
+        )
+      end
+
+      # Queries with low cache hit ratio
+      # @return [Report] Report with queries having poor cache utilization
+      def low_cache_hit_queries(limit: 20, min_calls: 100)
+        data = executor.execute_from_file(:queries, :low_cache_hit_queries)
+
+        filtered = data.select { |row| row["calls"].to_i >= min_calls }
+          .first(limit)
+
+        enriched = enrich_with_annotations(filtered)
+
+        Report.new(
+          title: "Queries with Low Cache Hit Ratio (min #{min_calls} calls)",
+          data: enriched,
+          columns: %w[query source calls cache_hit_ratio shared_blks_hit shared_blks_read]
+        )
+      end
+
+      # All query statistics ordered by total time
+      # @return [Report] Report with all query statistics
+      def all_queries(limit: 50)
+        data = executor.execute_from_file(:queries, :all_queries)
+          .first(limit)
+
+        enriched = enrich_with_annotations(data)
+
+        Report.new(
+          title: "All Query Statistics (top #{limit})",
+          data: enriched,
+          columns: %w[query source calls total_time_ms mean_time_ms rows]
+        )
+      end
+
+      # Reset pg_stat_statements statistics
+      def reset_statistics!
+        executor.execute("SELECT pg_stat_statements_reset()")
+        true
+      end
+
+      private
+
+      def executor
+        @executor ||= Executor.new
+      end
+
+      # Enrich query data with parsed annotations (Marginalia, Rails QueryLogs, etc.)
+      def enrich_with_annotations(data)
+        data.map do |row|
+          query = row["query"].to_s
+          annotation = AnnotationParser.parse(query)
+
+          if annotation.any?
+            row.merge(
+              "source" => AnnotationParser.format_for_display(annotation),
+              "query" => AnnotationParser.strip_annotations(query)
+            )
+          else
+            row.merge("source" => nil)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pg_reports/modules/system.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Modules
+    # System-level database statistics
+    module System
+      extend self
+
+      # Database sizes
+      # @return [Report] Report with database sizes
+      def database_sizes
+        data = executor.execute_from_file(:system, :database_sizes)
+
+        Report.new(
+          title: "Database Sizes",
+          data: data,
+          columns: %w[database size_mb size_pretty]
+        )
+      end
+
+      # PostgreSQL settings
+      # @return [Report] Report with important PostgreSQL settings
+      def settings
+        data = executor.execute_from_file(:system, :settings)
+
+        Report.new(
+          title: "PostgreSQL Settings",
+          data: data,
+          columns: %w[name setting unit category description]
+        )
+      end
+
+      # Extension information
+      # @return [Report] Report with installed extensions
+      def extensions
+        data = executor.execute_from_file(:system, :extensions)
+
+        Report.new(
+          title: "Installed Extensions",
+          data: data,
+          columns: %w[name version schema description]
+        )
+      end
+
+      # Database activity overview
+      # @return [Report] Report with current activity
+      def activity_overview
+        data = executor.execute_from_file(:system, :activity_overview)
+
+        Report.new(
+          title: "Database Activity Overview",
+          data: data,
+          columns: %w[metric value]
+        )
+      end
+
+      # Cache hit ratio for the entire database
+      # @return [Report] Report with cache statistics
+      def cache_stats
+        data = executor.execute_from_file(:system, :cache_stats)
+
+        Report.new(
+          title: "Database Cache Statistics",
+          data: data,
+          columns: %w[database heap_hit_ratio index_hit_ratio]
+        )
+      end
+
+      # pg_stat_statements availability check
+      # @return [Boolean] Whether pg_stat_statements is available
+      def pg_stat_statements_available?
+        result = executor.execute(<<~SQL)
+          SELECT EXISTS (
+            SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements'
+          ) AS available
+        SQL
+        result.first&.fetch("available", false) || false
+      end
+
+      # Check if pg_stat_statements is in shared_preload_libraries
+      # @return [Boolean] Whether pg_stat_statements is preloaded
+      def pg_stat_statements_preloaded?
+        result = executor.execute(<<~SQL)
+          SELECT setting FROM pg_settings WHERE name = 'shared_preload_libraries'
+        SQL
+        setting = result.first&.fetch("setting", "") || ""
+        setting.include?("pg_stat_statements")
+      end
+
+      # Get pg_stat_statements status details
+      # @return [Hash] Status information
+      def pg_stat_statements_status
+        {
+          extension_installed: pg_stat_statements_available?,
+          preloaded: pg_stat_statements_preloaded?,
+          ready: pg_stat_statements_available? && pg_stat_statements_preloaded?
+        }
+      end
+
+      # Enable pg_stat_statements extension
+      # Tries to create extension, returns helpful error if it fails
+      # @return [Hash] Result with success status and message
+      def enable_pg_stat_statements!
+        # Check if already enabled
+        if pg_stat_statements_available?
+          return {success: true, message: "pg_stat_statements is already enabled"}
+        end
+
+        # Try to create extension
+        begin
+          executor.execute("CREATE EXTENSION IF NOT EXISTS pg_stat_statements")
+
+          # Verify it worked
+          if pg_stat_statements_available?
+            {success: true, message: "pg_stat_statements extension created successfully"}
+          else
+            {
+              success: false,
+              message: "Extension created but not working. Check shared_preload_libraries in postgresql.conf",
+              requires_restart: true
+            }
+          end
+        rescue => e
+          error_message = e.message
+
+          # Provide helpful message for common errors
+          if error_message.include?("could not open extension control file") ||
+              error_message.include?("extension \"pg_stat_statements\" is not available")
+            {
+              success: false,
+              message: "pg_stat_statements is not installed. Add to postgresql.conf: " \
+                       "shared_preload_libraries = 'pg_stat_statements' and restart PostgreSQL.",
+              requires_restart: true
+            }
+          else
+            {success: false, message: "Failed to create extension: #{error_message}"}
+          end
+        end
+      end
+
+      private
+
+      def executor
+        @executor ||= Executor.new
+      end
+    end
+  end
+end