pg_reports 0.1.0

data/lib/pg_reports/sql/queries/expensive_queries.sql

@@ -0,0 +1,22 @@
+-- Expensive queries: queries consuming most total time
+-- Requires pg_stat_statements extension
+
+WITH total AS (
+  SELECT SUM(total_exec_time) AS total_time
+  FROM pg_stat_statements
+  WHERE calls > 0
+)
+SELECT
+  s.query,
+  s.calls,
+  ROUND((s.total_exec_time)::numeric, 2) AS total_time_ms,
+  ROUND((s.total_exec_time * 100.0 / t.total_time)::numeric, 2) AS percent_of_total,
+  ROUND((s.mean_exec_time)::numeric, 2) AS mean_time_ms,
+  s.rows
+FROM pg_stat_statements s, total t
+WHERE s.calls > 0
+  AND s.query NOT LIKE '%pg_stat_statements%'
+  AND s.query NOT LIKE 'COMMIT%'
+  AND s.query NOT LIKE 'BEGIN%'
+ORDER BY s.total_exec_time DESC
+LIMIT 100;

data/lib/pg_reports/sql/queries/heavy_queries.sql

@@ -0,0 +1,17 @@
+-- Heavy queries: queries called most frequently
+-- 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,
+  rows,
+  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%'
+  AND query NOT LIKE 'COMMIT%'
+  AND query NOT LIKE 'BEGIN%'
+ORDER BY calls DESC
+LIMIT 100;

data/lib/pg_reports/sql/queries/low_cache_hit_queries.sql

@@ -0,0 +1,19 @@
+-- Queries with low cache hit ratio
+-- Requires pg_stat_statements extension
+
+SELECT
+  query,
+  calls,
+  ROUND((shared_blks_hit * 100.0 / NULLIF(shared_blks_hit + shared_blks_read, 0))::numeric, 2) AS cache_hit_ratio,
+  shared_blks_hit,
+  shared_blks_read,
+  ROUND((total_exec_time)::numeric, 2) AS total_time_ms,
+  ROUND((mean_exec_time)::numeric, 2) AS mean_time_ms
+FROM pg_stat_statements
+WHERE calls > 10
+  AND (shared_blks_hit + shared_blks_read) > 0
+  AND query NOT LIKE '%pg_stat_statements%'
+  AND query NOT LIKE 'COMMIT%'
+  AND query NOT LIKE 'BEGIN%'
+ORDER BY (shared_blks_hit * 1.0 / NULLIF(shared_blks_hit + shared_blks_read, 0)) ASC
+LIMIT 100;

data/lib/pg_reports/sql/queries/missing_index_queries.sql

@@ -0,0 +1,25 @@
+-- Queries potentially missing indexes
+-- Identifies queries with patterns suggesting sequential scans
+-- 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,
+  rows,
+  -- Heuristic: high rows examined per call may indicate missing index
+  ROUND((rows / NULLIF(calls, 0))::numeric, 0) AS rows_per_call,
+  -- High read/hit ratio suggests disk access (possible seq scan)
+  ROUND((shared_blks_read * 100.0 / NULLIF(shared_blks_hit + shared_blks_read, 0))::numeric, 2) AS disk_read_ratio
+FROM pg_stat_statements
+WHERE calls > 10
+  AND (rows / NULLIF(calls, 0)) > 100
+  AND mean_exec_time > 10
+  AND query NOT LIKE '%pg_stat_statements%'
+  AND query NOT LIKE 'COMMIT%'
+  AND query NOT LIKE 'BEGIN%'
+  -- Focus on SELECT statements
+  AND (query ILIKE 'SELECT%' OR query ILIKE '%WHERE%')
+ORDER BY (rows / NULLIF(calls, 0)) * calls DESC
+LIMIT 100;

data/lib/pg_reports/sql/queries/slow_queries.sql

@@ -0,0 +1,17 @@
+-- Slow queries: queries with high mean execution time
+-- Requires pg_stat_statements extension
+
+SELECT
+  query,
+  calls,
+  ROUND((mean_exec_time)::numeric, 2) AS mean_time_ms,
+  ROUND((total_exec_time)::numeric, 2) AS total_time_ms,
+  ROUND((rows / NULLIF(calls, 0))::numeric, 2) AS rows_per_call,
+  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%'
+  AND query NOT LIKE 'COMMIT%'
+  AND query NOT LIKE 'BEGIN%'
+ORDER BY mean_exec_time DESC
+LIMIT 100;

data/lib/pg_reports/sql/system/activity_overview.sql

@@ -0,0 +1,29 @@
+-- Database activity overview
+-- Summary metrics for current database activity
+
+WITH stats AS (
+  SELECT
+    (SELECT count(*) FROM pg_stat_activity WHERE datname = current_database()) AS total_connections,
+    (SELECT count(*) FROM pg_stat_activity WHERE datname = current_database() AND state = 'active') AS active_queries,
+    (SELECT count(*) FROM pg_stat_activity WHERE datname = current_database() AND state = 'idle') AS idle_connections,
+    (SELECT count(*) FROM pg_stat_activity WHERE datname = current_database() AND state = 'idle in transaction') AS idle_in_transaction,
+    (SELECT count(*) FROM pg_stat_activity WHERE datname = current_database() AND wait_event IS NOT NULL) AS waiting_connections,
+    (SELECT count(*) FROM pg_locks WHERE NOT granted) AS blocked_queries,
+    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections,
+    (SELECT ROUND(pg_database_size(current_database()) / 1024.0 / 1024.0, 2)) AS database_size_mb
+)
+SELECT 'Total Connections' AS metric, total_connections::text AS value FROM stats
+UNION ALL
+SELECT 'Active Queries', active_queries::text FROM stats
+UNION ALL
+SELECT 'Idle Connections', idle_connections::text FROM stats
+UNION ALL
+SELECT 'Idle in Transaction', idle_in_transaction::text FROM stats
+UNION ALL
+SELECT 'Waiting Connections', waiting_connections::text FROM stats
+UNION ALL
+SELECT 'Blocked Queries', blocked_queries::text FROM stats
+UNION ALL
+SELECT 'Max Connections', max_connections::text FROM stats
+UNION ALL
+SELECT 'Database Size (MB)', database_size_mb::text FROM stats;

data/lib/pg_reports/sql/system/cache_stats.sql

@@ -0,0 +1,19 @@
+-- Database cache statistics
+-- Shows cache hit ratios for each database
+
+SELECT
+  datname AS database,
+  ROUND(
+    CASE
+      WHEN blks_hit + blks_read > 0 THEN
+        (blks_hit * 100.0 / (blks_hit + blks_read))
+      ELSE 100
+    END::numeric,
+    2
+  ) AS heap_hit_ratio,
+  blks_hit,
+  blks_read
+FROM pg_stat_database
+WHERE datname NOT LIKE 'template%'
+  AND datname IS NOT NULL
+ORDER BY datname;

data/lib/pg_reports/sql/system/database_sizes.sql

@@ -0,0 +1,10 @@
+-- Database sizes
+-- Shows size of all databases
+
+SELECT
+  datname AS database,
+  ROUND(pg_database_size(datname) / 1024.0 / 1024.0, 2) AS size_mb,
+  pg_size_pretty(pg_database_size(datname)) AS size_pretty
+FROM pg_database
+WHERE datistemplate = false
+ORDER BY pg_database_size(datname) DESC;

data/lib/pg_reports/sql/system/extensions.sql

@@ -0,0 +1,12 @@
+-- Installed extensions
+-- Shows all installed PostgreSQL extensions
+
+SELECT
+  extname AS name,
+  extversion AS version,
+  n.nspname AS schema,
+  c.description
+FROM pg_extension e
+JOIN pg_namespace n ON e.extnamespace = n.oid
+LEFT JOIN pg_description c ON c.objoid = e.oid AND c.classoid = 'pg_extension'::regclass
+ORDER BY extname;

data/lib/pg_reports/sql/system/settings.sql

@@ -0,0 +1,33 @@
+-- Important PostgreSQL settings
+-- Shows key configuration parameters
+
+SELECT
+  name,
+  setting,
+  unit,
+  category,
+  short_desc AS description
+FROM pg_settings
+WHERE name IN (
+  'shared_buffers',
+  'effective_cache_size',
+  'work_mem',
+  'maintenance_work_mem',
+  'max_connections',
+  'max_parallel_workers',
+  'max_parallel_workers_per_gather',
+  'random_page_cost',
+  'seq_page_cost',
+  'effective_io_concurrency',
+  'wal_buffers',
+  'checkpoint_completion_target',
+  'default_statistics_target',
+  'statement_timeout',
+  'lock_timeout',
+  'idle_in_transaction_session_timeout',
+  'log_min_duration_statement',
+  'autovacuum',
+  'autovacuum_vacuum_scale_factor',
+  'autovacuum_analyze_scale_factor'
+)
+ORDER BY category, name;

data/lib/pg_reports/sql/tables/bloated_tables.sql

@@ -0,0 +1,23 @@
+-- Bloated tables: tables with high dead tuple ratio
+-- High bloat indicates need for VACUUM
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  n_live_tup AS live_rows,
+  n_dead_tup AS dead_rows,
+  CASE
+    WHEN n_live_tup + n_dead_tup > 0 THEN
+      ROUND((n_dead_tup * 100.0 / (n_live_tup + n_dead_tup))::numeric, 2)
+    ELSE 0
+  END AS bloat_percent,
+  pg_size_pretty(pg_table_size(relid)) AS table_size,
+  ROUND(pg_table_size(relid) / 1024.0 / 1024.0, 2) AS table_size_mb,
+  last_vacuum,
+  last_autovacuum,
+  last_analyze,
+  last_autoanalyze
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND n_live_tup + n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;

data/lib/pg_reports/sql/tables/cache_hit_ratios.sql

@@ -0,0 +1,24 @@
+-- Table cache hit ratios
+-- Low cache hit ratio may indicate need for more memory or index optimization
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  heap_blks_read,
+  heap_blks_hit,
+  CASE
+    WHEN heap_blks_hit + heap_blks_read > 0 THEN
+      ROUND((heap_blks_hit * 100.0 / (heap_blks_hit + heap_blks_read))::numeric, 2)
+    ELSE 100
+  END AS cache_hit_ratio,
+  idx_blks_read,
+  idx_blks_hit,
+  CASE
+    WHEN idx_blks_hit + idx_blks_read > 0 THEN
+      ROUND((idx_blks_hit * 100.0 / (idx_blks_hit + idx_blks_read))::numeric, 2)
+    ELSE 100
+  END AS idx_cache_hit_ratio
+FROM pg_statio_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND (heap_blks_hit + heap_blks_read) > 0
+ORDER BY cache_hit_ratio ASC;

data/lib/pg_reports/sql/tables/recently_modified.sql

@@ -0,0 +1,20 @@
+-- Recently modified tables
+-- Tables with recent insert/update/delete activity
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  n_tup_ins AS inserts,
+  n_tup_upd AS updates,
+  n_tup_del AS deletes,
+  n_tup_hot_upd AS hot_updates,
+  n_live_tup AS live_rows,
+  n_dead_tup AS dead_rows,
+  last_vacuum,
+  last_autovacuum,
+  last_analyze,
+  last_autoanalyze
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND (n_tup_ins + n_tup_upd + n_tup_del) > 0
+ORDER BY (n_tup_ins + n_tup_upd + n_tup_del) DESC;

data/lib/pg_reports/sql/tables/row_counts.sql

@@ -0,0 +1,18 @@
+-- Table row counts
+-- Estimated row counts from statistics
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  n_live_tup AS row_count,
+  n_dead_tup AS dead_rows,
+  pg_size_pretty(pg_table_size(relid)) AS table_size,
+  ROUND(pg_table_size(relid) / 1024.0 / 1024.0, 2) AS table_size_mb,
+  CASE
+    WHEN n_live_tup > 0 THEN
+      ROUND((pg_table_size(relid) / n_live_tup)::numeric, 0)
+    ELSE 0
+  END AS bytes_per_row
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY n_live_tup DESC;

data/lib/pg_reports/sql/tables/seq_scans.sql

@@ -0,0 +1,26 @@
+-- Sequential scan statistics
+-- High sequential scans may indicate missing indexes
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  seq_scan,
+  seq_tup_read,
+  CASE
+    WHEN seq_scan > 0 THEN
+      ROUND((seq_tup_read / seq_scan)::numeric, 0)
+    ELSE 0
+  END AS rows_per_seq_scan,
+  idx_scan,
+  idx_tup_fetch,
+  CASE
+    WHEN seq_scan + COALESCE(idx_scan, 0) > 0 THEN
+      ROUND((seq_scan * 100.0 / (seq_scan + COALESCE(idx_scan, 0)))::numeric, 2)
+    ELSE 0
+  END AS seq_scan_ratio,
+  pg_size_pretty(pg_table_size(relid)) AS table_size,
+  n_live_tup AS row_count
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND seq_scan > 0
+ORDER BY seq_tup_read DESC;

data/lib/pg_reports/sql/tables/table_sizes.sql

@@ -0,0 +1,16 @@
+-- Table sizes including indexes
+-- Shows disk usage for each table
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  pg_size_pretty(pg_table_size(relid)) AS table_size,
+  ROUND(pg_table_size(relid) / 1024.0 / 1024.0, 2) AS table_size_mb,
+  pg_size_pretty(pg_indexes_size(relid)) AS index_size,
+  ROUND(pg_indexes_size(relid) / 1024.0 / 1024.0, 2) AS index_size_mb,
+  pg_size_pretty(pg_total_relation_size(relid)) AS total_size,
+  ROUND(pg_total_relation_size(relid) / 1024.0 / 1024.0, 2) AS total_size_mb,
+  n_live_tup AS row_count
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY pg_total_relation_size(relid) DESC;

data/lib/pg_reports/sql/tables/vacuum_needed.sql

@@ -0,0 +1,22 @@
+-- Tables needing vacuum
+-- High dead row count or long time since last vacuum
+
+SELECT
+  schemaname AS schema,
+  relname AS table_name,
+  n_live_tup,
+  n_dead_tup,
+  CASE
+    WHEN n_live_tup > 0 THEN
+      ROUND((n_dead_tup * 100.0 / n_live_tup)::numeric, 2)
+    ELSE 0
+  END AS dead_ratio_percent,
+  last_vacuum,
+  last_autovacuum,
+  last_analyze,
+  vacuum_count,
+  autovacuum_count,
+  pg_size_pretty(pg_table_size(relid)) AS table_size
+FROM pg_stat_user_tables
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+ORDER BY n_dead_tup DESC;

data/lib/pg_reports/sql_loader.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PgReports
+  # Loads and caches SQL queries from files
+  module SqlLoader
+    SQL_DIR = File.expand_path("sql", __dir__)
+
+    class << self
+      def load(category, name)
+        cache_key = "#{category}/#{name}"
+        sql_cache[cache_key] ||= read_sql_file(category, name)
+      end
+
+      def clear_cache!
+        @sql_cache = {}
+      end
+
+      private
+
+      def sql_cache
+        @sql_cache ||= {}
+      end
+
+      def read_sql_file(category, name)
+        path = File.join(SQL_DIR, category.to_s, "#{name}.sql")
+
+        unless File.exist?(path)
+          raise SqlFileNotFoundError, "SQL file not found: #{path}"
+        end
+
+        File.read(path)
+      end
+    end
+  end
+end

data/lib/pg_reports/telegram_sender.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module PgReports
+  # Sends reports to Telegram using telegram-bot-ruby gem
+  module TelegramSender
+    class << self
+      def send_message(text, parse_mode: "Markdown")
+        ensure_configured!
+        ensure_telegram_gem!
+
+        bot.api.send_message(
+          chat_id: chat_id,
+          text: truncate_message(text),
+          parse_mode: parse_mode
+        )
+      end
+
+      def send_file(content, filename:, caption: nil)
+        ensure_configured!
+        ensure_telegram_gem!
+
+        # Create a temporary file
+        temp_file = Tempfile.new([File.basename(filename, ".*"), File.extname(filename)])
+        begin
+          temp_file.write(content)
+          temp_file.rewind
+
+          bot.api.send_document(
+            chat_id: chat_id,
+            document: Faraday::UploadIO.new(temp_file.path, "text/plain", filename),
+            caption: caption&.truncate(1024)
+          )
+        ensure
+          temp_file.close
+          temp_file.unlink
+        end
+      end
+
+      def send_report(report)
+        if report.to_text.length > 4000
+          send_file(report.to_text, filename: report_filename(report), caption: report.title)
+        else
+          send_message(report.to_markdown)
+        end
+      end
+
+      private
+
+      def bot
+        @bot ||= Telegram::Bot::Client.new(PgReports.config.telegram_bot_token)
+      end
+
+      def chat_id
+        PgReports.config.telegram_chat_id
+      end
+
+      def ensure_configured!
+        unless PgReports.config.telegram_configured?
+          raise TelegramNotConfiguredError, "Telegram is not configured. Set telegram_bot_token and telegram_chat_id."
+        end
+      end
+
+      def ensure_telegram_gem!
+        unless defined?(Telegram::Bot)
+          raise Error, "telegram-bot-ruby gem is not installed. Add it to your Gemfile: gem 'telegram-bot-ruby'"
+        end
+      end
+
+      def truncate_message(text)
+        # Telegram message limit is 4096 characters
+        return text if text.length <= 4096
+
+        "#{text[0, 4000]}...\n\n_Message truncated. Use send_to_telegram_as_file for full report._"
+      end
+
+      def report_filename(report)
+        "#{report.title.parameterize}-#{report.generated_at.strftime("%Y%m%d-%H%M%S")}.txt"
+      end
+    end
+  end
+end

data/lib/pg_reports/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PgReports
+  VERSION = "0.1.0"
+end

data/lib/pg_reports.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext"
+require "active_record"
+
+require_relative "pg_reports/version"
+require_relative "pg_reports/error"
+require_relative "pg_reports/configuration"
+require_relative "pg_reports/sql_loader"
+require_relative "pg_reports/executor"
+require_relative "pg_reports/report"
+require_relative "pg_reports/telegram_sender"
+require_relative "pg_reports/annotation_parser"
+
+# Modules
+require_relative "pg_reports/modules/queries"
+require_relative "pg_reports/modules/indexes"
+require_relative "pg_reports/modules/tables"
+require_relative "pg_reports/modules/connections"
+require_relative "pg_reports/modules/system"
+
+# Dashboard
+require_relative "pg_reports/dashboard/reports_registry"
+
+# Rails Engine
+require_relative "pg_reports/engine" if defined?(Rails::Engine)
+
+module PgReports
+  class << self
+    # Query analysis methods
+    delegate :slow_queries, :heavy_queries, :expensive_queries,
+      :missing_index_queries, :low_cache_hit_queries, :all_queries,
+      :reset_statistics!, to: Modules::Queries
+
+    # Index analysis methods
+    delegate :unused_indexes, :duplicate_indexes, :invalid_indexes,
+      :missing_indexes, :index_usage, :bloated_indexes, :index_sizes,
+      to: Modules::Indexes
+
+    # Table analysis methods
+    delegate :table_sizes, :bloated_tables, :vacuum_needed,
+      :row_counts, :cache_hit_ratios, :seq_scans, :recently_modified,
+      to: Modules::Tables
+
+    # Connection analysis methods
+    delegate :active_connections, :connection_stats, :long_running_queries,
+      :blocking_queries, :locks, :idle_connections,
+      :kill_connection, :cancel_query,
+      to: Modules::Connections
+
+    # System analysis methods
+    delegate :database_sizes, :settings, :extensions,
+      :activity_overview, :cache_stats, :pg_stat_statements_available?,
+      :pg_stat_statements_preloaded?, :pg_stat_statements_status,
+      :enable_pg_stat_statements!,
+      to: Modules::System
+
+    # Generate a comprehensive database health report
+    # @return [Report] Combined health report
+    def health_report
+      # Collect all reports
+      reports = {
+        "Slow Queries" => slow_queries(limit: 10),
+        "Expensive Queries" => expensive_queries(limit: 10),
+        "Unused Indexes" => unused_indexes(limit: 10),
+        "Tables Needing Vacuum" => vacuum_needed(limit: 10),
+        "Long Running Queries" => long_running_queries,
+        "Blocking Queries" => blocking_queries
+      }
+
+      # Build combined data
+      combined_data = reports.map do |name, report|
+        {
+          "section" => name,
+          "items_count" => report.size,
+          "has_issues" => report.size.positive?
+        }
+      end
+
+      Report.new(
+        title: "Database Health Report",
+        data: combined_data,
+        columns: %w[section items_count has_issues]
+      )
+    end
+
+    # Run all reports and send summary to Telegram
+    def send_health_report_to_telegram
+      health_report.send_to_telegram
+    end
+
+    # Shorthand for accessing modules directly
+    def queries
+      Modules::Queries
+    end
+
+    def indexes
+      Modules::Indexes
+    end
+
+    def tables
+      Modules::Tables
+    end
+
+    def connections
+      Modules::Connections
+    end
+
+    def system
+      Modules::System
+    end
+  end
+end