pg_reports 0.1.0

data/lib/pg_reports/modules/tables.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Modules
+    # Table analysis module
+    module Tables
+      extend self
+
+      # Table sizes including indexes
+      # @return [Report] Report with table sizes
+      def table_sizes(limit: 50)
+        data = executor.execute_from_file(:tables, :table_sizes)
+          .first(limit)
+
+        Report.new(
+          title: "Table Sizes (top #{limit})",
+          data: data,
+          columns: %w[schema table_name table_size_mb index_size_mb total_size_mb row_count]
+        )
+      end
+
+      # Bloated tables - tables with high dead tuple ratio
+      # @return [Report] Report with bloated tables
+      def bloated_tables(limit: 20)
+        data = executor.execute_from_file(:tables, :bloated_tables)
+        threshold = PgReports.config.bloat_threshold_percent
+
+        filtered = data.select { |row| row["bloat_percent"].to_f >= threshold }
+          .first(limit)
+
+        Report.new(
+          title: "Bloated Tables (bloat >= #{threshold}%)",
+          data: filtered,
+          columns: %w[schema table_name live_rows dead_rows bloat_percent table_size_mb]
+        )
+      end
+
+      # Tables needing vacuum - high dead rows count
+      # @return [Report] Report with tables needing vacuum
+      def vacuum_needed(limit: 20)
+        data = executor.execute_from_file(:tables, :vacuum_needed)
+        threshold = PgReports.config.dead_rows_threshold
+
+        filtered = data.select { |row| row["n_dead_tup"].to_i >= threshold }
+          .first(limit)
+
+        Report.new(
+          title: "Tables Needing Vacuum (dead rows >= #{threshold})",
+          data: filtered,
+          columns: %w[schema table_name n_live_tup n_dead_tup last_vacuum last_autovacuum]
+        )
+      end
+
+      # Table row counts
+      # @return [Report] Report with table row counts
+      def row_counts(limit: 50)
+        data = executor.execute_from_file(:tables, :row_counts)
+          .first(limit)
+
+        Report.new(
+          title: "Table Row Counts (top #{limit})",
+          data: data,
+          columns: %w[schema table_name row_count table_size_mb]
+        )
+      end
+
+      # Table cache hit ratios
+      # @return [Report] Report with table cache hit ratios
+      def cache_hit_ratios(limit: 50)
+        data = executor.execute_from_file(:tables, :cache_hit_ratios)
+          .first(limit)
+
+        Report.new(
+          title: "Table Cache Hit Ratios",
+          data: data,
+          columns: %w[schema table_name heap_blks_read heap_blks_hit cache_hit_ratio]
+        )
+      end
+
+      # Sequential scan statistics
+      # @return [Report] Report with sequential scan statistics
+      def seq_scans(limit: 20)
+        data = executor.execute_from_file(:tables, :seq_scans)
+          .first(limit)
+
+        Report.new(
+          title: "Sequential Scans (top #{limit})",
+          data: data,
+          columns: %w[schema table_name seq_scan seq_tup_read idx_scan rows_per_seq_scan]
+        )
+      end
+
+      # Recently modified tables
+      # @return [Report] Report with recently modified tables
+      def recently_modified(limit: 20)
+        data = executor.execute_from_file(:tables, :recently_modified)
+          .first(limit)
+
+        Report.new(
+          title: "Recently Modified Tables",
+          data: data,
+          columns: %w[schema table_name n_tup_ins n_tup_upd n_tup_del last_analyze]
+        )
+      end
+
+      private
+
+      def executor
+        @executor ||= Executor.new
+      end
+    end
+  end
+end

data/lib/pg_reports/report.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module PgReports
+  # Report class that wraps query results and provides display/send methods
+  # Every module method returns a Report instance for chaining
+  class Report
+    attr_reader :title, :data, :columns, :generated_at
+
+    def initialize(title:, data:, columns: nil)
+      @title = title
+      @data = data
+      @columns = columns || detect_columns
+      @generated_at = Time.current
+    end
+
+    # Display report to STDOUT
+    def display
+      puts to_text
+    end
+
+    # Send report to configured Telegram channel as a message
+    def send_to_telegram
+      TelegramSender.send_message(to_markdown)
+      self
+    end
+
+    # Send report to configured Telegram channel as a file
+    def send_to_telegram_as_file(filename: nil)
+      filename ||= "#{title.parameterize}-#{generated_at.strftime("%Y%m%d-%H%M%S")}.txt"
+      TelegramSender.send_file(to_text, filename: filename, caption: title)
+      self
+    end
+
+    # Return plain text representation
+    def to_text
+      return empty_report_text if data.empty?
+
+      lines = []
+      lines << title
+      lines << "=" * title.length
+      lines << "Generated: #{generated_at.strftime("%Y-%m-%d %H:%M:%S")}"
+      lines << ""
+      lines << format_table_text
+      lines << ""
+      lines << "Total: #{data.size} rows"
+
+      lines.join("\n")
+    end
+
+    # Return Markdown representation
+    def to_markdown
+      return empty_report_markdown if data.empty?
+
+      lines = []
+      lines << "**#{title}**"
+      lines << "_Generated: #{generated_at.strftime("%Y-%m-%d %H:%M:%S")}_"
+      lines << ""
+      lines << format_table_markdown
+      lines << ""
+      lines << "_Total: #{data.size} rows_"
+
+      lines.join("\n")
+    end
+
+    # Return HTML representation
+    def to_html
+      return empty_report_html if data.empty?
+
+      lines = []
+      lines << "<h2>#{CGI.escapeHTML(title)}</h2>"
+      lines << "<p><em>Generated: #{generated_at.strftime("%Y-%m-%d %H:%M:%S")}</em></p>"
+      lines << format_table_html
+      lines << "<p><em>Total: #{data.size} rows</em></p>"
+
+      lines.join("\n")
+    end
+
+    # Return CSV representation
+    def to_csv
+      require "csv"
+
+      CSV.generate do |csv|
+        csv << columns
+        data.each do |row|
+          csv << columns.map { |col| row[col] }
+        end
+      end
+    end
+
+    # Get raw data as array of hashes
+    def to_a
+      data
+    end
+
+    # Check if report is empty
+    def empty?
+      data.empty?
+    end
+
+    # Get row count
+    def size
+      data.size
+    end
+
+    alias_method :length, :size
+    alias_method :count, :size
+
+    # Iterate over rows
+    def each(&block)
+      data.each(&block)
+    end
+
+    include Enumerable
+
+    private
+
+    def detect_columns
+      return [] if data.empty?
+
+      data.first.keys
+    end
+
+    def empty_report_text
+      "#{title}\n#{"=" * title.length}\nNo data found."
+    end
+
+    def empty_report_markdown
+      "**#{title}**\n\n_No data found._"
+    end
+
+    def empty_report_html
+      "<h2>#{CGI.escapeHTML(title)}</h2>\n<p><em>No data found.</em></p>"
+    end
+
+    def format_table_text
+      return "" if data.empty?
+
+      # Calculate column widths
+      widths = calculate_column_widths
+
+      # Build header
+      header = columns.map.with_index { |col, i| col.to_s.ljust(widths[i]) }.join(" | ")
+      separator = widths.map { |w| "-" * w }.join("-+-")
+
+      # Build rows
+      rows = data.map do |row|
+        columns.map.with_index do |col, i|
+          format_cell(row[col]).to_s.ljust(widths[i])
+        end.join(" | ")
+      end
+
+      [header, separator, *rows].join("\n")
+    end
+
+    def format_table_markdown
+      return "" if data.empty?
+
+      # Markdown table header
+      header = "| " + columns.map(&:to_s).join(" | ") + " |"
+      separator = "| " + columns.map { "---" }.join(" | ") + " |"
+
+      # Build rows (limit for Telegram message size)
+      limited_data = data.first(50)
+      rows = limited_data.map do |row|
+        "| " + columns.map { |col| format_cell(row[col]) }.join(" | ") + " |"
+      end
+
+      result = [header, separator, *rows]
+      result << "| ... and #{data.size - 50} more rows |" if data.size > 50
+
+      result.join("\n")
+    end
+
+    def format_table_html
+      return "" if data.empty?
+
+      lines = ["<table>"]
+
+      # Header
+      lines << "<thead><tr>"
+      columns.each { |col| lines << "<th>#{CGI.escapeHTML(col.to_s)}</th>" }
+      lines << "</tr></thead>"
+
+      # Body
+      lines << "<tbody>"
+      data.each do |row|
+        lines << "<tr>"
+        columns.each { |col| lines << "<td>#{CGI.escapeHTML(format_cell(row[col]))}</td>" }
+        lines << "</tr>"
+      end
+      lines << "</tbody>"
+
+      lines << "</table>"
+      lines.join("\n")
+    end
+
+    def calculate_column_widths
+      columns.map.with_index do |col, _i|
+        values = data.map { |row| format_cell(row[col]).to_s.length }
+        [col.to_s.length, *values].max
+      end
+    end
+
+    def format_cell(value)
+      case value
+      when nil
+        ""
+      when Float
+        format("%.2f", value)
+      when Time, DateTime
+        value.strftime("%Y-%m-%d %H:%M:%S")
+      when String
+        truncate_query(value)
+      else
+        value.to_s
+      end
+    end
+
+    def truncate_query(text)
+      max_length = PgReports.config.max_query_length
+      return text if text.length <= max_length
+
+      "#{text[0, max_length - 3]}..."
+    end
+  end
+end

data/lib/pg_reports/sql/connections/active_connections.sql

@@ -0,0 +1,20 @@
+-- Active connections
+-- Shows all current database connections
+
+SELECT
+  pid,
+  datname AS database,
+  usename AS username,
+  application_name AS application,
+  client_addr,
+  client_hostname,
+  state,
+  query_start,
+  state_change,
+  wait_event_type,
+  wait_event,
+  LEFT(query, 500) AS query
+FROM pg_stat_activity
+WHERE datname IS NOT NULL
+  AND pid != pg_backend_pid()
+ORDER BY query_start DESC NULLS LAST;

data/lib/pg_reports/sql/connections/blocking_queries.sql

@@ -0,0 +1,35 @@
+-- Blocking queries
+-- Shows queries that are blocking other queries
+
+SELECT
+  blocked_locks.pid AS blocked_pid,
+  blocked_activity.usename AS blocked_user,
+  blocking_locks.pid AS blocking_pid,
+  blocking_activity.usename AS blocking_user,
+  blocked_activity.datname AS database,
+  EXTRACT(EPOCH FROM (NOW() - blocked_activity.query_start)) AS blocked_duration,
+  blocked_activity.wait_event_type AS blocked_wait_type,
+  LEFT(blocked_activity.query, 300) AS blocked_query,
+  LEFT(blocking_activity.query, 300) AS blocking_query,
+  blocked_locks.locktype AS lock_type,
+  blocked_locks.mode AS blocked_mode,
+  blocking_locks.mode AS blocking_mode
+FROM pg_catalog.pg_locks blocked_locks
+JOIN pg_catalog.pg_stat_activity blocked_activity
+  ON blocked_activity.pid = blocked_locks.pid
+JOIN pg_catalog.pg_locks blocking_locks
+  ON blocking_locks.locktype = blocked_locks.locktype
+  AND blocking_locks.database IS NOT DISTINCT FROM blocked_locks.database
+  AND blocking_locks.relation IS NOT DISTINCT FROM blocked_locks.relation
+  AND blocking_locks.page IS NOT DISTINCT FROM blocked_locks.page
+  AND blocking_locks.tuple IS NOT DISTINCT FROM blocked_locks.tuple
+  AND blocking_locks.virtualxid IS NOT DISTINCT FROM blocked_locks.virtualxid
+  AND blocking_locks.transactionid IS NOT DISTINCT FROM blocked_locks.transactionid
+  AND blocking_locks.classid IS NOT DISTINCT FROM blocked_locks.classid
+  AND blocking_locks.objid IS NOT DISTINCT FROM blocked_locks.objid
+  AND blocking_locks.objsubid IS NOT DISTINCT FROM blocked_locks.objsubid
+  AND blocking_locks.pid != blocked_locks.pid
+JOIN pg_catalog.pg_stat_activity blocking_activity
+  ON blocking_activity.pid = blocking_locks.pid
+WHERE NOT blocked_locks.granted
+ORDER BY blocked_duration DESC;

data/lib/pg_reports/sql/connections/connection_stats.sql

@@ -0,0 +1,13 @@
+-- Connection statistics by state
+-- Summary of connections grouped by database and state
+
+SELECT
+  datname AS database,
+  state,
+  COUNT(*) AS count,
+  COUNT(*) FILTER (WHERE wait_event IS NOT NULL) AS waiting_count
+FROM pg_stat_activity
+WHERE datname IS NOT NULL
+  AND pid != pg_backend_pid()
+GROUP BY datname, state
+ORDER BY datname, count DESC;

data/lib/pg_reports/sql/connections/idle_connections.sql

@@ -0,0 +1,19 @@
+-- Idle connections
+-- Shows connections that are idle
+
+SELECT
+  pid,
+  datname AS database,
+  usename AS username,
+  application_name AS application,
+  client_addr,
+  state,
+  EXTRACT(EPOCH FROM (NOW() - state_change)) AS idle_duration,
+  state_change,
+  query_start,
+  LEFT(query, 200) AS last_query
+FROM pg_stat_activity
+WHERE datname IS NOT NULL
+  AND pid != pg_backend_pid()
+  AND state IN ('idle', 'idle in transaction', 'idle in transaction (aborted)')
+ORDER BY idle_duration DESC;

data/lib/pg_reports/sql/connections/locks.sql

@@ -0,0 +1,20 @@
+-- Current locks
+-- Shows all locks held in the database
+
+SELECT
+  l.pid,
+  a.datname AS database,
+  a.usename AS username,
+  COALESCE(c.relname, l.relation::text) AS relation,
+  l.locktype,
+  l.mode,
+  l.granted,
+  NOT l.granted AS waiting,
+  EXTRACT(EPOCH FROM (NOW() - a.query_start)) AS query_duration,
+  LEFT(a.query, 300) AS query
+FROM pg_locks l
+JOIN pg_stat_activity a ON l.pid = a.pid
+LEFT JOIN pg_class c ON l.relation = c.oid
+WHERE a.datname IS NOT NULL
+  AND l.pid != pg_backend_pid()
+ORDER BY l.granted, l.pid;

data/lib/pg_reports/sql/connections/long_running_queries.sql

@@ -0,0 +1,21 @@
+-- Long running queries
+-- Queries that have been running for extended period
+
+SELECT
+  pid,
+  datname AS database,
+  usename AS username,
+  application_name AS application,
+  client_addr,
+  state,
+  EXTRACT(EPOCH FROM (NOW() - query_start)) AS duration_seconds,
+  query_start,
+  wait_event_type,
+  wait_event,
+  LEFT(query, 500) AS query
+FROM pg_stat_activity
+WHERE datname IS NOT NULL
+  AND pid != pg_backend_pid()
+  AND state = 'active'
+  AND query_start IS NOT NULL
+ORDER BY duration_seconds DESC;

data/lib/pg_reports/sql/indexes/bloated_indexes.sql

@@ -0,0 +1,36 @@
+-- Bloated indexes: indexes with estimated bloat
+-- Uses pgstattuple extension if available, otherwise estimates
+
+WITH index_stats AS (
+  SELECT
+    schemaname AS schema,
+    tablename AS table_name,
+    indexname AS index_name,
+    pg_relation_size(indexname::regclass) AS index_size,
+    -- Estimate bloat using relation page count vs expected
+    CASE
+      WHEN pg_relation_size(indexname::regclass) > 0 THEN
+        ROUND(
+          (
+            (pg_relation_size(indexname::regclass) -
+             (SELECT reltuples * 8 FROM pg_class WHERE relname = indexname))
+            * 100.0 / pg_relation_size(indexname::regclass)
+          )::numeric,
+          2
+        )
+      ELSE 0
+    END AS estimated_bloat_percent
+  FROM pg_indexes
+  WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+)
+SELECT
+  schema,
+  table_name,
+  index_name,
+  pg_size_pretty(index_size) AS index_size,
+  ROUND(index_size / 1024.0 / 1024.0, 2) AS index_size_mb,
+  GREATEST(estimated_bloat_percent, 0) AS bloat_percent,
+  ROUND(GREATEST(estimated_bloat_percent, 0) * index_size / 100.0 / 1024.0 / 1024.0, 2) AS bloat_size_mb
+FROM index_stats
+WHERE index_size > 1024 * 1024  -- Only indexes > 1MB
+ORDER BY index_size DESC;

data/lib/pg_reports/sql/indexes/duplicate_indexes.sql

@@ -0,0 +1,38 @@
+-- Duplicate indexes: indexes that may be redundant
+-- One index is a prefix of another on the same table
+
+WITH index_cols AS (
+  SELECT
+    n.nspname AS schema,
+    t.relname AS table_name,
+    i.relname AS index_name,
+    a.amname AS index_type,
+    ARRAY_AGG(attr.attname ORDER BY array_position(ix.indkey, attr.attnum)) AS columns,
+    pg_relation_size(i.oid) AS index_size
+  FROM pg_index ix
+  JOIN pg_class t ON t.oid = ix.indrelid
+  JOIN pg_class i ON i.oid = ix.indexrelid
+  JOIN pg_namespace n ON n.oid = t.relnamespace
+  JOIN pg_am a ON a.oid = i.relam
+  JOIN pg_attribute attr ON attr.attrelid = t.oid AND attr.attnum = ANY(ix.indkey)
+  WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+  GROUP BY n.nspname, t.relname, i.relname, a.amname, i.oid
+)
+SELECT
+  a.table_name,
+  a.index_name,
+  a.columns AS index_columns,
+  b.index_name AS duplicate_of,
+  b.columns AS duplicate_columns,
+  pg_size_pretty(a.index_size) AS index_size,
+  ROUND(a.index_size / 1024.0 / 1024.0, 2) AS index_size_mb
+FROM index_cols a
+JOIN index_cols b ON
+  a.schema = b.schema AND
+  a.table_name = b.table_name AND
+  a.index_name != b.index_name AND
+  a.index_type = b.index_type AND
+  -- a's columns are a prefix of b's columns
+  a.columns = b.columns[1:array_length(a.columns, 1)]
+WHERE array_length(a.columns, 1) < array_length(b.columns, 1)
+ORDER BY a.index_size DESC;

data/lib/pg_reports/sql/indexes/index_sizes.sql

@@ -0,0 +1,14 @@
+-- Index sizes
+-- Shows all indexes sorted by size
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  indexrelname AS index_name,
+  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
+  ROUND(pg_relation_size(indexrelid) / 1024.0 / 1024.0, 2) AS index_size_mb,
+  idx_scan,
+  idx_tup_read
+FROM pg_stat_user_indexes
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY pg_relation_size(indexrelid) DESC;

data/lib/pg_reports/sql/indexes/index_usage.sql

@@ -0,0 +1,19 @@
+-- Index usage statistics
+-- Shows how often each index is scanned
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  indexrelname AS index_name,
+  idx_scan,
+  idx_tup_read,
+  idx_tup_fetch,
+  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
+  ROUND(pg_relation_size(indexrelid) / 1024.0 / 1024.0, 2) AS index_size_mb,
+  CASE
+    WHEN idx_scan > 0 THEN ROUND((idx_tup_read / idx_scan)::numeric, 2)
+    ELSE 0
+  END AS avg_tuples_per_scan
+FROM pg_stat_user_indexes
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY idx_scan DESC;

data/lib/pg_reports/sql/indexes/invalid_indexes.sql

@@ -0,0 +1,15 @@
+-- Invalid indexes: indexes that are not valid
+-- These may have failed during concurrent creation
+
+SELECT
+  n.nspname AS schema,
+  t.relname AS table_name,
+  i.relname AS index_name,
+  pg_get_indexdef(i.oid) AS index_definition
+FROM pg_index ix
+JOIN pg_class t ON t.oid = ix.indrelid
+JOIN pg_class i ON i.oid = ix.indexrelid
+JOIN pg_namespace n ON n.oid = t.relnamespace
+WHERE NOT ix.indisvalid
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY n.nspname, t.relname, i.relname;

data/lib/pg_reports/sql/indexes/missing_indexes.sql

@@ -0,0 +1,27 @@
+-- Tables potentially missing indexes
+-- High sequential scans with low or no index usage
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  seq_scan,
+  seq_tup_read,
+  idx_scan,
+  COALESCE(idx_scan, 0) AS idx_scan_count,
+  CASE
+    WHEN seq_scan > 0 THEN ROUND((seq_tup_read / seq_scan)::numeric, 0)
+    ELSE 0
+  END AS avg_seq_tup_read,
+  pg_size_pretty(pg_relation_size(relid)) AS table_size,
+  ROUND(pg_relation_size(relid) / 1024.0 / 1024.0, 2) AS table_size_mb,
+  n_live_tup AS estimated_rows
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND seq_scan > 50
+  AND pg_relation_size(relid) > 10 * 1024 * 1024  -- Tables > 10MB
+  AND (
+    idx_scan IS NULL
+    OR idx_scan = 0
+    OR (seq_scan::float / NULLIF(idx_scan, 0)) > 10
+  )
+ORDER BY seq_tup_read DESC NULLS LAST;

data/lib/pg_reports/sql/indexes/unused_indexes.sql

@@ -0,0 +1,18 @@
+-- Unused indexes: indexes that are rarely or never scanned
+-- These indexes waste disk space and slow down writes
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  indexrelname AS index_name,
+  idx_scan,
+  idx_tup_read,
+  idx_tup_fetch,
+  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
+  ROUND(pg_relation_size(indexrelid) / 1024.0 / 1024.0, 2) AS index_size_mb
+FROM pg_stat_user_indexes
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND idx_scan = 0
+  AND indexrelname NOT LIKE '%_pkey'
+  AND indexrelname NOT LIKE '%_unique%'
+ORDER BY pg_relation_size(indexrelid) DESC;

data/lib/pg_reports/sql/queries/all_queries.sql

@@ -0,0 +1,20 @@
+-- All query statistics ordered by total time
+-- Requires pg_stat_statements extension
+
+SELECT
+  query,
+  calls,
+  ROUND((total_exec_time)::numeric, 2) AS total_time_ms,
+  ROUND((mean_exec_time)::numeric, 2) AS mean_time_ms,
+  ROUND((min_exec_time)::numeric, 2) AS min_time_ms,
+  ROUND((max_exec_time)::numeric, 2) AS max_time_ms,
+  ROUND((stddev_exec_time)::numeric, 2) AS stddev_time_ms,
+  rows,
+  shared_blks_hit,
+  shared_blks_read,
+  ROUND((shared_blks_hit * 100.0 / NULLIF(shared_blks_hit + shared_blks_read, 0))::numeric, 2) AS cache_hit_ratio
+FROM pg_stat_statements
+WHERE calls > 0
+  AND query NOT LIKE '%pg_stat_statements%'
+ORDER BY total_exec_time DESC
+LIMIT 200;