pg_reports 0.6.2 → 0.8.0

data/lib/pg_reports/connection/target.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Connection
+    # Represents a single named PostgreSQL target (host+credentials).
+    # Holds a memoized AR-subclass-backed connection per database it has been
+    # asked for, so switching between databases on the same target reuses pools.
+    #
+    # The :primary target wraps ActiveRecord::Base directly when accessed at its
+    # default database — we don't open a parallel pool to the host app's DB.
+    # For non-default databases we create an isolated AR subclass that has its
+    # own pool, so the host application's pool is never affected.
+    class Target
+      class ConnectionFailed < PgReports::Error; end
+
+      attr_reader :name
+
+      def initialize(name, spec)
+        @name = name.to_sym
+        @spec = normalize_spec(spec)
+        @pools = {} # database (string) => AR class
+      end
+
+      # Configuration hash used as a template for derived databases.
+      def spec
+        @spec.dup
+      end
+
+      def default_database
+        @spec[:database]&.to_s
+      end
+
+      # Resolve the AR class backing the connection for `database` (nil = default).
+      # Returns a class responding to `.connection` (ActiveRecord::Base or subclass).
+      def ar_class_for(database = nil)
+        db = (database || default_database).to_s
+        raise ArgumentError, "Cannot resolve connection: target #{name.inspect} has no default database and none was given" if db.empty?
+
+        @pools[db] ||= build_pool_class(db)
+      end
+
+      # Returns the active PG connection for `database`, opening it if needed.
+      def connection_for(database = nil)
+        ar_class_for(database).connection
+      rescue ActiveRecord::NoDatabaseError, PG::ConnectionBad => e
+        raise ConnectionFailed, "Cannot connect to #{name}/#{database || default_database}: #{e.message}"
+      end
+
+      # List all databases visible on this target's cluster (using pg_database).
+      # Result rows: { "name" => String, "size" => String, "current" => Boolean }
+      def list_databases(current: nil)
+        rows = connection_for.exec_query(<<~SQL).to_a
+          SELECT datname AS name,
+                 pg_size_pretty(pg_database_size(datname)) AS size
+          FROM pg_database
+          WHERE datistemplate = false AND datallowconn = true
+          ORDER BY datname
+        SQL
+        current_db = (current || default_database).to_s
+        rows.each { |r| r["current"] = (r["name"].to_s == current_db) }
+        rows
+      end
+
+      # Close all derived pools we own. The :primary AR::Base pool is never touched.
+      def disconnect!
+        @pools.each_value do |klass|
+          next if klass.equal?(ActiveRecord::Base)
+          klass.connection_pool.disconnect! if klass.connection_pool.connected?
+        rescue
+          # Best-effort cleanup
+        end
+        @pools.clear
+      end
+
+      private
+
+      def normalize_spec(spec)
+        hash = case spec
+        when Hash
+          spec.transform_keys(&:to_sym)
+        when ActiveRecord::DatabaseConfigurations::HashConfig
+          spec.configuration_hash.transform_keys(&:to_sym)
+        else
+          raise ArgumentError, "Unsupported spec type: #{spec.class}"
+        end
+
+        # Ensure adapter defaults to postgresql; we only support PG.
+        hash[:adapter] ||= "postgresql"
+        hash
+      end
+
+      def build_pool_class(database)
+        # When asked for the primary target's default database, reuse AR::Base
+        # so we don't open a parallel pool to the same DB the host app uses.
+        if name == :primary && database == default_database
+          return ActiveRecord::Base
+        end
+
+        klass = Class.new(ActiveRecord::Base) { self.abstract_class = true }
+        const_name = "Pool_#{name}_#{database}".gsub(/\W/, "_")
+        if PgReports::Connection.const_defined?(const_name, false)
+          PgReports::Connection.send(:remove_const, const_name)
+        end
+        PgReports::Connection.const_set(const_name, klass)
+
+        klass.establish_connection(@spec.merge(database: database))
+        klass
+      end
+    end
+  end
+end

data/lib/pg_reports/dashboard/reports_registry.rb

@@ -277,8 +277,8 @@ module PgReports
             seq_scans: {name: "Sequential Scans", description: "Tables with high sequential scans"},
             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}
+            update_hotspots: {name: "Update Hotspots", description: "Same rows or indexed columns updated repeatedly"},
+            unused_tables: {name: "Unused Tables", description: "Tables never queried since the last stats reset"}
           }
         },
         connections: {
@@ -316,14 +316,19 @@ module PgReports
           name: "Schema Analysis",
           icon: "🔍",
           color: "#06b6d4",
+          # These reports introspect the host application's ActiveRecord models,
+          # which are bound to the default database. Running them against a
+          # different database in the cluster returns rows that may not map to
+          # any model. The dashboard greys the category out in that case.
+          target_constraint: :primary_default_database_only,
           reports: {
             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}
+            unused_columns: {name: "Unused Columns", description: "Columns that have only ever held a single value"},
+            always_null_columns: {name: "Always-NULL Columns", description: "Nullable columns that contain only NULL"},
+            polymorphic_without_index: {name: "Polymorphic Without Index", description: "Polymorphic associations missing composite index"},
+            counter_cache_issues: {name: "Counter Cache Issues", description: "counter_cache declarations whose target column is missing"},
+            soft_delete_without_scope: {name: "Soft Delete Without Scope", description: "Soft-delete columns with no model scope filtering them"},
+            orphan_tables: {name: "Orphan Tables", description: "DB tables without a corresponding Rails model"}
           }
         }
       }.freeze
@@ -398,6 +403,15 @@ module PgReports
       def self.problem_fields(report)
         REPORT_CONFIG.dig(report.to_sym, :problem_fields) || []
       end
+
+      # Returns the target constraint declared on a category, or nil.
+      # Currently the only constraint is :primary_default_database_only, which
+      # means "only meaningful when the dashboard is pointing at the host app's
+      # primary target on its default database" — used by Schema Analysis,
+      # which depends on ActiveRecord::Base.descendants of the host app.
+      def self.target_constraint(category)
+        REPORTS.dig(category.to_sym, :target_constraint)
+      end
     end
   end
 end

data/lib/pg_reports/executor.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 module PgReports
-  # Executes SQL queries and returns results
+  # Executes SQL queries and returns results.
+  #
+  # The connection is resolved lazily on every #execute call so that thread-local
+  # context set by PgReports.with_target / with_database is honored even when an
+  # Executor instance has been memoized at the module level.
   class Executor
     def initialize(connection: nil)
-      @connection = connection || PgReports.config.connection
+      @connection_override = connection
     end
 
     # Execute SQL from a file and return results as array of hashes
@@ -16,10 +20,15 @@ module PgReports
     # 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 = connection.exec_query(processed_sql)
       result.to_a
     end
 
+    # Resolved on every call: explicit override > thread-local > registry default.
+    def connection
+      @connection_override || PgReports.config.connection
+    end
+
     private
 
     # Simple parameter interpolation for SQL
@@ -40,11 +49,11 @@ module PgReports
       when Integer, Float
         value.to_s
       when String
-        @connection.quote(value)
+        connection.quote(value)
       when Array
         "(#{value.map { |v| quote_value(v) }.join(", ")})"
       else
-        @connection.quote(value.to_s)
+        connection.quote(value.to_s)
       end
     end
   end

data/lib/pg_reports/grafana/dashboard_builder.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PgReports
+  module Grafana
+    # Builds an importable Grafana dashboard JSON from configured favorites.
+    # Each report becomes a row with two panels:
+    #   - "rows" stat (total)
+    #   - "issues by severity" timeseries (ok / warning / critical)
+    # Severity colours are wired so that any warning lights yellow, any critical lights red.
+    class DashboardBuilder
+      DATASOURCE_INPUT = "DS_PROMETHEUS"
+
+      DEFAULT_TITLE = "PgReports — PostgreSQL Health"
+      DEFAULT_UID = "pg-reports"
+
+      SEVERITY_COLORS = {
+        "ok" => "green",
+        "warning" => "yellow",
+        "critical" => "red"
+      }.freeze
+
+      GRID_WIDTH = 24
+      ROW_HEIGHT = 1
+      TIMESERIES_HEIGHT = 8
+      TABLE_HEIGHT = 10
+      REPORT_BLOCK_HEIGHT = TIMESERIES_HEIGHT + TABLE_HEIGHT
+
+      def self.build(**opts)
+        new(**opts).build
+      end
+
+      def initialize(favorites: PgReports.config.grafana_favorites,
+        title: DEFAULT_TITLE,
+        uid: DEFAULT_UID,
+        refresh: "1m",
+        time_from: "now-6h")
+        @favorites = normalize(favorites)
+        @title = title
+        @uid = uid
+        @refresh = refresh
+        @time_from = time_from
+        @panel_id = 0
+      end
+
+      def build
+        if @favorites.empty?
+          raise ArgumentError,
+            "No favorites configured. Set PgReports.config.grafana_favorites or pass favorites:."
+        end
+
+        {
+          "__inputs" => [datasource_input],
+          "__requires" => [grafana_require, prometheus_require],
+          "annotations" => {"list" => []},
+          "editable" => true,
+          "graphTooltip" => 1,
+          "panels" => build_panels,
+          "refresh" => @refresh,
+          "schemaVersion" => 38,
+          "tags" => ["pg_reports", "postgresql"],
+          "templating" => {"list" => []},
+          "time" => {"from" => @time_from, "to" => "now"},
+          "timezone" => "browser",
+          "title" => @title,
+          "uid" => @uid,
+          "version" => 1,
+          "weekStart" => ""
+        }
+      end
+
+      def to_json(*)
+        JSON.pretty_generate(build)
+      end
+
+      private
+
+      def normalize(favorites)
+        case favorites
+        when Hash then favorites.keys.map(&:to_sym)
+        when Array then favorites.map(&:to_sym)
+        else []
+        end
+      end
+
+      def build_panels
+        panels = []
+        y = 0
+
+        grouped_favorites.each do |category, keys|
+          panels << row_panel(category_label(category), y)
+          y += ROW_HEIGHT
+
+          keys.each do |key|
+            info = report_info(category, key)
+            panels << timeseries_panel(key, info, y)
+            panels << table_panel(key, info, y + TIMESERIES_HEIGHT)
+            y += REPORT_BLOCK_HEIGHT
+          end
+        end
+
+        panels
+      end
+
+      def grouped_favorites
+        groups = {}
+        @favorites.each do |key|
+          category = category_for(key)
+          next unless category # silently skip unknown keys; exporter logs them
+          groups[category] ||= []
+          groups[category] << key
+        end
+        groups
+      end
+
+      def category_for(key)
+        Dashboard::ReportsRegistry::REPORTS.each do |category, info|
+          return category if info[:reports].key?(key)
+        end
+        nil
+      end
+
+      def category_label(category)
+        Dashboard::ReportsRegistry::REPORTS.dig(category, :name) || category.to_s.humanize
+      end
+
+      def report_info(category, key)
+        Dashboard::ReportsRegistry::REPORTS.dig(category, :reports, key) || {name: key.to_s.humanize, description: ""}
+      end
+
+      def row_panel(title, y)
+        {
+          "id" => next_id,
+          "type" => "row",
+          "title" => title,
+          "collapsed" => false,
+          "gridPos" => {"h" => ROW_HEIGHT, "w" => GRID_WIDTH, "x" => 0, "y" => y},
+          "panels" => []
+        }
+      end
+
+      def timeseries_panel(key, info, y)
+        {
+          "id" => next_id,
+          "type" => "timeseries",
+          "title" => "#{info[:name]} — issues by severity",
+          "description" => info[:description].to_s,
+          "datasource" => datasource_ref,
+          "gridPos" => {"h" => TIMESERIES_HEIGHT, "w" => GRID_WIDTH, "x" => 0, "y" => y},
+          "targets" => severity_targets(key),
+          "options" => {
+            "legend" => {"displayMode" => "table", "placement" => "right", "calcs" => ["lastNotNull"]},
+            "tooltip" => {"mode" => "multi", "sort" => "desc"}
+          },
+          "fieldConfig" => {
+            "defaults" => {
+              "custom" => {
+                "drawStyle" => "bars",
+                "stacking" => {"mode" => "normal", "group" => "A"},
+                "fillOpacity" => 60,
+                "lineWidth" => 1
+              },
+              "color" => {"mode" => "fixed"},
+              "mappings" => []
+            },
+            "overrides" => severity_color_overrides
+          }
+        }
+      end
+
+      def table_panel(key, info, y)
+        {
+          "id" => next_id,
+          "type" => "table",
+          "title" => "#{info[:name]} — current rows",
+          "description" => "#{info[:description]}\n\nLatest snapshot of report rows. Each row's columns are unpacked from Prometheus labels via the Labels-to-fields transformation.".strip,
+          "datasource" => datasource_ref,
+          "gridPos" => {"h" => TABLE_HEIGHT, "w" => GRID_WIDTH, "x" => 0, "y" => y},
+          "targets" => [
+            {
+              "refId" => "A",
+              "expr" => %(pg_reports_row{report="#{key}"}),
+              "datasource" => datasource_ref,
+              "format" => "table",
+              "instant" => true,
+              "legendFormat" => "__auto"
+            }
+          ],
+          "transformations" => [
+            {
+              "id" => "labelsToFields",
+              "options" => {"mode" => "columns"}
+            },
+            {
+              "id" => "organize",
+              "options" => {
+                "excludeByName" => {
+                  "Time" => true,
+                  "Value" => true,
+                  "__name__" => true,
+                  "instance" => true,
+                  "job" => true,
+                  "report" => true,
+                  "row" => true
+                },
+                "indexByName" => {},
+                "renameByName" => {}
+              }
+            }
+          ],
+          "options" => {
+            "showHeader" => true,
+            "cellHeight" => "sm",
+            "footer" => {"show" => false}
+          },
+          "fieldConfig" => {
+            "defaults" => {
+              "custom" => {"align" => "auto", "displayMode" => "auto"},
+              "mappings" => []
+            },
+            "overrides" => []
+          }
+        }
+      end
+
+      def severity_targets(key)
+        SEVERITY_COLORS.keys.each_with_index.map do |severity, i|
+          {
+            "refId" => ("A".ord + i).chr,
+            "expr" => %(pg_reports_issues{report="#{key}",severity="#{severity}"}),
+            "datasource" => datasource_ref,
+            "legendFormat" => severity
+          }
+        end
+      end
+
+      def severity_color_overrides
+        SEVERITY_COLORS.map do |severity, color|
+          {
+            "matcher" => {"id" => "byName", "options" => severity},
+            "properties" => [
+              {"id" => "color", "value" => {"mode" => "fixed", "fixedColor" => color}}
+            ]
+          }
+        end
+      end
+
+      def datasource_input
+        {
+          "name" => DATASOURCE_INPUT,
+          "label" => "Prometheus",
+          "description" => "Datasource that scrapes /pg_reports/metrics",
+          "type" => "datasource",
+          "pluginId" => "prometheus",
+          "pluginName" => "Prometheus"
+        }
+      end
+
+      def datasource_ref
+        {"type" => "prometheus", "uid" => "${#{DATASOURCE_INPUT}}"}
+      end
+
+      def grafana_require
+        {"type" => "grafana", "id" => "grafana", "name" => "Grafana", "version" => "9.0.0"}
+      end
+
+      def prometheus_require
+        {"type" => "datasource", "id" => "prometheus", "name" => "Prometheus", "version" => "1.0.0"}
+      end
+
+      def next_id
+        @panel_id += 1
+      end
+    end
+  end
+end