pg_insights 0.1.0

data/config/routes.rb

@@ -0,0 +1,22 @@
+PgInsights::Engine.routes.draw do
+  root "insights#index"
+
+  # For running queries and loading the main UI
+  post "/", to: "insights#index"
+
+  # For the table name dropdown
+  get :table_names, to: "insights#table_names"
+
+  # For managing user-saved queries
+  resources :queries, only: [ :create, :update, :destroy ]  # For the health dashboard
+  get :health, to: "health#index"
+  namespace :health do
+    get :unused_indexes
+    get :missing_indexes
+    get :sequential_scans
+    get :slow_queries
+    get :table_bloat
+    get :parameter_settings
+    post :refresh
+  end
+end

data/lib/generators/pg_insights/clean_generator.rb

@@ -0,0 +1,74 @@
+require "rails/generators/base"
+
+module PgInsights
+  module Generators
+    class CleanGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../..", __FILE__)
+
+      def remove_routes
+        routes_file = File.join(destination_root, "config", "routes.rb")
+        route_to_remove = "mount PgInsights::Engine => '/pg_insights'"
+
+        if File.exist?(routes_file)
+          routes_content = File.read(routes_file)
+          if routes_content.include?(route_to_remove)
+            puts "Removing PgInsights engine mount from routes..."
+            updated_content = routes_content.gsub(/^\s*#{Regexp.escape(route_to_remove)}\s*\n?/, "")
+            File.write(routes_file, updated_content)
+            say_status("removed", "PgInsights engine mount from config/routes.rb", :green)
+          else
+            say_status("skipped", "PgInsights engine mount not found in config/routes.rb", :yellow)
+          end
+        end
+      end
+
+      def remove_initializer
+        initializer_path = "config/initializers/pg_insights.rb"
+        initializer_full_path = File.join(destination_root, initializer_path)
+
+        if File.exist?(initializer_full_path)
+          puts "Removing PgInsights initializer..."
+          remove_file initializer_path
+          say_status("removed", initializer_path, :green)
+        else
+          say_status("skipped", "#{initializer_path} not found", :yellow)
+        end
+      end
+
+      def show_migration_rollback_instructions
+        puts "\nPgInsights has been cleaned up!"
+        puts ""
+        puts "To complete the uninstallation, you may also want to:"
+        puts "1. Roll back the migrations:"
+
+        migration_files = find_pg_insights_migrations
+        if migration_files.any?
+          puts "   rails db:rollback STEP=#{migration_files.count}"
+          puts ""
+          puts "2. Or manually remove the migration files:"
+          migration_files.each do |file|
+            puts "   rm #{file}"
+          end
+        else
+          puts "   (No PgInsights migrations found)"
+        end
+
+        puts ""
+        puts "3. Remove any PgInsights data from your database:"
+        puts "   rails runner 'PgInsights::Query.destroy_all'"
+        puts "   rails runner 'PgInsights::HealthCheckResult.destroy_all'"
+        puts ""
+        puts "4. If you want to reinstall later, run: rails generate pg_insights:install"
+      end
+
+      private
+
+      def find_pg_insights_migrations
+        migrate_path = File.join(destination_root, "db", "migrate")
+        return [] unless File.directory?(migrate_path)
+
+        Dir.glob("#{migrate_path}/*_create_pg_insights_*.rb").sort
+      end
+    end
+  end
+end

data/lib/generators/pg_insights/install_generator.rb

@@ -0,0 +1,176 @@
+require "rails/generators/base"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module PgInsights
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("../../../..", __FILE__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_migrations
+        copy_queries_migration
+        copy_health_check_results_migration
+      end
+
+      def create_initializer
+        initializer_path = File.join(destination_root, "config", "initializers", "pg_insights.rb")
+
+        if File.exist?(initializer_path)
+          say_status("skipped", "Initializer 'config/initializers/pg_insights.rb' already exists", :yellow)
+        else
+          puts "Creating PgInsights initializer..."
+          create_file "config/initializers/pg_insights.rb", initializer_content
+        end
+      end
+
+      def mount_engine
+        route_to_add = "mount PgInsights::Engine => '/pg_insights'"
+        routes_file = File.join(destination_root, "config", "routes.rb")
+
+        if File.exist?(routes_file) && File.read(routes_file).include?(route_to_add)
+          say_status("skipped", "Route `#{route_to_add}` already exists in `config/routes.rb`", :yellow)
+        else
+          puts "Mounting PgInsights engine..."
+          route route_to_add
+        end
+      end
+
+      def show_readme
+        puts "\nPgInsights has been successfully installed!"
+        puts ""
+        puts "Next steps:"
+        puts "1. Run 'rails db:migrate' to create the necessary tables"
+        puts "2. Review and customize 'config/initializers/pg_insights.rb'"
+        puts "3. Configure background jobs (optional, see initializer comments)"
+        puts "4. Visit '/pg_insights' in your browser to start using the dashboard"
+        puts ""
+        puts "For background job integration, see: config/initializers/pg_insights.rb"
+        puts "To check status: rails pg_insights:status"
+        puts "To uninstall: rails generate pg_insights:clean"
+      end
+
+      private
+
+      def initializer_content
+        <<~RUBY
+          # PgInsights Configuration
+          ##{' '}
+          # This file contains the configuration for PgInsights, a PostgreSQL database
+          # performance monitoring and health check engine.
+
+          PgInsights.configure do |config|
+            # === Background Jobs Configuration ===
+            ##{' '}
+            # Enable background job processing for health checks.
+            # When enabled, health checks will run asynchronously if your app has ActiveJob configured.
+            # When disabled or if ActiveJob is not available, health checks run synchronously.
+            #
+            # Default: true
+            config.enable_background_jobs = true
+
+            # Queue name for PgInsights background jobs
+            # Make sure this queue is processed by your job processor (Sidekiq, Resque, etc.)
+            #
+            # Default: :pg_insights_health
+            config.background_job_queue = :pg_insights_health
+
+            # === Cache and Timeout Settings ===
+          #{'  '}
+            # How long to cache health check results before considering them stale
+            # Stale results will trigger background refresh when accessed
+            #
+            # Default: 5.minutes
+            config.health_cache_expiry = 5.minutes
+
+            # Timeout for individual health check queries to prevent long-running queries
+            # from blocking the application
+            #
+            # Default: 10.seconds#{'  '}
+            config.health_check_timeout = 10.seconds
+
+            # Maximum execution time for user queries in the insights interface
+            #
+            # Default: 30.seconds
+            config.max_query_execution_time = 30.seconds
+          end
+
+          # === Background Job Integration ===
+          #
+          # If you want automatic recurring health checks, add one of these to your job scheduler:
+          #
+          # ** Whenever (crontab) **
+          # Add to config/schedule.rb:
+          #   every 1.hour do
+          #     runner "PgInsights::RecurringHealthChecksJob.perform_later"
+          #   end
+          #
+          # ** Sidekiq-Cron **
+          # Add to config/initializers/sidekiq.rb:
+          #   Sidekiq::Cron::Job.create(
+          #     name: 'PgInsights Health Checks',
+          #     cron: '0 * * * *',
+          #     class: 'PgInsights::RecurringHealthChecksJob'
+          #   )
+          #
+          # ** Manual Trigger **
+          # You can also trigger health checks manually:
+          #   PgInsights::HealthCheckService.refresh_all!
+          #
+          # ** Check Status **
+          # To verify your configuration:
+          #   rails pg_insights:status
+
+          # === Environment-Specific Settings ===
+          #
+          # You may want different settings per environment:
+          #
+          # if Rails.env.development?
+          #   PgInsights.configure do |config|
+          #     config.health_cache_expiry = 1.minute  # Shorter cache in development
+          #     config.enable_background_jobs = false  # Synchronous in development
+          #   end
+          # end
+          #
+          # if Rails.env.production?
+          #   PgInsights.configure do |config|
+          #     config.health_cache_expiry = 15.minutes  # Longer cache in production
+          #     config.health_check_timeout = 30.seconds # More generous timeout
+          #   end
+          # end
+        RUBY
+      end
+
+      def copy_queries_migration
+        if migration_exists?("create_pg_insights_queries")
+          say_status("skipped", "Migration 'create_pg_insights_queries' already exists", :yellow)
+        else
+          puts "Copying PgInsights queries migration..."
+          migration_template "db/migrate/create_pg_insights_queries.rb",
+                             "db/migrate/create_pg_insights_queries.rb"
+        end
+      end
+
+      def copy_health_check_results_migration
+        if migration_exists?("create_pg_insights_health_check_results")
+          say_status("skipped", "Migration 'create_pg_insights_health_check_results' already exists", :yellow)
+        else
+          puts "Copying PgInsights health check results migration..."
+          migration_template "db/migrate/create_pg_insights_health_check_results.rb",
+                             "db/migrate/create_pg_insights_health_check_results.rb"
+        end
+      end
+
+      def migration_exists?(migration_name)
+        migrate_path = File.join(destination_root, "db", "migrate")
+        return false unless File.directory?(migrate_path)
+        Dir.glob("#{migrate_path}/*_#{migration_name}.rb").any?
+      end
+    end
+  end
+end

data/lib/pg_insights/engine.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "chartkick"
+
+module PgInsights
+  class Engine < ::Rails::Engine
+    isolate_namespace PgInsights
+
+    initializer "pg_insights.assets.precompile" do |app|
+      app.config.assets.precompile += %w[
+        pg_insights/application.css
+        pg_insights/application.js
+        pg_insights/health.css
+        pg_insights/health.js
+        pg_insights/results.css
+        pg_insights/results.js
+      ]
+    end
+
+    initializer "pg_insights.configure_background_jobs", after: "active_job.set_configs" do |app|
+      ActiveSupport.on_load(:active_job) do
+        if PgInsights.enable_background_jobs
+          if PgInsights.background_jobs_available?
+            Rails.logger.info "PgInsights: Background jobs enabled (#{ActiveJob::Base.queue_adapter_name})"
+          else
+            Rails.logger.warn "PgInsights: Background jobs enabled but may not be fully available yet."
+            Rails.logger.warn "PgInsights: Will fall back to synchronous execution when needed."
+            Rails.logger.warn "PgInsights: Check your ActiveJob configuration if you see issues."
+          end
+        else
+          Rails.logger.info "PgInsights: Background jobs disabled - will run health checks synchronously"
+        end
+      end
+    end
+
+    rake_tasks do
+      load "tasks/pg_insights.rake"
+    end
+  end
+end

data/lib/pg_insights/version.rb

@@ -0,0 +1,3 @@
+module PgInsights
+  VERSION = "0.1.0"
+end

data/lib/pg_insights.rb

@@ -0,0 +1,83 @@
+require "pg_insights/version"
+require "pg_insights/engine"
+
+module PgInsights
+  # Configuration options
+  mattr_accessor :enable_background_jobs, default: true
+  mattr_accessor :health_cache_expiry, default: 5.minutes
+  mattr_accessor :background_job_queue, default: :pg_insights_health
+  mattr_accessor :max_query_execution_time, default: 30.seconds
+  mattr_accessor :health_check_timeout, default: 10.seconds
+
+  def self.configure
+    yield self
+  end
+
+  # Check if background jobs are available and properly configured
+  def self.background_jobs_available?
+    return false unless enable_background_jobs
+    return false unless defined?(ActiveJob::Base)
+    return false if ActiveJob::Base.queue_adapter.is_a?(ActiveJob::QueueAdapters::InlineAdapter)
+    return false unless defined?(PgInsights::HealthCheckJob)
+
+    # Verify the queue adapter can handle our jobs
+    begin
+      ActiveJob::Base.queue_adapter.respond_to?(:enqueue) ||
+      ActiveJob::Base.queue_adapter.respond_to?(:enqueue_at)
+    rescue => e
+      Rails.logger.debug "PgInsights: Background job check failed: #{e.message}" if defined?(Rails)
+      false
+    end
+  end
+
+  # Safely execute background jobs with fallback
+  def self.execute_with_fallback(job_class, method_name, *args, &fallback_block)
+    if background_jobs_available?
+      begin
+        job_class.public_send(method_name, *args)
+        return true
+      rescue => e
+        Rails.logger.warn "PgInsights: Background job failed, falling back to synchronous execution: #{e.message}" if defined?(Rails)
+      end
+    end
+
+    # Execute fallback if provided
+    fallback_block.call if fallback_block
+    false
+  end
+
+  # Integration helpers for host applications
+  module Integration
+    # Helper for host apps to check if they need to configure anything
+    def self.status
+      {
+        background_jobs_available: PgInsights.background_jobs_available?,
+        queue_adapter: defined?(ActiveJob::Base) ? ActiveJob::Base.queue_adapter_name : "not_available",
+        configuration: {
+          enable_background_jobs: PgInsights.enable_background_jobs,
+          health_cache_expiry: PgInsights.health_cache_expiry,
+          background_job_queue: PgInsights.background_job_queue
+        }
+      }
+    end
+
+    # Helper for host apps to test job functionality
+    def self.test_background_jobs
+      return { success: false, error: "Background jobs disabled" } unless PgInsights.enable_background_jobs
+      return { success: false, error: "ActiveJob not available" } unless defined?(ActiveJob::Base)
+
+      begin
+        # Try to enqueue a simple test
+        if defined?(PgInsights::HealthCheckJob)
+          # Don't actually run the job, just test enqueueing
+          Rails.logger.info "PgInsights: Testing background job capability..."
+          { success: true, message: "Background jobs appear to be working" }
+        else
+          { success: false, error: "PgInsights job classes not loaded" }
+        end
+      rescue => e
+        { success: false, error: e.message }
+      end
+    end
+  end
+end

data/lib/tasks/pg_insights.rake

@@ -0,0 +1,172 @@
+namespace :pg_insights do
+  desc "Show PgInsights configuration and background job status"
+  task status: :environment do
+    puts "PgInsights Configuration Status"
+    puts "==============================="
+
+    status = PgInsights::Integration.status
+
+    puts "Background Jobs: #{status[:background_jobs_available] ? '✅ Available' : '❌ Not Available'}"
+    puts "Queue Adapter: #{status[:queue_adapter]}"
+    puts "Queue Name: #{status[:configuration][:background_job_queue]}"
+    puts "Cache Expiry: #{status[:configuration][:health_cache_expiry]}"
+    puts "Enabled: #{status[:configuration][:enable_background_jobs] ? 'Yes' : 'No'}"
+
+    if defined?(PgInsights::RecurringHealthChecksJob)
+      puts "\nRecurring Job Status:"
+      validation = PgInsights::RecurringHealthChecksJob.validate_setup
+      if validation[:valid]
+        puts "✅ #{validation[:message]}"
+      else
+        puts "❌ Issues found:"
+        validation[:issues].each { |issue| puts "   - #{issue}" }
+      end
+    end
+
+    puts "\nIntegration Help:"
+    if status[:background_jobs_available]
+      puts "✅ Your application is ready for PgInsights background jobs!"
+      puts "   Add this to your job scheduler (whenever, sidekiq-cron, etc.):"
+      puts "   PgInsights::RecurringHealthChecksJob.perform_later"
+    else
+      puts "ℹ️  Background jobs are not configured. PgInsights will work in synchronous mode."
+      puts "   To enable background processing:"
+      puts "   1. Configure ActiveJob in your Rails application"
+      puts "   2. Set up a job queue backend (Sidekiq, Resque, etc.)"
+      puts "   3. Add to config/initializers/pg_insights.rb:"
+      puts "      PgInsights.configure { |c| c.enable_background_jobs = true }"
+    end
+  end
+
+  desc "Test background job functionality"
+  task test_jobs: :environment do
+    puts "Testing PgInsights Background Jobs"
+    puts "=================================="
+
+    test_result = PgInsights::Integration.test_background_jobs
+
+    if test_result[:success]
+      puts "✅ #{test_result[:message]}"
+
+      # Try scheduling a real health check
+      if defined?(PgInsights::HealthCheckJob)
+        if PgInsights::HealthCheckJob.perform_check("parameter_settings")
+          puts "✅ Successfully enqueued a test health check"
+        else
+          puts "❌ Failed to enqueue test health check"
+        end
+      end
+    else
+      puts "❌ #{test_result[:error]}"
+    end
+  end
+
+  desc "Run health checks synchronously (without background jobs)"
+  task health_check: :environment do
+    puts "Running PgInsights Health Checks (Synchronous)"
+    puts "=============================================="
+
+    start_time = Time.current
+
+    begin
+      PgInsights::HealthCheckService.execute_all_checks_synchronously
+      execution_time = Time.current - start_time
+
+      puts "✅ Health checks completed in #{execution_time.round(2)} seconds"
+      puts "Visit /pg_insights/health in your browser to see the results"
+    rescue => e
+      puts "❌ Health checks failed: #{e.message}"
+    end
+  end
+
+  desc "Clear all PgInsights stored data"
+  task clear_data: :environment do
+    puts "Clearing PgInsights stored data..."
+
+    # Remove data from database
+    begin
+      if defined?(PgInsights::Query)
+        query_count = PgInsights::Query.count
+        PgInsights::Query.destroy_all
+        puts "Removed #{query_count} stored queries"
+      end
+    rescue => e
+      puts "Could not remove queries: #{e.message}"
+    end
+
+    begin
+      if defined?(PgInsights::HealthCheckResult)
+        result_count = PgInsights::HealthCheckResult.count
+        PgInsights::HealthCheckResult.destroy_all
+        puts "Removed #{result_count} cached health check results"
+      end
+    rescue => e
+      puts "Could not remove health check results: #{e.message}"
+    end
+
+    puts "PgInsights data cleared successfully!"
+    puts "To completely uninstall PgInsights (remove migrations and routes), run: rails generate pg_insights:clean"
+  end
+
+  desc "Reset PgInsights data (clears all stored queries and health check results)"
+  task reset: :environment do
+    puts "Resetting PgInsights data..."
+
+    begin
+      if defined?(PgInsights::Query)
+        PgInsights::Query.destroy_all
+        puts "Cleared all PgInsights queries"
+      end
+    rescue => e
+      puts "Could not clear queries: #{e.message}"
+    end
+
+    begin
+      if defined?(PgInsights::HealthCheckResult)
+        PgInsights::HealthCheckResult.destroy_all
+        puts "Cleared all PgInsights health check results"
+      end
+    rescue => e
+      puts "Could not clear health check results: #{e.message}"
+    end
+
+    puts "PgInsights data reset completed!"
+  end
+
+  desc "Show PgInsights statistics"
+  task stats: :environment do
+    puts "PgInsights Statistics:"
+    puts "====================="
+
+    begin
+      if defined?(PgInsights::Query)
+        query_count = PgInsights::Query.count
+        puts "Stored queries: #{query_count}"
+      end
+    rescue => e
+      puts "Queries table not available: #{e.message}"
+    end
+
+    begin
+      if defined?(PgInsights::HealthCheckResult)
+        result_count = PgInsights::HealthCheckResult.count
+        recent_results = PgInsights::HealthCheckResult.where("executed_at > ?", 24.hours.ago).count
+        puts "Health check results: #{result_count}"
+        puts "Recent results (24h): #{recent_results}"
+
+        # Show results by type
+        PgInsights::HealthCheckResult::VALID_CHECK_TYPES.each do |check_type|
+          latest = PgInsights::HealthCheckResult.latest_for_type(check_type)
+          if latest
+            freshness = latest.fresh? ? "fresh" : "stale"
+            puts "  #{check_type}: #{latest.status} (#{freshness})"
+          else
+            puts "  #{check_type}: no data"
+          end
+        end
+      end
+    rescue => e
+      puts "Health check results table not available: #{e.message}"
+    end
+  end
+end