pg_peek 0.1.0

data/app/assets/stylesheets/pg_peek/application.css

@@ -0,0 +1,362 @@
+/*
+ * pg_peek — a terminal-shaped stylesheet.
+ *
+ * The data here is durations, counts, percentages and SQL: monospace with
+ * tabular figures makes columns scannable in a way proportional type cannot.
+ * Styling targets semantic elements rather than classes wherever possible, so
+ * views stay plain HTML.
+ */
+
+:root {
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+
+  --bg: #fcfcfa;
+  --panel: #f1f1ec;
+  --fg: #1b1b19;
+  --dim: #6e6e67;
+  --line: #d8d8d1;
+  --accent: #0a5fbf;
+  --warn: #9a5b00;
+  --danger: #b32218;
+  --ok: #17683a;
+}
+
+:root[data-theme="dark"] {
+  --bg: #111312;
+  --panel: #1a1d1c;
+  --fg: #d8dbd8;
+  --dim: #8a8f8b;
+  --line: #2b302e;
+  --accent: #3ee83e;
+  --warn: #e0a24a;
+  --danger: #f0796b;
+  --ok: #3ee83e;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #111312;
+    --panel: #1a1d1c;
+    --fg: #d8dbd8;
+    --dim: #8a8f8b;
+    --line: #2b302e;
+    --accent: #3ee83e;
+    --warn: #e0a24a;
+    --danger: #f0796b;
+    --ok: #3ee83e;
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  padding: 0 1.5rem 3.5rem;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.55;
+  font-variant-numeric: tabular-nums;
+  -webkit-font-smoothing: antialiased;
+}
+
+main { max-width: 120ch; margin: 0 auto; }
+
+/* Header ------------------------------------------------------------------ */
+
+nav {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.75rem 0;
+  border-bottom: 1px solid var(--line);
+  margin-bottom: 1.5rem;
+}
+
+nav ul {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+nav ul:last-of-type { margin-left: auto; }
+nav .wordmark { color: var(--fg); font-weight: 600; }
+
+nav a {
+  color: var(--dim);
+  text-decoration: none;
+  text-transform: lowercase;
+}
+
+nav a:hover, nav a[aria-current] { color: var(--fg); }
+
+nav .current-database { margin-left: 0.5rem; padding-left: 1rem; border-left: 1px solid var(--line); }
+
+.switcher { position: relative; display: inline-block; }
+.switcher::after { content: "▾"; color: var(--dim); position: absolute; right: 0; top: 0; pointer-events: none; }
+
+.switcher select {
+  appearance: none;
+  -webkit-appearance: none;
+  background: none;
+  border: 0;
+  padding: 0 1.4ch 0 0;
+  margin: 0;
+  color: var(--fg);
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+/* Keyboard focus only: after a mouse pick the select keeps focus, and a ring
+   that lingers after every switch reads as a stuck highlight. */
+.switcher select:focus { outline: none; }
+.switcher select:focus-visible { outline: 1px solid var(--accent); outline-offset: 2px; }
+
+/* Type -------------------------------------------------------------------- */
+
+h1, h2, h3 {
+  font-size: 13px;
+  font-weight: 600;
+  margin: 1.75rem 0 0.75rem;
+  letter-spacing: 0.02em;
+  text-transform: lowercase;
+}
+
+p { margin: 0.5rem 0; }
+a { color: var(--accent); }
+strong { font-weight: 600; }
+small { color: var(--dim); }
+
+code {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  padding: 0 0.4ch;
+  font-family: var(--mono);
+}
+
+pre {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  padding: 0.6rem 0.8rem;
+  overflow-x: auto;
+  margin: 0.5rem 0;
+}
+
+pre code { background: none; border: 0; padding: 0; }
+
+/* Tables ------------------------------------------------------------------ */
+
+.scroll { overflow-x: auto; }
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 0.5rem 0;
+}
+
+thead th {
+  text-align: left;
+  font-weight: 600;
+  color: var(--dim);
+  text-transform: lowercase;
+  border-bottom: 1px solid var(--line);
+  padding: 0.35rem 0.75rem 0.35rem 0;
+  white-space: nowrap;
+}
+
+tbody td {
+  vertical-align: top;
+  padding: 0.4rem 0.75rem 0.4rem 0;
+  border-bottom: 1px solid var(--line);
+}
+
+tbody tr:hover td { background: var(--panel); }
+
+/* A table of label/value pairs (e.g. the table detail page): the row header
+   reads like a column header -- dim, plain weight -- and its value lines up
+   right like every other figure. */
+tbody th {
+  text-align: left;
+  font-weight: 400;
+  color: var(--dim);
+  white-space: nowrap;
+  padding: 0.4rem 0.75rem 0.4rem 0;
+  border-bottom: 1px solid var(--line);
+}
+tbody th + td { text-align: right; }
+
+.num { text-align: right; white-space: nowrap; }
+.nowrap { white-space: nowrap; }
+.dim { color: var(--dim); }
+.warn { color: var(--warn); }
+.intensity { white-space: nowrap; }
+.bar { letter-spacing: 0.08em; }
+.bar-on { color: var(--accent); }
+/* Brightness follows the value: a one-segment bar sits at 80%, five at full. */
+.bar-1 .bar-on { opacity: 0.80; }
+.bar-2 .bar-on { opacity: 0.85; }
+.bar-3 .bar-on { opacity: 0.90; }
+.bar-4 .bar-on { opacity: 0.95; }
+.bar-5 .bar-on { opacity: 1; }
+.bar-off { color: var(--line); }
+.sql { word-break: break-all; white-space: pre-wrap; background: none; border: 0; padding: 0; }
+
+/* What issued a query, from its SQLcommenter tags: a link line under the SQL,
+   plus every raw tag behind a disclosure. The page-level details/summary
+   below is a bordered block sized for a whole section; this is one line in a
+   table cell, so it drops the border and shrinks to fit. */
+.sql + .dim { margin-top: 0.25rem; }
+details.tags { border: 0; padding: 0; margin: 0.25rem 0 0; font-size: inherit; }
+details.tags summary { display: inline; }
+details.tags[open] summary { margin-bottom: 0.25rem; }
+
+/* Panels ------------------------------------------------------------------ */
+
+article {
+  border: 1px solid var(--line);
+  background: var(--panel);
+  padding: 0 1rem 0.75rem;
+  margin: 1rem 0;
+}
+
+article > header {
+  margin: 0 -1rem 0.75rem;
+  padding: 0.5rem 1rem;
+  border-bottom: 1px solid var(--line);
+  font-weight: 600;
+}
+
+article > header::before { content: "! "; color: var(--warn); }
+
+article > footer {
+  margin: 0.75rem -1rem 0;
+  padding: 0.5rem 1rem 0;
+  border-top: 1px solid var(--line);
+  color: var(--dim);
+}
+
+article ol, article ul { margin: 0.5rem 0; padding-left: 2.5ch; }
+
+details {
+  border: 1px solid var(--line);
+  padding: 0.4rem 0.75rem;
+  margin: 0.5rem 0;
+}
+
+summary { cursor: pointer; color: var(--dim); }
+summary:hover { color: var(--fg); }
+details[open] summary { color: var(--fg); margin-bottom: 0.5rem; }
+details pre { margin: 0; border: 0; background: none; padding: 0; }
+
+/* Controls ---------------------------------------------------------------- */
+
+input[type="search"] {
+  width: 100%;
+  background: var(--bg);
+  color: var(--fg);
+  border: 1px solid var(--line);
+  padding: 0.4rem 0.75rem;
+  font-family: var(--mono);
+  font-size: 13px;
+}
+
+input[type="search"]:focus { outline: 1px solid var(--accent); border-color: var(--accent); }
+
+button, .button {
+  background: var(--panel);
+  color: var(--fg);
+  border: 1px solid var(--line);
+  padding: 0.3rem 1ch;
+  font-family: var(--mono);
+  font-size: 13px;
+  cursor: pointer;
+}
+
+button:hover { border-color: var(--fg); }
+button.danger { color: var(--danger); border-color: var(--danger); }
+button.danger:hover { background: var(--danger); color: var(--bg); }
+
+form.inline { display: inline; margin: 0; }
+
+.toolbar {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.notice {
+  border: 1px solid var(--ok);
+  color: var(--ok);
+  padding: 0.4rem 0.75rem;
+  margin: 0.75rem 0;
+}
+
+mark { background: var(--accent); color: var(--bg); }
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(28ch, 1fr));
+  gap: 1rem;
+}
+
+.stack > * + * { margin-top: 0.25rem; }
+
+/* Status line ------------------------------------------------------------- */
+
+footer.status {
+  position: fixed;
+  left: 0; right: 0; bottom: 0;
+  display: flex;
+  gap: 2ch;
+  align-items: center;
+  padding: 0.35rem 1.5rem;
+  background: var(--panel);
+  border-top: 1px solid var(--line);
+  color: var(--dim);
+  font-size: 12px;
+}
+
+footer.status a { color: var(--dim); text-decoration: none; }
+footer.status a:hover { color: var(--fg); }
+
+footer.status button {
+  margin-left: auto;
+  background: none;
+  border: 0;
+  padding: 0;
+  color: var(--dim);
+  font-size: 12px;
+}
+
+footer.status button:hover { color: var(--fg); }
+
+/* Overview ---------------------------------------------------------------- */
+
+.vitals { margin: 0 0 1rem; }
+.vitals span + span::before { content: " · "; color: var(--line); }
+
+.panels {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0 2rem;
+}
+
+.panels > section { min-width: 0; }
+.panels > section.wide { grid-column: 1 / -1; }
+.panels h2 { margin-top: 1.25rem; }
+.panels h2 a { color: var(--dim); font-weight: normal; margin-left: 1ch; text-decoration: none; }
+.panels h2 a:hover { color: var(--fg); }
+
+.attention { list-style: none; margin: 0; padding: 0; }
+.attention li { padding: 0.3rem 0; border-bottom: 1px solid var(--line); }
+.attention li::before { content: "! "; color: var(--warn); }
+.attention .ok::before { content: "✓ "; color: var(--ok); }
+
+@media (max-width: 90ch) { .panels { grid-template-columns: 1fr; } }
+[hidden] { display: none !important; }

data/app/controllers/pg_peek/activity_controller.rb

@@ -0,0 +1,16 @@
+# What is happening right now, as opposed to what has been expensive since the
+# last reset. Needs no pg_stat_statements, so it works on any install.
+class PgPeek::ActivityController < PgPeek::ApplicationController
+  REFRESH_INTERVALS = [ 5, 15, 60 ].freeze
+
+  def show
+    @database = PgPeek::Database.find(params[:database_id]) or raise ActiveRecord::RecordNotFound, "Database not found"
+    @sessions = PgPeek::Reports::Sessions.new(database: @database)
+    @blocked = PgPeek::Reports::Blocked.new(database: @database, sessions: @sessions)
+    @summary = @database.connection_summary
+    @captured_at = Time.zone.now
+    # Only the offered intervals are honoured: a URL cannot make the page hammer the server.
+    @refresh = REFRESH_INTERVALS.find { |seconds| seconds == params[:refresh].to_i }
+    @show_idle = params[:idle].present?
+  end
+end

data/app/controllers/pg_peek/application_controller.rb

@@ -0,0 +1,36 @@
+class PgPeek::ApplicationController < ActionController::Base
+  layout "pg_peek/application"
+
+  # Host applications may set include_all_helpers = false, which limits a
+  # controller to its own matching helper.
+  helper PgPeek::ApplicationHelper, PgPeek::ReportHelper
+  helper_method :switchable_databases
+
+  before_action :authenticate
+
+  private
+    def switchable_databases
+      @switchable_databases ||= PgPeek::Database.all.select(&:configured?)
+    end
+
+    # Resolved per request rather than when this class is loaded, so credentials
+    # set after boot are honoured instead of silently ignored.
+    #
+    # Credentials win over the local exemption: a tunnelled development server
+    # is reachable, and setting them is how you protect it.
+    def authenticate
+      return if PgPeek.config.public_dashboard
+      return request_http_basic_credentials if PgPeek.config.credentials?
+      return if Rails.env.local?
+
+      render template: "pg_peek/authentication_required", status: :forbidden
+    end
+
+    def request_http_basic_credentials
+      authenticate_or_request_with_http_basic("PgPeek") do |username, password|
+        # & rather than && so both comparisons always run.
+        ActiveSupport::SecurityUtils.secure_compare(username, PgPeek.config.username) &
+          ActiveSupport::SecurityUtils.secure_compare(password, PgPeek.config.password)
+      end
+    end
+end

data/app/controllers/pg_peek/databases_controller.rb

@@ -0,0 +1,96 @@
+class PgPeek::DatabasesController < PgPeek::ApplicationController
+  OVERVIEW_ROWS = 5
+
+  def index
+    @databases = PgPeek::Database.all
+    # Resolved once: each miss logs a warning, and the view needs the answer
+    # twice -- to list what works and to explain what does not.
+    @configured_databases = @databases.select(&:connection_configured?)
+    @report = PgPeek::Reports::Databases.new(databases: @configured_databases)
+  end
+
+  # Root. The primary's overview is what nearly everyone came for; the list of
+  # databases is one click away as a switcher.
+  def home
+    configured = PgPeek::Database.all.select(&:connection_configured?)
+    landing = configured.find(&:primary) || configured.first
+
+    redirect_to landing ? database_path(landing) : databases_path
+  end
+
+  def show
+    @database = PgPeek::Database.find(params[:id]) or raise ActiveRecord::RecordNotFound, "Database not found"
+    @pg_stat_statements = PgPeek::PgStatStatements.new(database: @database)
+    @tables = PgPeek::Reports::Tables.new(database: @database)
+    @vitals = @database.vitals
+    @stats_reset_at = @pg_stat_statements.reset_at
+    @sessions = PgPeek::Reports::Sessions.new(database: @database)
+    @connection_summary = @database.connection_summary
+
+    if @pg_stat_statements.usable?
+      @endpoints = PgPeek::Reports::Endpoints.new(database: @database)
+      @jobs = PgPeek::Reports::Jobs.new(database: @database)
+      @queries = PgPeek::Reports::Queries.new(database: @database)
+    end
+
+    @attention = attention
+  end
+
+  private
+    # Computed, not browsed: the things worth acting on, each linking to where
+    # you would act.
+    def attention
+      items = []
+
+      ratio = @vitals["cache_hit_ratio"]&.to_f
+      threshold = PgPeek.config.cache_hit_warning_threshold
+      if ratio && ratio < threshold
+        items << { text: "cache hit ratio #{ratio}% (below #{threshold}%)", href: nil }
+      end
+
+      @database.tables_with_dead_tuples(PgPeek.config.dead_tuple_warning_threshold).each do |table|
+        vacuumed = table["last_autovacuum"] ? "last autovacuum #{helpers.time_ago_in_words(table["last_autovacuum"])} ago" : "never autovacuumed"
+        items << { text: "#{table["relname"]}: #{table["dead_ratio"]}% dead tuples, #{vacuumed}",
+                   href: database_table_path(@database, table["relname"]) }
+      end
+
+      indexes = PgPeek::Reports::Indexes.new(database: @database)
+      if indexes.unused.any?
+        items << { text: "#{helpers.pluralize(indexes.unused.size, "unused index")} · #{helpers.number_to_human_size(indexes.unused_bytes)}",
+                   href: database_indexes_path(@database) }
+      end
+
+      activity = database_activity_path(@database)
+
+      if @sessions.blocked.any?
+        items << { text: "#{helpers.pluralize(@sessions.blocked.size, "session")} waiting for a lock", href: activity }
+      end
+
+      seconds = PgPeek.config.long_query_warning_seconds
+      long_running = @sessions.long_running(seconds * 1000)
+      if long_running.any?
+        items << { text: "#{helpers.pluralize(long_running.size, "query")} running longer than #{seconds}s, longest #{helpers.format_duration_from_ms(long_running.first["duration_ms"])}",
+                   href: activity }
+      end
+
+      seconds = PgPeek.config.idle_in_transaction_warning_seconds
+      stale = @sessions.stale_transactions(seconds * 1000)
+      if stale.any?
+        items << { text: "#{helpers.pluralize(stale.size, "session")} idle in transaction for over #{seconds}s -- holding locks and blocking vacuum",
+                   href: activity }
+      end
+
+      used = @connection_summary["client_connections"].to_i
+      max = @connection_summary["max_connections"].to_i
+      if max.positive? && used >= max * 0.8
+        items << { text: "#{used} of #{max} connections in use", href: activity }
+      end
+
+      if @stats_reset_at && @stats_reset_at > 1.hour.ago
+        items << { text: "statistics were reset #{helpers.time_ago_in_words(@stats_reset_at)} ago -- figures may not be representative yet",
+                   href: database_path(@database, anchor: "pg_stat_statements") }
+      end
+
+      items
+    end
+end

data/app/controllers/pg_peek/endpoints_controller.rb

@@ -0,0 +1,10 @@
+class PgPeek::EndpointsController < PgPeek::ApplicationController
+  def index
+    @database = PgPeek::Database.find(params[:database_id])
+    @pg_stat_statements = PgPeek::PgStatStatements.new(database: @database)
+
+    return render "pg_peek/pg_stat_statements/not_preloaded" unless @pg_stat_statements.usable?
+
+    @report = PgPeek::Reports::Endpoints.new(database: @database)
+  end
+end

data/app/controllers/pg_peek/indexes_controller.rb

@@ -0,0 +1,7 @@
+class PgPeek::IndexesController < PgPeek::ApplicationController
+  def index
+    @database = PgPeek::Database.find(params[:database_id]) or raise ActiveRecord::RecordNotFound, "Database not found"
+    @report = PgPeek::Reports::Indexes.new(database: @database)
+    @stats_reset_at = @database.stats_reset_at
+  end
+end

data/app/controllers/pg_peek/jobs_controller.rb

@@ -0,0 +1,44 @@
+class PgPeek::JobsController < PgPeek::ApplicationController
+  before_action :set_database
+  before_action :require_sqlcommenter_tags
+
+  def index
+    return render "pg_peek/pg_stat_statements/not_preloaded" unless @pg_stat_statements.usable?
+
+    # Without the job tag no query can be attributed to a job, so an empty
+    # dashboard has nothing to do with whether jobs have run.
+    @job_tag_configured = query_log_tags.include?(:job)
+    @stats_reset_at = @pg_stat_statements.reset_at
+    @report = PgPeek::Reports::Jobs.new(database: @database)
+  end
+
+  def show
+    @job_class = CGI.unescape(params[:job_class])
+    return render "pg_peek/pg_stat_statements/not_preloaded" unless @pg_stat_statements.usable?
+
+    @report = PgPeek::Reports::JobQueries.new(database: @database, job_class: @job_class)
+  end
+
+  private
+    def set_database
+      @database = PgPeek::Database.find(params[:database_id]) or
+        raise ActiveRecord::RecordNotFound, "Database not found"
+      @pg_stat_statements = PgPeek::PgStatStatements.new(database: @database)
+    end
+
+    def query_log_tags
+      Rails.application.config.active_record.query_log_tags.to_a
+    end
+
+    def require_sqlcommenter_tags
+      config = Rails.application.config.active_record
+
+      unless config.query_log_tags_enabled
+        return render plain: "Query log tags are not enabled. Please enable config.active_record.query_log_tags_enabled in your Rails configuration.", status: :unprocessable_entity
+      end
+
+      if config.query_log_tags_format == :legacy
+        render plain: "Legacy query log tags format is not supported. Please set config.active_record.query_log_tags_format to :sqlcommenter in your Rails configuration.", status: :unprocessable_entity
+      end
+    end
+end

data/app/controllers/pg_peek/pg_stat_statements_controller.rb

@@ -0,0 +1,11 @@
+# Manages the extension itself. What it records is read by QueriesController,
+# EndpointsController and JobsController.
+class PgPeek::PgStatStatementsController < PgPeek::ApplicationController
+  def reset
+    @database = PgPeek::Database.find(params[:database_id]) or raise ActiveRecord::RecordNotFound, "Database not found"
+    PgPeek::PgStatStatements.new(database: @database).reset!
+
+    redirect_to database_path(@database, anchor: "pg_stat_statements"),
+                notice: "pg_stat_statements has been reset."
+  end
+end

data/app/controllers/pg_peek/queries_controller.rb

@@ -0,0 +1,13 @@
+# https://docs.percona.com/pg-stat-monitor/comparison.html
+class PgPeek::QueriesController < PgPeek::ApplicationController
+  def index
+    @database = PgPeek::Database.find(params[:database_id]) or raise ActiveRecord::RecordNotFound, "Database not found"
+    @pg_stat_statements = PgPeek::PgStatStatements.new(database: @database)
+
+    # The extension can be installed while the module was never preloaded, in
+    # which case querying its views raises instead of returning rows.
+    return render "pg_peek/pg_stat_statements/not_preloaded" unless @pg_stat_statements.usable?
+
+    @queries = PgPeek::Reports::Queries.new(database: @database)
+  end
+end

data/app/controllers/pg_peek/tables_controller.rb

@@ -0,0 +1,6 @@
+class PgPeek::TablesController < PgPeek::ApplicationController
+  def show
+    @database = PgPeek::Database.find(params[:database_id]) or raise ActiveRecord::RecordNotFound, "Database not found"
+    @table = @database.find_table(params[:name]) or raise ActiveRecord::RecordNotFound, "Table '#{params[:name]}' not found"
+  end
+end