pg_peek 0.1.0

data/app/helpers/pg_peek/application_helper.rb

@@ -0,0 +1,179 @@
+module PgPeek::ApplicationHelper
+  # Where the current section lives in another database. Detail pages fall back
+  # to their section, since the other database may not have that table or job.
+  def switch_database_path(database)
+    case controller_name
+    when "queries"            then database_queries_path(database)
+    when "endpoints"          then database_endpoints_path(database)
+    when "jobs"               then database_jobs_path(database)
+    when "indexes"            then database_indexes_path(database)
+    when "activity"           then database_activity_path(database)
+    else database_path(database)
+    end
+  end
+
+  # example sql comment: /*action='show',application='Trmz',namespaced_controller='staff%2Fprocesses%2Fprocesses'*/
+
+  SQLCOMMENTER_PATTERN = %r{
+    \s*                     # optional leading whitespace
+    /\*                     # opening /*
+    (?:                     # one or more key:value pairs
+      [a-zA-Z_][a-zA-Z0-9_]*  # key (starts with letter/underscore)
+      =                       # colon
+      [^:*]*                  # value (anything except * or : to avoid breaking */
+    \s*)+
+    \*/                     # closing */
+    \s*                     # optional trailing whitespace
+  }xi
+
+  def strip_sqlcommenter(sql)
+    sql.gsub(SQLCOMMENTER_PATTERN, "").strip
+  end
+
+  # Where a query's SQLcommenter tags point, if anywhere: a job's own page,
+  # or the endpoints list for a controller/action (there is no per-endpoint
+  # page to link into yet, so this lands on the list rather than one row of it).
+  def sqlcommenter_href(database, tags)
+    return database_job_path(database, tags["job"]) if tags["job"].present?
+
+    controller = tags["namespaced_controller"] || tags["controller"]
+    return database_endpoints_path(database) if controller.present?
+
+    nil
+  end
+
+  # Format a rate with auto-scaled units based on magnitude
+  def format_rate(count, seconds_elapsed)
+    return "N/A" if seconds_elapsed.nil? || seconds_elapsed.zero? || count.nil?
+
+    per_second = count.to_f / seconds_elapsed
+
+    formatted = case per_second
+    when 0...0.017      # < 1/min
+      "#{format_number((per_second * 86400).round(1))}/day"
+    when 0.017...1      # < 1/sec
+      "#{format_number((per_second * 3600).round(1))}/hr"
+    when 1...60         # < 60/sec
+      "#{format_number((per_second * 60).round(1))}/min"
+    else
+      "#{format_number(per_second.round(1))}/s"
+    end
+
+    "(~#{formatted})"
+  end
+
+  # Format a count with its rate
+  def format_count_with_rate(count, seconds_elapsed)
+    return "N/A" if count.nil?
+
+    formatted_count = format_number(count)
+    rate = format_rate(count, seconds_elapsed)
+
+    if rate == "N/A"
+      formatted_count
+    else
+      "#{formatted_count} #{rate}"
+    end
+  end
+
+  # Format a number with thousands separators
+  def format_number(number)
+    return "N/A" if number.nil?
+    number_with_delimiter(number)
+  end
+
+  # Format a percentage, returning "N/A" for nil
+  def format_percentage(value)
+    return "N/A" if value.nil?
+    "#{value}%"
+  end
+
+  # Format a timestamp as relative time (e.g., "3 hours ago")
+  def format_time_ago(timestamp)
+    return "Never" if timestamp.nil?
+    time_ago_in_words(timestamp) + " ago"
+  end
+
+  # Every pg_stat_statements figure is cumulative since the last reset. Each
+  # page says so in its header and links to the overview block that resets it.
+  def stats_since_link(database, reset_at)
+    link_to "stats since #{format_time_ago(reset_at)}",
+            database_path(database, anchor: "pg_stat_statements"),
+            title: "figures are cumulative since the last pg_stat_statements reset"
+  end
+
+  # Format cache hit ratio for inline display
+  def format_inline_cache_stats(heap_ratio, index_ratio)
+    heap_display = heap_ratio.nil? ? "-" : "#{heap_ratio}%"
+    index_display = index_ratio.nil? ? "-" : "#{index_ratio}%"
+    "H: #{heap_display} I: #{index_display}"
+  end
+
+  # Horizontal bar meter for call intensity visualization
+  # Returns a 5-segment bar: ██░░░ (low) → █████ (high)
+  INTENSITY_SEGMENTS = 5
+
+  # One character throughout, with colour rather than shading separating the
+  # filled part from the rest: mixed block glyphs vary in weight between fonts
+  # and read as noise at this size.
+  def intensity_bar(value, max_value)
+    filled = intensity_segments(value, max_value)
+
+    # The level class lets the stylesheet brighten the bar with its value.
+    tag.span(class: "bar bar-#{filled}") do
+      tag.span("█" * filled, class: "bar-on") +
+        tag.span("█" * (INTENSITY_SEGMENTS - filled), class: "bar-off")
+    end
+  end
+
+  # A non-zero value always keeps one segment lit, so "rare but present" is
+  # distinguishable from "absent" at a glance.
+  def intensity_segments(value, max_value)
+    return 0 if value.nil? || max_value.nil? || max_value.zero?
+
+    ((value.to_f / max_value) * INTENSITY_SEGMENTS).ceil.clamp(0, INTENSITY_SEGMENTS)
+  end
+
+  # Durations pick their unit by magnitude: 210ms, 1.20s, 2m 05s, 1h 12m.
+  # Values stay narrow and read at a glance, and a header sits over data of
+  # similar width. The exact figure belongs in a title, not the cell.
+  def format_duration_from_ms(total_ms)
+    ms = total_ms.to_f
+    return "0ms" if ms <= 0
+    return format("%.1fms", ms) if ms < 10
+    return "#{ms.round}ms" if ms < 1000
+
+    seconds = ms / 1000.0
+    return format("%.2fs", seconds) if seconds < 60
+
+    minutes, secs = seconds.divmod(60)
+    return format("%dm %02ds", minutes, secs) if minutes < 60
+
+    hours, mins = minutes.divmod(60)
+    format("%dh %02dm", hours, mins)
+  end
+
+  # Rails sets intervalstyle = iso_8601 on its connections, so an interval
+  # arrives as "PT1.204S". Anything else -- a raw psql connection, or a host
+  # that overrides the style -- renders as "HH:MM:SS.fff" with a "N days"
+  # prefix once long enough. Both are read.
+  def format_duration(interval_text)
+    format_duration_from_ms(interval_to_ms(interval_text))
+  end
+
+  def interval_to_ms(interval_text)
+    text = interval_text.to_s.strip
+    return 0.0 if text.empty?
+    return ActiveSupport::Duration.parse(text).to_f * 1000.0 if text.start_with?("P")
+
+    days = text[/(\d+)\s+days?/, 1].to_i
+    hours = minutes = seconds = 0.0
+    if (match = text.match(/(\d+):(\d{2}):(\d{2}(?:\.\d+)?)/))
+      hours, minutes, seconds = match[1].to_i, match[2].to_i, match[3].to_f
+    end
+
+    (days * 86_400 + hours * 3600 + minutes * 60 + seconds) * 1000.0
+  rescue ActiveSupport::Duration::ISO8601Parser::ParsingError
+    0.0
+  end
+end

data/app/helpers/pg_peek/report_helper.rb

@@ -0,0 +1,58 @@
+# Turns a report cell into markup. The report is passed alongside the column
+# because some formats are relative -- an intensity bar means nothing without
+# the largest value in its column.
+module PgPeek::ReportHelper
+  def format_cell(report, column, row)
+    value = row.value(column)
+    return "" if value.nil? || value.to_s.empty?
+
+    case column.format
+    when :number       then format_number(value.to_i)
+    when :duration_ms  then duration_cell(value.to_f)
+    when :duration     then duration_cell(interval_to_ms(value))
+    when :percent      then "#{value}%"
+    when :ratio        then "~#{value}"
+    when :sql          then sql_cell(report, value.to_s)
+    when :intensity    then intensity_bar(value.to_f, report.max_for(column))
+    else value.to_s
+    end
+  end
+
+  # The compact figure is what you scan; the exact one is a hover away.
+  def duration_cell(ms)
+    tag.span(format_duration_from_ms(ms), title: "#{number_with_delimiter(ms.round(1))} ms")
+  end
+
+  # The SQL text, plus -- when SQLcommenter tagged it -- what issued it (a
+  # link into the page that already aggregates this exact query across every
+  # call site) and every raw tag behind a disclosure, for the rest.
+  def sql_cell(report, sql)
+    code = tag.code(strip_sqlcommenter(sql).squish, class: "sql")
+    tags = PgPeek::SqlComment.tags(sql)
+    return code if tags.empty?
+
+    safe_join([ code, sql_source(report, tags), sql_tags(tags) ].compact)
+  end
+
+  def sql_source(report, tags)
+    label = PgPeek::SqlComment.label(tags)
+    return nil unless label
+
+    href = report.database && sqlcommenter_href(report.database, tags)
+    tag.div(safe_join([ "→ ", href ? link_to(label, href) : label ]), class: "dim")
+  end
+
+  def sql_tags(tags)
+    tag.details(safe_join([
+      tag.summary("tags"),
+      tag.pre(tags.map { |key, value| "#{key}: #{value}" }.join("\n"))
+    ]), class: "tags")
+  end
+
+  def cell_class(column)
+    case column.format
+    when :intensity then "intensity"
+    else column.numeric? ? "num" : nil
+    end
+  end
+end

data/app/jobs/pg_peek/application_job.rb

@@ -0,0 +1,4 @@
+module PgPeek
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/pg_peek/application_mailer.rb

@@ -0,0 +1,6 @@
+module PgPeek
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/pg_peek/application_record.rb

@@ -0,0 +1,3 @@
+class PgPeek::ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end

data/app/models/pg_peek/database.rb

@@ -0,0 +1,131 @@
+class PgPeek::Database
+  attr_reader :name, :primary, :replica, :schema_format
+
+  def self.available_postgres_databases
+    ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).select do |db_config|
+      db_config.adapter == "postgresql"
+    end
+  end
+
+  def self.all
+    available_postgres_databases.map do |db_config|
+      PgPeek::Database.new(
+        name: db_config.name,
+        primary: db_config.primary?,
+        replica: db_config.replica?,
+        schema_format: db_config.schema_format
+      )
+    end
+  end
+
+  def self.find(name)
+    all.find { |db| db.name == name }
+  end
+
+  def initialize(name:, primary: false, replica: false, schema_format:)
+    @name = name
+    @primary = primary
+    @replica = replica
+    @schema_format = schema_format
+  end
+
+  def to_param
+    @name
+  end
+
+  # The other configured databases on the same server, judged by host and
+  # port. Production tends to give each database its own server; review apps
+  # put them all on one, where a server-wide action such as a
+  # pg_stat_statements reset reaches every one of them.
+  def server_peers
+    self.class.all.reject { |other| other.name == name }.select { |other| other.server == server }
+  end
+
+  def server
+    config = self.class.available_postgres_databases.find { |db_config| db_config.name == name }
+    return unless config
+
+    [ config.host.presence || "localhost", config.configuration_hash[:port].presence || 5432 ].map(&:to_s)
+  end
+
+  def connection
+    connection_class = PgPeek.config.connection_class_for(name)
+    connection_class&.connection
+  end
+
+  # Cheap enough for the layout to ask on every request: reads the config, does
+  # not resolve the class or check out a connection.
+  def configured?
+    PgPeek.config.connections.key?(name)
+  end
+
+  def connection_configured?
+    connection.present?
+  end
+
+  def version_full
+    @version_full ||= connection.execute(PgPeek::QueryLoader.mark("SELECT version()")).first["version"]
+  end
+
+  def version
+    @version ||= version_full.match(/PostgreSQL ([\d.]+)/)[1]
+  end
+
+  def major_version
+    @major_version ||= version.split(".").first.to_i
+  end
+
+  def installed_extensions
+    connection.execute(PgPeek::QueryLoader.mark("SELECT name, default_version, installed_version FROM pg_available_extensions WHERE installed_version IS NOT NULL ORDER BY name")).to_a
+  end
+
+  def vitals
+    @vitals ||= begin
+      query = PgPeek::QueryLoader.load("database/vitals", pg_version: major_version)
+      connection.execute(query).first || {}
+    end
+  end
+
+  def indexes
+    query = PgPeek::QueryLoader.load("indexes/all", pg_version: major_version)
+    connection.execute(query).to_a
+  end
+
+  def sessions
+    query = PgPeek::QueryLoader.load("activity/sessions", pg_version: major_version)
+    connection.execute(query).to_a
+  end
+
+  def waiting_locks
+    query = PgPeek::QueryLoader.load("activity/waiting_locks", pg_version: major_version)
+    connection.execute(query).to_a
+  end
+
+  def connection_summary
+    query = PgPeek::QueryLoader.load("activity/summary", pg_version: major_version)
+    connection.execute(query).first || {}
+  end
+
+  def stats_reset_at
+    value = vitals["stats_reset"]
+    Time.zone.parse(value.to_s) if value.present?
+  end
+
+  def tables_with_dead_tuples(threshold)
+    query = PgPeek::QueryLoader.load("tables/dead_tuples", pg_version: major_version, threshold: threshold.to_i)
+    connection.execute(query).to_a
+  end
+
+  def tables
+    connection.tables.sort - PgPeek.config.excluded_tables
+  end
+
+  def table_exists?(table_name)
+    connection.tables.include?(table_name)
+  end
+
+  def find_table(name)
+    return nil unless table_exists?(name)
+    PgPeek::Table.new(self, name)
+  end
+end

data/app/models/pg_peek/pg_stat_statements.rb

@@ -0,0 +1,132 @@
+class PgPeek::PgStatStatements
+  LIBRARY_NAME = "pg_stat_statements".freeze
+
+  attr_reader :database, :default_version, :installed_version
+
+  def initialize(database:)
+    @database = database
+
+    verify_installation
+  end
+
+  def connection
+    database.connection
+  end
+
+  def available?
+    default_version.present?
+  end
+
+  def installed?
+    installed_version.present?
+  end
+
+  # The extension can be created in the database while the module itself was
+  # never loaded at server start. Querying the view then raises
+  # PG::ObjectNotInPrerequisiteState, so every read has to check this first.
+  def preloaded?
+    shared_preload_libraries.split(",").map(&:strip).include?(LIBRARY_NAME)
+  end
+
+  def usable?
+    installed? && preloaded?
+  end
+
+  def shared_preload_libraries
+    @shared_preload_libraries ||= connection.select_value(PgPeek::QueryLoader.mark("SHOW shared_preload_libraries")).to_s
+  end
+
+  def outdated?
+    return false unless installed?
+
+    @installed_version != @default_version
+  end
+
+  # Server-wide on purpose. pg_stat_statements_info keeps a single stats_reset
+  # for the whole server and only moves it when every entry is removed, so a
+  # reset scoped to this database would leave "stats since" pointing at the
+  # old time.
+  def reset!
+    return unless usable?
+
+    connection.execute PgPeek::QueryLoader.mark(<<-SQL)
+      SELECT pg_stat_statements_reset();
+    SQL
+  end
+
+  def reset_at
+    return unless usable?
+
+    value = connection.select_value PgPeek::QueryLoader.mark(<<-SQL)
+      SELECT stats_reset FROM pg_stat_statements_info;
+    SQL
+
+    Time.zone.parse(value.to_s) if value.present?
+  end
+
+  def outliers
+    return unless usable?
+
+    query = PgPeek::QueryLoader.load("pg_stat_statements/outliers",
+                                      pg_version: database.major_version,
+                                      limit: PgPeek.config.outliers_limit)
+    result = connection.execute(query)
+    result.to_a
+  end
+
+  def statement_count
+    return unless usable?
+
+    connection.select_value(PgPeek::QueryLoader.mark(<<~SQL)).to_i
+      SELECT count(*) FROM pg_stat_statements
+      WHERE dbid = (SELECT oid FROM pg_database WHERE datname = current_database())
+    SQL
+  end
+
+  def endpoints
+    return unless usable?
+
+    query = PgPeek::QueryLoader.load("pg_stat_statements/endpoints",
+                                      pg_version: database.major_version,
+                                      limit: PgPeek.config.outliers_limit)
+    connection.execute(query).to_a
+  end
+
+  def jobs
+    return unless usable?
+
+    query = PgPeek::QueryLoader.load("pg_stat_statements/jobs",
+                                      pg_version: database.major_version)
+    result = connection.execute(query)
+    result.to_a
+  end
+
+  def outliers_by_job(job_class)
+    return unless usable?
+
+    # Build pattern to match job='JobClassName' in SQLcommenter
+    # Need to escape for SQL LIKE and quote properly
+    escaped_job = job_class.gsub("'", "''")
+    pattern = "%job='#{escaped_job}'%"
+
+    query = PgPeek::QueryLoader.load("pg_stat_statements/outliers_by_job",
+                                      pg_version: database.major_version,
+                                      job_pattern: connection.quote(pattern),
+                                      limit: PgPeek.config.outliers_limit)
+    result = connection.execute(query)
+    result.to_a
+  end
+
+  private
+
+  def verify_installation
+    result = connection.execute PgPeek::QueryLoader.mark(<<-SQL)
+      SELECT default_version, installed_version FROM pg_available_extensions WHERE name = 'pg_stat_statements';
+    SQL
+
+    if result.any?
+      @default_version = result.first["default_version"]
+      @installed_version = result.first["installed_version"]
+    end
+  end
+end

data/app/models/pg_peek/sql_comment.rb

@@ -0,0 +1,25 @@
+# Parses the trailing SQLcommenter comment Rails' query_log_tags appends to a
+# query -- e.g. /*action='index',application='Dummy',controller='posts'*/ --
+# and reduces it to the one thing worth showing at a glance: what issued this
+# query. Used by both the Sessions report and the view layer, so there is one
+# parser rather than the two that used to disagree on how tags are shaped.
+class PgPeek::SqlComment
+  TAG = /(\w+)='([^']*)'/
+
+  def self.tags(query)
+    comment = query.to_s[%r{/\*([^*]*=[^*]*)\*/}, 1] or return {}
+    comment.scan(TAG).to_h { |key, value| [ key, CGI.unescape(value) ] }
+  end
+
+  # A job always names itself. Otherwise, the endpoint that issued this, if
+  # SQLcommenter tagged it. Otherwise nil -- callers fall back to whatever
+  # else identifies the source (an application_name, or nothing).
+  def self.label(tags)
+    return tags["job"] if tags["job"].present?
+
+    controller = tags["namespaced_controller"] || tags["controller"]
+    return nil if controller.blank?
+
+    [ controller, tags["action"] ].compact_blank.join("#")
+  end
+end