pg_peek 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: edfdc4a86128d1eec3f1c69e731780b9ef71afdd071d76cde2756eee57d55ff8
+  data.tar.gz: 666c7f0204c05e295f6c6950e32362720e273d579ec3eec6c557fd2769ab14c0
+SHA512:
+  metadata.gz: 4ecde1526a25bd02fe30c47dbbe62ff2058ce2d8f6b1ff741ffd50b2eea26236e102646f98b67dabf4d9f6d566717a838c04c15be895d5d3b335a59bde342945
+  data.tar.gz: 44fa0fbf8d8ccd408c9e967b78ec29503fc94f605beb961cdc8480137773e7b6145af740990c039ac4f09be1c7664d03c204290190c0f9cd94a1e674b9517d15

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Tomasz Mazur
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,217 @@
+# PgPeek
+
+A Rails Engine that provides a web UI for monitoring and analyzing PostgreSQL query performance. Mount it into your Rails application for easy database introspection and slow query analysis.
+
+## Features
+
+- **Database Overview**: View PostgreSQL version, installed extensions, and table listings
+- **Query Performance Analysis**: Identify slow queries using the `pg_stat_statements` extension
+- **SQLcommenter Support**: Parses and displays SQLcommenter tags from queries
+- **Endpoint and Active Job Breakdowns**: Groups query cost by controller/action and by job class, with a per-job drill-down into its query shapes
+- **Multi-Database Support**: Works with multiple database configurations (primary, replica, etc.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "pg_peek"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Then run the installer, which mounts the engine at `/pg_peek` and creates the
+initializer:
+
+```bash
+bin/rails generate pg_peek:install
+```
+
+Pass `--skip-routes` if you would rather mount the engine yourself, for example
+inside an authenticated scope.
+
+Now map each database in your `database.yml` to the ActiveRecord class that
+connects to it:
+
+```ruby
+# config/initializers/pg_peek.rb
+Rails.application.config.pg_peek.tap do |config|
+  config.connections = {
+    "primary" => "ApplicationRecord"
+  }
+end
+```
+
+This step is required. A database without an entry cannot be opened and is not
+listed.
+
+Visit `/pg_peek` in your application to access the dashboard.
+
+### Authentication
+
+pg_peek exposes your schema, every normalized query in the database, and an
+endpoint that resets query statistics. Outside development and test it refuses
+to serve until you say how it is protected.
+
+Give it credentials and it asks for them over HTTP basic:
+
+```bash
+PG_PEEK_USERNAME=peek PG_PEEK_PASSWORD=...
+```
+
+or equivalently in `config/credentials.yml.enc`:
+
+```yaml
+pg_peek:
+  username: peek
+  password: ...
+```
+
+Credentials, once set, apply in **every** environment — including a development
+server exposed through a tunnel.
+
+If you would rather mount the engine behind authentication you already have, say
+so and pg_peek stays out of the way:
+
+```ruby
+# config/initializers/pg_peek.rb
+config.public_dashboard = true
+```
+
+```ruby
+# config/routes.rb
+constraints ->(request) { request.session[:admin_id].present? } do
+  mount PgPeek::Engine, at: "/pg_peek"
+end
+```
+
+Development and test are exempt when no credentials are set, so local work is
+never interrupted.
+
+### Enabling pg_stat_statements
+
+Query analysis needs the `pg_stat_statements` extension, and enabling it is two
+separate steps on two different things. Doing only the first is the most common
+way to end up with a dashboard that shows nothing.
+
+**1. Load the module into the server.** This is PostgreSQL configuration, not
+database state: a migration cannot do it, and it takes effect only after a
+restart.
+
+```sql
+ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
+```
+
+or the equivalent line in `postgresql.conf`. Then restart PostgreSQL. On a
+managed service this is usually a parameter-group setting; in Docker, pass
+`-c shared_preload_libraries=pg_stat_statements` to the server command.
+
+**2. Create the extension in each database.** A migration, so it is tracked in
+your schema and applied per environment:
+
+```ruby
+class EnablePgStatStatements < ActiveRecord::Migration[8.1]
+  def change
+    enable_extension "pg_stat_statements"
+  end
+end
+```
+
+For a secondary database, generate it into that database's migrations path:
+
+```bash
+bin/rails generate migration EnablePgStatStatements --database analytics
+```
+
+If you do step 2 without step 1, the extension reports itself as installed but
+its views cannot be queried. pg_peek detects this and shows the instructions
+above in place of every page that needs statistics, so you will not be left
+guessing — but you will be left waiting for a restart.
+
+A restart also clears all collected statistics, so expect an empty dashboard
+until your application has run for a while afterwards.
+
+### Requirements
+
+- Rails 8.1+
+- PostgreSQL 14+ with `pg_stat_statements` extension (for query analysis features)
+- Only officially supported PostgreSQL versions are supported
+
+### Why not pg_stat_monitor?
+
+pg_peek reads `pg_stat_statements` only. This is deliberate, not an omission.
+
+Percona's `pg_stat_monitor` has two genuine advantages: it parses SQLcommenter
+tags into a column of their own, and it keeps time-bucketed history rather than
+one counter since the last reset. Both would simplify this engine.
+
+But it is not part of PostgreSQL's contrib, so it is unavailable on Heroku and
+most managed PostgreSQL. And its bucketed figures are not comparable with
+`pg_stat_statements`' cumulative ones: supporting both would give two different
+answers to "what does this endpoint cost" depending on which extension happened
+to be installed. One data source that works everywhere beats two that disagree.
+
+## Development
+
+### Prerequisites
+
+- Ruby (see `.ruby-version`)
+- Docker and Docker Compose (for PostgreSQL)
+
+### Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Start PostgreSQL 18 (default for development)
+docker compose up postgres18 -d
+
+# Setup the dummy app database
+bin/rails db:setup
+
+# Start the development server
+bin/rails s
+
+# Visit http://localhost:3000/pg_peek
+```
+
+### Testing Against Other PostgreSQL Versions
+
+```bash
+# Run databases
+docker compose up -d
+
+# PostgreSQL 14
+bin/test-pg14
+
+# PostgreSQL 15
+bin/test-pg15
+
+# PostgreSQL 16
+bin/test-pg16
+
+# PostgreSQL 17
+bin/test-pg17
+
+# PostgreSQL 18
+bin/test-pg18
+```
+
+## Testing
+
+```bash
+# Run the full test suite
+bin/test
+
+# Code style check
+bin/rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/javascripts/pg_peek/application.js

@@ -0,0 +1,147 @@
+// pg_peek — no framework, no CDN, no import map. Three small behaviours.
+(function () {
+  "use strict";
+
+  // Theme -------------------------------------------------------------------
+  function applyTheme(theme) {
+    document.documentElement.dataset.theme = theme;
+
+    var meta = document.querySelector('meta[name="color-scheme"]');
+    if (meta) meta.content = theme;
+
+    document.querySelectorAll("[data-theme-toggle]").forEach(function (button) {
+      button.textContent = "theme: " + theme;
+    });
+  }
+
+  function storedTheme() {
+    try {
+      return localStorage.getItem("pg_peek.theme");
+    } catch (error) {
+      return null; // Private windows and blocked site data both throw.
+    }
+  }
+
+  function toggleTheme() {
+    var next = document.documentElement.dataset.theme === "dark" ? "light" : "dark";
+    applyTheme(next);
+    try {
+      localStorage.setItem("pg_peek.theme", next);
+    } catch (error) {
+      /* Nothing to do: the toggle still works for this page view. */
+    }
+  }
+
+  function typing() {
+    var el = document.activeElement;
+    return el && (el.tagName === "INPUT" || el.tagName === "TEXTAREA");
+  }
+
+  function initTheme() {
+    var preferred = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    applyTheme(storedTheme() || preferred);
+
+    document.querySelectorAll("[data-theme-toggle]").forEach(function (button) {
+      button.addEventListener("click", function (event) {
+        event.preventDefault();
+        toggleTheme();
+      });
+    });
+
+    document.addEventListener("keydown", function (event) {
+      if (event.key === "t" && !typing() && !event.metaKey && !event.ctrlKey) toggleTheme();
+    });
+  }
+
+  // Filtering ---------------------------------------------------------------
+  function initFilter() {
+    var input = document.querySelector("[data-filter-input]");
+    if (!input) return;
+
+    // Scoped to the nearest [data-filter] ancestor when there is one, so a
+    // page with several report tables -- the overview, with endpoints, jobs,
+    // queries and tables all on it -- filters only the one the input actually
+    // belongs to, rather than every row on the page.
+    var scope = input.closest("[data-filter]") || document;
+    var items = Array.prototype.slice.call(scope.querySelectorAll("[data-filter-value]"));
+    var count = scope.querySelector("[data-filter-count]");
+    var empty = scope.querySelector("[data-filter-empty]");
+    var noun = input.dataset.filterNoun || "row";
+    var timer;
+
+    function render() {
+      var query = input.value.trim().toLowerCase();
+      var matched = 0;
+
+      items.forEach(function (item) {
+        var hit = !query || item.dataset.filterValue.indexOf(query) !== -1;
+        item.hidden = !hit;
+        if (hit) matched++;
+      });
+
+      if (count) count.textContent = matched + " " + noun + (matched === 1 ? "" : "s");
+      if (empty) empty.hidden = matched > 0;
+    }
+
+    input.addEventListener("input", function () {
+      clearTimeout(timer);
+      timer = setTimeout(render, 120);
+    });
+
+    document.addEventListener("keydown", function (event) {
+      if (event.key === "/" && document.activeElement !== input) {
+        event.preventDefault();
+        input.focus();
+      } else if (event.key === "Escape" && document.activeElement === input) {
+        input.value = "";
+        render();
+      }
+    });
+
+    render();
+  }
+
+  // Confirmation ------------------------------------------------------------
+  // Previously data-confirm, which needed rails-ujs the engine never shipped:
+  // the reset button asked nothing and simply reset.
+  function initConfirm() {
+    document.querySelectorAll("form[data-confirm]").forEach(function (form) {
+      form.addEventListener("submit", function (event) {
+        if (!window.confirm(form.dataset.confirm)) event.preventDefault();
+      });
+    });
+  }
+
+  // Database switcher -------------------------------------------------------
+  function initSwitcher() {
+    document.querySelectorAll("[data-switcher]").forEach(function (select) {
+      select.addEventListener("change", function () {
+        window.location.assign(select.value);
+      });
+    });
+  }
+
+  // Reload ------------------------------------------------------------------
+  // The activity page is a snapshot; "r" refreshes it the way top does.
+  function initReload() {
+    document.addEventListener("keydown", function (event) {
+      if (event.key === "r" && !typing() && !event.metaKey && !event.ctrlKey && !event.altKey) {
+        window.location.reload();
+      }
+    });
+  }
+
+  function init() {
+    initTheme();
+    initFilter();
+    initConfirm();
+    initSwitcher();
+    initReload();
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", init);
+  } else {
+    init();
+  }
+})();