pg_peek 0.1.0

data/app/queries/pg_peek/pg18/tables/dead_tuples.sql

@@ -0,0 +1,11 @@
+-- Tables whose dead-tuple share is at or above the warning threshold.
+SELECT
+  relname,
+  n_live_tup,
+  n_dead_tup,
+  round(100.0 * n_dead_tup / NULLIF(n_live_tup + n_dead_tup, 0), 1) AS dead_ratio,
+  last_autovacuum
+FROM pg_stat_user_tables
+WHERE n_live_tup + n_dead_tup > 0
+  AND 100.0 * n_dead_tup / (n_live_tup + n_dead_tup) >= {{threshold}}
+ORDER BY dead_ratio DESC

data/app/queries/pg_peek/pg18/tables/inline_stats.sql

@@ -0,0 +1,9 @@
+SELECT
+  t.relname AS table_name,
+  s.heap_blks_read,
+  s.heap_blks_hit,
+  s.idx_blks_read,
+  s.idx_blks_hit
+FROM pg_stat_user_tables t
+LEFT JOIN pg_statio_user_tables s ON t.relid = s.relid
+WHERE t.relname IN ({{placeholders:count}})

data/app/queries/pg_peek/pg18/tables/stats.sql

@@ -0,0 +1,32 @@
+SELECT
+  t.relname AS table_name,
+  t.seq_scan,
+  t.seq_tup_read,
+  t.idx_scan,
+  t.idx_tup_fetch,
+  t.n_tup_ins,
+  t.n_tup_upd,
+  t.n_tup_del,
+  t.n_live_tup,
+  t.n_dead_tup,
+  t.last_vacuum,
+  t.last_autovacuum,
+  t.last_analyze,
+  t.last_autoanalyze,
+  t.vacuum_count,
+  t.autovacuum_count,
+  t.analyze_count,
+  t.autoanalyze_count,
+  s.heap_blks_read,
+  s.heap_blks_hit,
+  s.idx_blks_read,
+  s.idx_blks_hit,
+  s.toast_blks_read,
+  s.toast_blks_hit,
+  s.tidx_blks_read,
+  s.tidx_blks_hit,
+  c.reltuples AS row_estimate
+FROM pg_stat_user_tables t
+LEFT JOIN pg_statio_user_tables s ON t.relid = s.relid
+LEFT JOIN pg_class c ON t.relid = c.oid
+WHERE t.relname = $1

data/app/reports/pg_peek/column.rb

@@ -0,0 +1,27 @@
+# One column of a report: what to read from a row, how to label it, and how the
+# value should be drawn. Renderers decide what those choices mean -- the HTML
+# table right-aligns, a terminal renderer pads -- so a column stays free of
+# either.
+class PgPeek::Column
+  ALIGNMENTS = %i[left right].freeze
+
+  attr_reader :key, :align, :format, :title
+
+  def initialize(key, header: nil, align: :left, format: :text, title: nil)
+    raise ArgumentError, "unknown alignment #{align.inspect}" unless ALIGNMENTS.include?(align)
+
+    @key = key
+    @header = header
+    @align = align
+    @format = format
+    @title = title
+  end
+
+  def header
+    @header || key.to_s.tr("_", " ")
+  end
+
+  def numeric?
+    align == :right
+  end
+end

data/app/reports/pg_peek/report.rb

@@ -0,0 +1,63 @@
+# A report is columns plus rows, and nothing about how either is drawn.
+#
+# Every angle pg_peek offers -- queries, endpoints, jobs, tables -- is one of
+# these, so a new angle is a subclass and a .sql file rather than a controller,
+# a view and its own styling. It also means a terminal renderer can draw the
+# same report as the HTML one, from the same declaration.
+class PgPeek::Report
+  class Row
+    def initialize(attributes) = @attributes = attributes
+
+    def value(column) = @attributes[column.key.to_s]
+    def [](key) = @attributes[key.to_s]
+    def to_h = @attributes
+  end
+
+  class_attribute :columns, instance_writer: false, default: []
+
+  attr_reader :database
+
+  class << self
+    def title(value = nil)
+      @title = value if value
+      @title || name.demodulize.titleize
+    end
+
+    def column(key, **options)
+      # Subclasses get their own array rather than appending to the parent's.
+      self.columns = columns + [ PgPeek::Column.new(key, **options) ]
+    end
+  end
+
+  # Most reports describe one database. A few -- the database list itself --
+  # describe the set of them, and pass nothing.
+  def initialize(database: nil)
+    @database = database
+  end
+
+  def rows
+    @rows ||= fetch_rows.map { |attributes| Row.new(attributes) }
+  end
+
+  def empty? = rows.empty?
+
+  def title = self.class.title
+
+  # Relative formats -- an intensity bar, a share of total -- need the extent of
+  # the column, not just the cell.
+  def max_for(column)
+    @maxima ||= {}
+    @maxima[column.key] ||= rows.filter_map { |row| row.value(column)&.to_f }.max
+  end
+
+  private
+    # Subclasses return an array of hashes keyed by column name, which is what
+    # PG::Result already yields.
+    def fetch_rows
+      raise NotImplementedError, "#{self.class} must define #fetch_rows"
+    end
+
+    def pg_stat_statements
+      @pg_stat_statements ||= PgPeek::PgStatStatements.new(database: database)
+    end
+end

data/app/reports/pg_peek/reports/blocked.rb

@@ -0,0 +1,60 @@
+# Sessions waiting for a lock, and who holds it. Built from the sessions
+# report rather than a second look at pg_stat_activity, so both tables on the
+# page describe the same instant.
+class PgPeek::Reports::Blocked < PgPeek::Report
+  title "Blocked sessions"
+
+  column :pid, align: :right, title: "The waiting session"
+  column :waiting_for
+  column :duration_ms, header: "for", align: :right, format: :duration_ms, title: "How long the waiting query has run"
+  column :source, title: "Endpoint or job of the waiting session"
+  column :blocked_by, align: :right, title: "The session holding the lock"
+  column :blocker, title: "State and source of the session holding the lock"
+  column :blocker_query, header: "blocker's query", format: :sql
+
+  def initialize(database:, sessions: nil)
+    super(database: database)
+    @sessions = sessions || PgPeek::Reports::Sessions.new(database: database)
+  end
+
+  def any? = rows.any?
+
+  private
+    attr_reader :sessions
+
+    def fetch_rows
+      blocked = sessions.blocked
+      return [] if blocked.empty?
+
+      by_pid = sessions.rows.index_by { |row| row["pid"].to_i }
+      locks = database.waiting_locks.index_by { |row| row["pid"].to_i }
+
+      blocked.map do |row|
+        blockers = row["blocked_by"].map { |pid| by_pid[pid] }.compact
+
+        {
+          "pid" => row["pid"],
+          "waiting_for" => describe(locks[row["pid"].to_i]),
+          "duration_ms" => row["query_ms"],
+          "source" => row["source"],
+          "blocked_by" => row["blocked_by"].join(", "),
+          "blocker" => blockers.map { |b| [ b["state"], b["source"] ].compact_blank.join(" · ") }.join("; ").presence || "a session on another database",
+          "blocker_query" => blockers.map { |b| b["query"] }.compact_blank.join("\n")
+        }
+      end
+    end
+
+    # "access exclusive lock on posts", "advisory lock (exclusive)",
+    # "transactionid lock (share)" -- the last is what a row-level conflict
+    # looks like from pg_locks.
+    def describe(lock)
+      return "a lock" unless lock
+
+      mode = lock["mode"].to_s.delete_suffix("Lock").underscore.tr("_", " ")
+      if lock["relation"].present?
+        "#{mode} lock on #{lock["relation"]}"
+      else
+        "#{lock["locktype"]} lock (#{mode})"
+      end
+    end
+end

data/app/reports/pg_peek/reports/databases.rb

@@ -0,0 +1,47 @@
+# The databases pg_peek can open, and whether each is actually collecting
+# statistics. Whether a database is worth visiting is the question this page
+# answers, so the extension's state belongs in the list rather than behind a
+# click.
+class PgPeek::Reports::Databases < PgPeek::Report
+  title "Databases"
+
+  column :name, header: "database"
+  column :role
+  column :version, align: :right
+  column :statistics, title: "State of the pg_stat_statements extension"
+  column :tables, align: :right, format: :number
+
+  def initialize(databases:)
+    super(database: nil)
+    @databases = databases
+  end
+
+  private
+    def fetch_rows
+      @databases.map do |database|
+        pg_stat = PgPeek::PgStatStatements.new(database: database)
+
+        { "name" => database.name,
+          "role" => role_for(database),
+          "version" => database.version,
+          "statistics" => statistics_for(pg_stat),
+          "tables" => database.tables.size,
+          "database" => database }
+      end
+    end
+
+    def role_for(database)
+      return "primary" if database.primary
+      return "replica" if database.replica
+
+      ""
+    end
+
+    def statistics_for(pg_stat)
+      return "not available" unless pg_stat.available?
+      return "not installed" unless pg_stat.installed?
+      return "not preloaded" unless pg_stat.preloaded?
+
+      "collecting · #{pg_stat.installed_version}"
+    end
+end

data/app/reports/pg_peek/reports/endpoints.rb

@@ -0,0 +1,35 @@
+# Database cost per controller#action, attributed through SQLcommenter tags.
+class PgPeek::Reports::Endpoints < PgPeek::Report
+  title "Endpoints"
+
+  # Above this, a query is running many times per request rather than a few:
+  # the shape of an N+1 rather than a page that legitimately asks twice.
+  N_PLUS_ONE_THRESHOLD = 5
+
+  column :endpoint
+  column :total_exec_time_ms, header: "db time", align: :right, format: :duration_ms
+  column :share, align: :right, format: :intensity, title: "Share of database time across endpoints"
+  column :request_count, header: "requests", align: :right, format: :number,
+                         title: "Estimated from the least-called query of this endpoint"
+  column :total_calls, header: "queries", align: :right, format: :number
+  column :query_count, header: "shapes", align: :right, format: :number
+  column :total_rows, header: "rows", align: :right, format: :number
+  column :max_queries_per_request, header: "q/req", align: :right, format: :ratio,
+                                   title: "Worst queries-per-request in this endpoint. An estimate, not a measurement."
+
+  def self.n_plus_one?(row)
+    row["max_queries_per_request"].to_f >= N_PLUS_ONE_THRESHOLD
+  end
+
+  private
+    def fetch_rows
+      rows = pg_stat_statements.endpoints
+      return [] if rows.blank?
+
+      rows.each do |row|
+        # namespaced_controller arrives url-encoded: staff%2Fprocesses#show.
+        row["endpoint"] = CGI.unescape(row["endpoint"].to_s)
+        row["share"] = row["total_exec_time_ms"]
+      end
+    end
+end

data/app/reports/pg_peek/reports/indexes.rb

@@ -0,0 +1,44 @@
+# Every index in the database, unused ones first. "Unused" means never scanned
+# since the statistics were last reset and not enforcing a constraint --
+# primary keys and unique indexes do their work on writes, whether or not a
+# query ever reads them.
+class PgPeek::Reports::Indexes < PgPeek::Report
+  title "Indexes"
+
+  column :table_name, header: "table"
+  column :index_name, header: "index"
+  column :kind
+  column :size, align: :right
+  column :scans, align: :right, format: :number, title: "Scans since statistics were last reset"
+  column :note
+
+  def unused
+    rows.select { |row| row["unused"] }
+  end
+
+  def unused_bytes
+    unused.sum { |row| row["size_bytes"].to_i }
+  end
+
+  private
+    def fetch_rows
+      rows = database.indexes.reject { |row| PgPeek::Table.excluded?(row["table_name"]) }
+
+      rows.each do |row|
+        primary = truthy?(row["primary_key"])
+        unique = truthy?(row["unique_index"])
+
+        row["kind"] = primary ? "primary key" : (unique ? "unique" : "")
+        row["unused"] = row["scans"].to_i.zero? && !primary && !unique
+        row["note"] = row["unused"] ? "unused" : ""
+      end
+
+      rows.sort_by { |row| [ row["unused"] ? 0 : 1, -row["size_bytes"].to_i, row["table_name"], row["index_name"] ] }
+    end
+
+    # Raw results hand booleans over as "t"/"f" or true/false depending on
+    # the adapter's type map.
+    def truthy?(value)
+      ActiveModel::Type::Boolean.new.cast(value) == true
+    end
+end

data/app/reports/pg_peek/reports/job_queries.rb

@@ -0,0 +1,14 @@
+# The query shapes one job class issues, most expensive first.
+class PgPeek::Reports::JobQueries < PgPeek::Reports::Queries
+  attr_reader :job_class
+
+  def initialize(database:, job_class:)
+    super(database: database)
+    @job_class = job_class
+  end
+
+  private
+    def source_rows
+      pg_stat_statements.outliers_by_job(job_class)
+    end
+end

data/app/reports/pg_peek/reports/jobs.rb

@@ -0,0 +1,21 @@
+# Database cost per ActiveJob class, attributed through the `job` SQLcommenter
+# tag. Queue depth, retries and failures belong to the job backend; this is the
+# database's view of the same jobs.
+class PgPeek::Reports::Jobs < PgPeek::Report
+  title "Jobs"
+
+  column :job_class, header: "job"
+  column :total_exec_time_ms, header: "db time", align: :right, format: :duration_ms
+  column :share, align: :right, format: :intensity, title: "Share of database time across jobs"
+  column :total_calls, header: "queries", align: :right, format: :number
+  column :query_count, header: "shapes", align: :right, format: :number,
+                       title: "Distinct query shapes issued by this job"
+
+  private
+    def fetch_rows
+      rows = pg_stat_statements.jobs
+      return [] if rows.blank?
+
+      rows.each { |row| row["share"] = row["total_exec_time_ms"] }
+    end
+end

data/app/reports/pg_peek/reports/queries.rb

@@ -0,0 +1,23 @@
+# The most expensive query shapes in the database.
+class PgPeek::Reports::Queries < PgPeek::Report
+  title "Queries"
+
+  column :calls, align: :right, format: :intensity, title: "Call count relative to the other queries listed"
+  column :total_exec_time, header: "db time", align: :right, format: :duration
+  column :prop_exec_time, header: "share", align: :right
+  column :avg_exec_ms, header: "avg", align: :right, format: :duration_ms
+  column :query, format: :sql
+
+  private
+    def fetch_rows
+      rows = source_rows
+      return [] if rows.blank?
+
+      # ncalls arrives already formatted with separators; the bar needs a number.
+      rows.each { |row| row["calls"] = row["ncalls"].to_s.delete(",").to_i }
+    end
+
+    def source_rows
+      pg_stat_statements.outliers
+    end
+end

data/app/reports/pg_peek/reports/sessions.rb

@@ -0,0 +1,88 @@
+# Every other client session on the database right now, the busiest first:
+# blocked sessions, then running queries by age, then open transactions by
+# age, then idle connections. Unlike every other report this is a snapshot,
+# not a sum since the last reset.
+class PgPeek::Reports::Sessions < PgPeek::Report
+  title "Sessions"
+
+  HIDDEN_QUERY = "<insufficient privilege>".freeze
+
+  column :pid, align: :right
+  column :state
+  column :duration_ms, header: "for", align: :right, format: :duration_ms,
+         title: "Active: how long the current query has run. Idle in transaction: age of the open transaction. Idle: time since the last query finished."
+  column :wait, title: "What the session is waiting on: another session's lock, IO, its client -- or nothing, which means CPU"
+  column :source, title: "Endpoint or job from the query's SQLcommenter tags, otherwise the application name"
+  column :query, format: :sql
+
+  def active = rows.select { |row| row["state"] == "active" }
+  def idle = rows.select { |row| row["state"] == "idle" }
+  def in_transaction = rows.select { |row| row["state"].to_s.start_with?("idle in transaction") }
+  def blocked = rows.select { |row| row["blocked_by"].any? }
+
+  # Everything an operator would look at; idle connections are a pool doing
+  # its job.
+  def busy = rows.reject { |row| row["state"] == "idle" }
+
+  def long_running(threshold_ms)
+    active.select { |row| row["duration_ms"].to_i >= threshold_ms }
+  end
+
+  def stale_transactions(threshold_ms)
+    in_transaction.select { |row| row["duration_ms"].to_i >= threshold_ms }
+  end
+
+  # PostgreSQL shows a session's query text only to its own user, superusers
+  # and members of pg_read_all_stats. Anything else reads as a placeholder.
+  def hidden_queries?
+    rows.any? { |row| row["query"] == HIDDEN_QUERY }
+  end
+
+  private
+    def fetch_rows
+      rows = database.sessions
+
+      rows.each do |row|
+        row["blocked_by"] = row["blocked_by"].to_s.split(",").map(&:to_i)
+        row["duration_ms"] = duration_for(row)
+        row["wait"] = wait_for(row)
+        row["source"] = source_for(row)
+      end
+
+      rows.sort_by { |row| [ priority(row), -row["duration_ms"].to_i, row["pid"].to_i ] }
+    end
+
+    def priority(row)
+      return 0 if row["blocked_by"].any?
+
+      case row["state"]
+      when "active" then 1
+      when "idle" then 3
+      else 2
+      end
+    end
+
+    # The figure that matters depends on what the session is doing: a running
+    # query's age, an open transaction's age, or how long a connection has
+    # sat unused.
+    def duration_for(row)
+      value = case row["state"]
+      when "active" then row["query_ms"]
+      when "idle" then row["state_ms"]
+      else row["xact_ms"] || row["state_ms"]
+      end
+      value&.to_i
+    end
+
+    def wait_for(row)
+      return "blocked by #{row["blocked_by"].join(", ")}" if row["blocked_by"].any?
+      return "" if row["wait_event_type"].blank?
+
+      "#{row["wait_event_type"].downcase}: #{row["wait_event"]}"
+    end
+
+    def source_for(row)
+      tags = PgPeek::SqlComment.tags(row["query"])
+      PgPeek::SqlComment.label(tags) || row["application_name"].presence || ""
+    end
+end

data/app/reports/pg_peek/reports/tables.rb

@@ -0,0 +1,25 @@
+# Every table in the database with the cache ratios already fetched in one
+# round trip by Table.inline_stats_for.
+class PgPeek::Reports::Tables < PgPeek::Report
+  title "Tables"
+
+  column :name, header: "table"
+  column :heap_hit_ratio, header: "heap cache", align: :right, format: :percent,
+                          title: "Share of heap block reads served from cache"
+  column :index_hit_ratio, header: "index cache", align: :right, format: :percent,
+                           title: "Share of index block reads served from cache"
+
+  private
+    def fetch_rows
+      names = database.tables
+      stats = PgPeek::Table.inline_stats_for(database, names)
+
+      names.map do |name|
+        row = stats[name] || {}
+
+        { "name" => name,
+          "heap_hit_ratio" => row[:heap_hit_ratio],
+          "index_hit_ratio" => row[:index_hit_ratio] }
+      end
+    end
+end

data/app/views/layouts/pg_peek/application.html.erb

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="light">
+  <head>
+    <title>pg_peek</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="light">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= yield :head %>
+
+    <%= stylesheet_link_tag "pg_peek/application", media: "all" %>
+    <%= javascript_include_tag "pg_peek/application", defer: true %>
+  </head>
+  <body>
+    <main>
+      <% if flash[:notice] %><p class="notice"><%= flash[:notice] %></p><% end %>
+      <nav>
+        <ul>
+          <li><%= link_to "pg_peek", databases_path, class: "wordmark" %></li>
+        </ul>
+        <ul>
+          <% if @database %>
+            <li><%= link_to "overview", database_path(@database) %></li>
+            <li><%= link_to "queries", database_queries_path(@database) %></li>
+            <li><%= link_to "endpoints", database_endpoints_path(@database) %></li>
+            <li><%= link_to "jobs", database_jobs_path(@database) %></li>
+            <li><%= link_to "indexes", database_indexes_path(@database) %></li>
+            <li><%= link_to "activity", database_activity_path(@database) %></li>
+            <li class="current-database">
+              <% if switchable_databases.many? %>
+                <span class="switcher">
+                  <select data-switcher aria-label="Switch database">
+                    <% switchable_databases.each do |candidate| %>
+                      <option value="<%= switch_database_path(candidate) %>" <%= "selected" if candidate.name == @database.name %>><%= candidate.name %></option>
+                    <% end %>
+                  </select>
+                </span>
+              <% else %>
+                <%= link_to @database.name, database_path(@database) %>
+              <% end %>
+            </li>
+          <% end %>
+        </ul>
+      </nav>
+
+      <%= yield %>
+    </main>
+
+    <footer class="status">
+      <span>pg_peek <%= PgPeek::VERSION %></span>
+      <a href="https://github.com/trix/pg_peek" rel="noopener noreferrer">source</a>
+      <button type="button" data-theme-toggle aria-label="Toggle theme" title="Press t to toggle">theme: light</button>
+    </footer>
+  </body>
+</html>

data/app/views/pg_peek/activity/show.html.erb

@@ -0,0 +1,70 @@
+<% if @refresh %>
+  <% content_for :head do %><meta http-equiv="refresh" content="<%= @refresh %>"><% end %>
+<% end %>
+
+<div class="toolbar">
+  <h1>activity</h1>
+  <small class="dim">
+    captured <%= @captured_at.strftime("%H:%M:%S") %>
+    &middot; refresh:
+    <% PgPeek::ActivityController::REFRESH_INTERVALS.each do |seconds| %>
+      <%= link_to_unless @refresh == seconds, "#{seconds}s", database_activity_path(@database, refresh: seconds, idle: @show_idle ? 1 : nil) do |name| %><b><%= name %></b><% end %>
+    <% end %>
+    <%= link_to_unless @refresh.nil?, "off", database_activity_path(@database, idle: @show_idle ? 1 : nil) do |name| %><b><%= name %></b><% end %>
+    &middot; <kbd>r</kbd> reloads
+  </small>
+</div>
+
+<p class="vitals dim">
+  <span><%= @summary["client_connections"] %> of <%= @summary["max_connections"] %> server connections in use</span>
+  <span>this database: <%= @sessions.active.size %> active</span>
+  <span><%= @sessions.in_transaction.size %> idle in transaction</span>
+  <span><%= @sessions.idle.size %> idle</span>
+  <% if @blocked.any? %><span><%= @blocked.rows.size %> blocked</span><% end %>
+</p>
+
+<% if @blocked.any? %>
+  <article aria-label="Blocked sessions">
+    <header><%= pluralize(@blocked.rows.size, "session") %> waiting for a lock</header>
+    <%= render "pg_peek/reports/report", report: @blocked %>
+    <footer>
+      <small>
+        pg_peek only looks. To end a query: <code>SELECT pg_cancel_backend(pid)</code>;
+        to drop the whole session: <code>SELECT pg_terminate_backend(pid)</code>.
+      </small>
+    </footer>
+  </article>
+<% end %>
+
+<% if @sessions.hidden_queries? %>
+  <article aria-label="Query text hidden">
+    <header>queries of other users are hidden</header>
+    <p>
+      PostgreSQL shows a session's query only to its own user, superusers and
+      members of <code>pg_read_all_stats</code>. pg_peek connects as
+      <code><%= @summary["username"] %></code>:
+    </p>
+    <pre><code>GRANT pg_read_all_stats TO <%= @summary["username"] %>;</code></pre>
+  </article>
+<% end %>
+
+<% visible = @show_idle ? @sessions.rows : @sessions.busy %>
+
+<h2>
+  sessions
+  <small class="dim">
+    <% if @show_idle %>
+      <%= link_to "hide idle", database_activity_path(@database, refresh: @refresh) %>
+    <% elsif @sessions.idle.any? %>
+      <%= @sessions.idle.size %> idle hidden &middot; <%= link_to "show idle", database_activity_path(@database, refresh: @refresh, idle: 1) %>
+    <% end %>
+  </small>
+</h2>
+
+<% if @sessions.empty? %>
+  <p class="dim">No other session is connected to <%= @database.name %>.</p>
+<% elsif visible.empty? %>
+  <p class="dim">Nothing running. Every other session is idle.</p>
+<% else %>
+  <%= render "pg_peek/reports/report", report: @sessions, rows: visible %>
+<% end %>

data/app/views/pg_peek/authentication_required.html.erb

@@ -0,0 +1,31 @@
+<h1>pg_peek</h1>
+
+<article aria-label="Authentication is not configured">
+  <header>Authentication is not configured</header>
+  <p>
+    pg_peek exposes your schema, every normalized query in the database, and an
+    endpoint that resets query statistics. It refuses to serve
+    <code><%= Rails.env %></code> until you say how it should be protected.
+  </p>
+
+  <p>Either give it credentials, and it will ask for them:</p>
+  <pre><code>PG_PEEK_USERNAME=... PG_PEEK_PASSWORD=...</code></pre>
+  <p>or, equivalently, in <code>config/credentials.yml.enc</code>:</p>
+  <pre><code>pg_peek:
+  username: ...
+  password: ...</code></pre>
+
+  <p>
+    Or, if the engine is already mounted behind your own authentication, say so
+    in <code>config/initializers/pg_peek.rb</code>:
+  </p>
+  <pre><code>config.public_dashboard = true</code></pre>
+
+  <footer>
+    <small>
+      Development and test are exempt, so this never interrupts local work.
+      Credentials, once set, apply everywhere &mdash; including a development
+      server exposed through a tunnel.
+    </small>
+  </footer>
+</article>