pg_reports 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70975bd7aa15cac037bc8ac3f658c7cabe1e7492a3c37a1db588c92bce3d0f3d
-  data.tar.gz: 587f0a5474d427303c483603467155c4e0602ff604d5628c39e45d7137d1354d
+  metadata.gz: 2ff4489af5016c4bfbe14f7187daa5ca2ea279b15887bab928c8effefc4b2dad
+  data.tar.gz: 26815859090bbf8a84000acb3545c1eecb982887f8d0f07d9ab0e582f2380c58
 SHA512:
-  metadata.gz: 3174ba9362c38d77da9a41653453de23e6c462fac8be71ceacf82b645fffb68343eb09421df8cfbab9f1100d1ca70fbca6234bc3a4450e83e5be9c35079653da
-  data.tar.gz: 70f91b168cc0890414741f75de6aea545400d738ef2a00e5a664a7555aac9bcfd923ba53ce169ca2ffa610efe9dbd95ff26902c77dcbfcf79b872421cf63e644
+  metadata.gz: f94d1f175001f3a8140d8ef9b826d353bb20963d3b75487aace882fde54186466be500840252bc9e87268e55244bb96746f59fd82b6ba648271a828b596b47d4
+  data.tar.gz: f89ff6622a18f3daf33fabf898a8736da510e2ecf84f4455e5720a8a07f3a219ed1336a1f1a286437a23da505560e724679bb27957b74b501567db2cfaee9f17

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-07-03
+
+### Added
+
+- **Standalone mode — run the dashboard without a host Rails app.** A new `pg_reports server` executable (and `rake pg_reports:server` task) boots a minimal Rails application that mounts the engine at `/` and serves it on port **4000**, straight from the gem's root folder. The connection is resolved from `--database-url`, then `DATABASE_URL`, then libpq-style `PG*` env vars; flags cover `--port`, `--host`, `--mount`, and `--server`. All existing multi-database / multi-cluster switching works unchanged, since the connection registry auto-registers the standalone connection as the `:primary` target.
+  - **No new runtime dependencies.** `rack` and `rackup` already ship transitively via `actionpack`/`railties`; the web server (Puma, WEBrick, …) is resolved at run time and is not a hard dependency — the runner uses whichever is installed and prints a clear message if none is.
+  - New `PgReports::Standalone` module encapsulating app construction, connection resolution, and server boot.
+  - `./bin/pg_reports` runs from a checkout without `bundle exec` via a soft bundler shim (activated only when a Gemfile sits next to the executable; skipped for the installed gem).
+  - **[docs/standalone.md](docs/standalone.md).**
+- **Dashboard footer** with links to the project on GitHub and a contact address.
+- **ESC closes any open modal.** A single global handler triggers the modal's own close button, so per-modal cleanup still runs.
+
+### Changed
+
+- **Redesigned the pg_stat_statements status badge.** The header badge now reports four clearly distinguished states with plain-language labels instead of a raw identifier glued to an adjective (`pg_stat_statements готовий`):
+  - 🟢 **Active** — monitoring works.
+  - 🟡 **Preload required** — the extension exists but isn't in `shared_preload_libraries`; clicking the badge opens the setup instructions.
+  - 🟡 **Extension required** — the library is loaded but the extension isn't created; clicking opens a modal with a one-click **Create extension** button.
+  - 🔴 **No connection** — the database itself is unreachable.
+  Warning/error badges are now clickable and self-explanatory. The redundant `?` info button and the header **Create extension** button were removed in favor of the badge-driven modals. Labels no longer use a negative "Not …" framing. Translations updated for `en` / `uk` / `ru`.
+- **pg_stat_statements status detection no longer reads `shared_preload_libraries`.** That setting requires the `pg_read_all_settings` role and is unreadable by a typical monitoring user, which made the "preloaded but extension missing" state unreachable. State is now derived entirely from signals every role can observe: connectivity (`SELECT 1`), extension presence in `pg_extension`, and whether the `pg_stat_statements` view is queryable. `pg_stat_statements_status` gains a `connected:` key, and `PgReports.system.connected?` is a new public helper.
+- **Primary buttons toned down.** `btn-primary` (Start monitoring, Run report, Create extension, …) switched from a solid accent fill to a subtle tinted style, so it reads as the accent action without dominating the page.
+- **Live-metrics "long queries" threshold lowered from 60s to 5s** — the default the top-of-dashboard tile counts against.
+- **Header/layout polish** — the status badge, settings button, and Reset button are unified to the same height; the settings button is now square; the pg_stat_statements category warning banner no longer overhangs its card; and the "scope: host application" note in the query monitor uses a real styled tooltip (hover + keyboard focus) instead of the unreliable native `title`.
+- **README trimmed**: standalone, Telegram, and Grafana/Prometheus details moved to dedicated docs ([docs/standalone.md](docs/standalone.md), [docs/telegram.md](docs/telegram.md), [docs/grafana.md](docs/grafana.md)).
+
+### Fixed
+
+- **Query Monitor no longer records pg_reports' own queries.** Internal queries (live-metrics polling, status checks, database listing) run through `Executor`/`Target` are now tagged with a `"PgReports"` statement name, so `QueryMonitor#should_skip?` filters them by name regardless of backtrace depth. Previously the deep `ActiveSupport::Notifications` stack could push the pg_reports frames past the 30-frame backtrace scan, leaking these queries into the monitor history.
+- **Dashboard requests broke when the engine is mounted at the root path** (e.g. standalone). The client base path resolved to `/`, so `fetch` URLs became `//live_metrics` — a protocol-relative URL the browser sent to a bogus host, breaking live metrics and report runs. The base now strips a trailing slash.
+
 ## [0.8.0] - 2026-05-01
 
 ### Added

data/README.md

@@ -61,6 +61,17 @@ Visit `http://localhost:3000/pg_reports`.
 
 For query analysis, also enable `pg_stat_statements` — see [setup instructions in docs/configuration.md](docs/configuration.md#pg_stat_statements-setup).
 
+## Standalone (no host app)
+
+You can also run the dashboard on its own, straight from the gem's root folder — no Rails app to mount it in. It serves at `/` on port **4000** and connects via `DATABASE_URL` or libpq env vars:
+
+```bash
+./bin/pg_reports server        # from a checkout; no `bundle exec` needed
+DATABASE_URL=postgres://user:pass@localhost/myapp bundle exec pg_reports server
+```
+
+Adds no runtime dependencies to the gem. **[Standalone guide → docs/standalone.md](docs/standalone.md)**
+
 ## Usage
 
 ```ruby
@@ -73,12 +84,9 @@ report = PgReports.expensive_queries
 report.to_text
 report.to_csv
 report.to_a
-
-# Telegram
-PgReports.slow_queries.send_to_telegram
 ```
 
-**[Full list of reports →](docs/reports.md)**
+**[Full list of reports →](docs/reports.md)**  ·  **[Send reports to Telegram →](docs/telegram.md)**
 
 ## Multi-database
 
@@ -100,8 +108,6 @@ PgReports works out of the box once mounted. Common options:
 ```ruby
 # config/initializers/pg_reports.rb
 PgReports.configure do |config|
-  config.telegram_bot_token           = ENV["PG_REPORTS_TELEGRAM_TOKEN"]
-  config.telegram_chat_id             = ENV["PG_REPORTS_TELEGRAM_CHAT_ID"]
   config.slow_query_threshold_ms      = 100
   config.unused_index_threshold_scans = 50
   config.bloat_threshold_percent      = 20
@@ -115,8 +121,8 @@ PgReports.configure do |config|
 end
 ```
 
-**Multi-database, thresholds, query monitor, Grafana, raw query execution, source tracking, locale, Telegram —**
-**[full reference in docs/configuration.md →](docs/configuration.md)**
+**Multi-database, thresholds, query monitor, raw query execution, source tracking, locale —**
+**[full reference in docs/configuration.md →](docs/configuration.md)**  ·  **[Telegram](docs/telegram.md)**  ·  **[Grafana / Prometheus](docs/grafana.md)**
 
 ## Report object
 
@@ -240,66 +246,9 @@ The Export dropdown includes **Copy Prompt** (visible on actionable reports). It
 <details>
 <summary><strong>Grafana / Prometheus exporter</strong></summary>
 
-Expose selected reports at `<mount_point>/metrics` in Prometheus exposition format. The default mount is `/pg_reports`, so the endpoint is typically `/pg_reports/metrics` — but it follows whatever path you used in `mount PgReports::Engine, at: "..."`. Severity (`ok` / `warning` / `critical`) is derived automatically from the thresholds defined in [`Dashboard::ReportsRegistry::REPORT_CONFIG`](lib/pg_reports/dashboard/reports_registry.rb).
-
-```ruby
-PgReports.configure do |config|
-  config.grafana_favorites = [
-    :slow_queries,
-    :unused_indexes,
-    :bloated_tables,
-    :missing_validations,
-    :polymorphic_without_index
-  ]
-  config.grafana_metrics_token = ENV["PG_REPORTS_METRICS_TOKEN"]  # optional bearer token
-  config.grafana_cache_ttl     = 60                                # seconds
-end
-```
-
-Scrape with Prometheus:
-
-```yaml
-scrape_configs:
-  - job_name: pg_reports
-    metrics_path: /pg_reports/metrics    # adjust to your Engine mount point
-    scrape_interval: 60s
-    authorization: { credentials: "${PG_REPORTS_METRICS_TOKEN}" }
-    static_configs:
-      - targets: ["app.internal:3000"]
-```
-
-> [!WARNING]
-> Reports are cached via `Rails.cache` for `grafana_cache_ttl` so frequent scrapes don't hammer the database. Without it, Prometheus' default 15s scrape interval against heavy reports like `missing_validations` will DDoS your own DB. Always set a TTL ≥ scrape interval, and consider a longer per-report TTL for expensive reports.
-
-The exporter also emits a `pg_reports_row` series per report row (each column becomes a Prometheus label), so the auto-generated dashboard can show a **table panel** with the actual rows that need fixing — not just an aggregate count.
-
-Generate a matching Grafana dashboard from the same favorites:
-
-```bash
-bundle exec rake pg_reports:grafana:dashboard
-# writes pg_reports.json in pwd; then Dashboards → Import in Grafana
-```
-
-**[Full Grafana integration guide →](docs/grafana.md)** &nbsp;·&nbsp; **[Local Prometheus + Grafana without Docker →](docs/grafana-local-setup.md)**
-
-</details>
-
-<details>
-<summary><strong>Telegram delivery</strong></summary>
-
-Get a bot token from [@BotFather](https://t.me/BotFather) and your chat ID from [@userinfobot](https://t.me/userinfobot), then:
-
-```ruby
-PgReports.configure do |config|
-  config.telegram_bot_token = "123456:ABC-DEF..."
-  config.telegram_chat_id   = "-1001234567890"
-end
-
-PgReports.slow_queries.send_to_telegram
-PgReports.health_report.send_to_telegram_as_file
-```
+Expose selected reports at `<mount_point>/metrics` in Prometheus exposition format, with severity (`ok` / `warning` / `critical`) derived automatically from each report's thresholds. Reports are cached per a configurable TTL so frequent scrapes don't hammer the database, and a matching Grafana dashboard can be generated from the same favorites (`rake pg_reports:grafana:dashboard`).
 
-Reports under ~50 rows go as a message; larger ones are sent as a file attachment.
+**[Grafana / Prometheus integration guide →](docs/grafana.md)** &nbsp;·&nbsp; **[Local Prometheus + Grafana without Docker →](docs/grafana-local-setup.md)**
 
 </details>
 
@@ -323,8 +272,8 @@ bundle exec rubocop
 
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Acknowledgments
 
-Inspired by [rails-pg-extras](https://github.com/pawurb/rails-pg-extras). UI built with [Claude](https://www.anthropic.com/claude) by Anthropic.
+Inspired by [rails-pg-extras](https://github.com/pawurb/rails-pg-extras) and built with ❤️ for the Rails community.

data/app/controllers/pg_reports/dashboard_controller.rb

@@ -70,7 +70,7 @@ module PgReports
     end
 
     def live_metrics
-      threshold = params[:long_query_threshold]&.to_i || 60
+      threshold = params[:long_query_threshold]&.to_i || 5
 
       # Check if we have access to required statistics
       begin

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

@@ -113,13 +113,32 @@
       display: flex;
       align-items: center;
       gap: 0.4rem;
-      padding: 0.4rem 0.75rem;
+      height: 2.125rem;
+      padding: 0 0.75rem;
       background: var(--bg-tertiary);
       border: 1px solid var(--border-color);
       border-radius: 4px;
       font-size: 0.75rem;
     }
 
+    .header-badge-clickable {
+      cursor: pointer;
+      font-family: inherit;
+      color: inherit;
+      transition: border-color 0.15s ease, background 0.15s ease;
+    }
+
+    .header-badge-clickable:hover {
+      background: var(--bg-card);
+      border-color: var(--text-muted);
+    }
+
+    .badge-info-icon {
+      color: var(--text-muted);
+      font-size: 0.85rem;
+      line-height: 1;
+    }
+
     .badge-dot {
       width: 8px;
       height: 8px;
@@ -306,13 +325,14 @@
     }
 
     .btn-primary {
-      background: var(--accent-purple);
-      color: #fff;
-      border-color: var(--accent-purple);
+      background: rgba(124, 138, 246, 0.14);
+      color: var(--accent-purple);
+      border-color: rgba(124, 138, 246, 0.35);
     }
 
     .btn-primary:hover {
-      background: #6b79e4;
+      background: rgba(124, 138, 246, 0.24);
+      border-color: rgba(124, 138, 246, 0.55);
     }
 
     .btn-secondary {
@@ -634,6 +654,7 @@
     }
 
     .query-monitoring-scope {
+      position: relative;
       font-weight: 400;
       font-size: 0.75rem;
       color: var(--text-muted);
@@ -643,6 +664,40 @@
       cursor: help;
     }
 
+    .query-monitoring-scope::after {
+      content: attr(data-tooltip);
+      position: absolute;
+      top: calc(100% + 8px);
+      left: 0;
+      z-index: 100;
+      width: max-content;
+      max-width: 320px;
+      padding: 0.6rem 0.75rem;
+      background: var(--bg-card);
+      color: var(--text-secondary);
+      border: 1px solid var(--border-color);
+      border-radius: 6px;
+      box-shadow: 0 6px 18px rgba(0, 0, 0, 0.35);
+      font-size: 0.75rem;
+      font-weight: 400;
+      line-height: 1.5;
+      white-space: normal;
+      text-align: left;
+      opacity: 0;
+      visibility: hidden;
+      transform: translateY(-4px);
+      transition: opacity 0.15s ease, transform 0.15s ease;
+      pointer-events: none;
+    }
+
+    .query-monitoring-scope:hover::after,
+    .query-monitoring-scope:focus::after,
+    .query-monitoring-scope:focus-visible::after {
+      opacity: 1;
+      visibility: visible;
+      transform: translateY(0);
+    }
+
     .monitoring-indicator {
       width: 7px;
       height: 7px;
@@ -1000,6 +1055,10 @@
       max-width: 360px;
     }
 
+    .modal-medium {
+      max-width: 560px;
+    }
+
     /* Database selector — used inside .live-monitoring-title and .breadcrumb.
        Sizes to fit its longest option (no artificial cap), capped at the
        parent's available width so it never overruns neighboring controls. */
@@ -1128,7 +1187,10 @@
   <div id="ide-menu" class="ide-menu"></div>
 
   <script>
-    const pgReportsRoot = document.querySelector('meta[name="pg-reports-root"]')?.content || '/pg_reports';
+    // Trailing slash stripped so `${pgReportsRoot}/foo` never becomes `//foo` —
+    // a protocol-relative URL (host "foo") — when the engine is mounted at "/"
+    // (e.g. standalone mode), where the mount path resolves to "/".
+    const pgReportsRoot = (document.querySelector('meta[name="pg-reports-root"]')?.content || '/pg_reports').replace(/\/+$/, '');
     window.PG_REPORTS_I18N = <%= raw I18n.t("pg_reports.ui").to_json %>;
 
     // Format strings with %{var} placeholders
@@ -1137,6 +1199,26 @@
       return template.replace(/%\{(\w+)\}/g, function(_, k) { return vars[k] != null ? vars[k] : ''; });
     };
 
+    // Close the topmost open modal on ESC. Applies to every `.modal` that has a
+    // close (×) button — it triggers that button so each modal's own close
+    // handler (and any cleanup) runs.
+    document.addEventListener('keydown', function(e) {
+      if (e.key !== 'Escape' && e.key !== 'Esc') return;
+      const open = Array.prototype.slice.call(document.querySelectorAll('.modal'))
+        .filter(function(m) {
+          return getComputedStyle(m).display !== 'none' && m.querySelector('.modal-close');
+        });
+      if (!open.length) return;
+      e.preventDefault();
+      const modal = open[open.length - 1];
+      const closeBtn = modal.querySelector('.modal-close');
+      if (closeBtn) {
+        closeBtn.click();
+      } else {
+        modal.style.display = 'none';
+      }
+    });
+
     function showToast(message, type = 'success') {
       const toast = document.getElementById('toast');
       toast.textContent = message;

data/app/views/pg_reports/dashboard/index.html.erb

@@ -27,28 +27,34 @@
       <button class="btn btn-small btn-muted" onclick="showResetConfirmModal()" id="reset-btn">
         <%= t("pg_reports.ui.actions.reset_statistics") %>
       </button>
-    <% else %>
-      <button class="btn btn-small btn-primary" onclick="enablePgStatStatements(this)" id="enable-btn">
-        <%= t("pg_reports.ui.actions.create_extension") %>
-      </button>
-      <button class="btn-info" onclick="showPgStatInfo()">?</button>
     <% end %>
     <button class="btn-info" onclick="showIdeSettingsModal()" title="<%= t("pg_reports.ui.actions.ide_settings_button_title") %>">⚙️</button>
-    <div class="header-badge" id="pg-stat-badge">
-      <% if @pg_stat_status[:ready] %>
+
+    <% if !@pg_stat_status[:connected] %>
+      <div class="header-badge" id="pg-stat-badge">
+        <span class="badge-dot error"></span>
+        <span><%= t("pg_reports.ui.status.disconnected") %></span>
+      </div>
+    <% elsif @pg_stat_status[:ready] %>
+      <div class="header-badge" id="pg-stat-badge">
         <span class="badge-dot"></span>
         <span><%= t("pg_reports.ui.status.pg_stat_ready") %></span>
-      <% elsif @pg_stat_status[:extension_installed] %>
+      </div>
+    <% elsif @pg_stat_status[:extension_installed] %>
+      <button type="button" class="header-badge header-badge-clickable" id="pg-stat-badge"
+              onclick="showPgStatInfo()" title="<%= t("pg_reports.ui.status.click_for_details") %>">
         <span class="badge-dot warning"></span>
-        <span><%= t("pg_reports.ui.status.extension_installed") %></span>
-      <% elsif @pg_stat_status[:preloaded] %>
+        <span><%= t("pg_reports.ui.status.not_preloaded") %></span>
+        <span class="badge-info-icon" aria-hidden="true">ⓘ</span>
+      </button>
+    <% else %>
+      <button type="button" class="header-badge header-badge-clickable" id="pg-stat-badge"
+              onclick="showCreateExtensionModal()" title="<%= t("pg_reports.ui.status.click_for_details") %>">
         <span class="badge-dot warning"></span>
-        <span><%= t("pg_reports.ui.status.preloaded") %></span>
-      <% else %>
-        <span class="badge-dot error"></span>
-        <span><%= t("pg_reports.ui.status.not_configured") %></span>
-      <% end %>
-    </div>
+        <span><%= t("pg_reports.ui.status.extension_missing") %></span>
+        <span class="badge-info-icon" aria-hidden="true">ⓘ</span>
+      </button>
+    <% end %>
   </div>
 </header>
 
@@ -81,6 +87,25 @@ pg_stat_statements.track = all</pre>
   </div>
 </div>
 
+<!-- Create extension modal -->
+<div id="create-extension-modal" class="modal" style="display: none;">
+  <div class="modal-content modal-medium">
+    <div class="modal-header">
+      <h3><%= t("pg_reports.ui.modals.create_extension_title") %></h3>
+      <button class="modal-close" onclick="closeCreateExtensionModal()">×</button>
+    </div>
+    <div class="modal-body">
+      <p><%= t("pg_reports.ui.modals.create_extension_intro") %></p>
+      <pre>CREATE EXTENSION IF NOT EXISTS pg_stat_statements;</pre>
+      <p class="warning-subtext"><%= t("pg_reports.ui.modals.create_extension_note") %></p>
+      <div class="modal-actions">
+        <button class="btn btn-secondary" onclick="closeCreateExtensionModal()"><%= t("pg_reports.ui.actions.cancel") %></button>
+        <button class="btn btn-primary" onclick="enablePgStatStatements(this)" id="modal-create-extension-btn"><%= t("pg_reports.ui.actions.create_extension") %></button>
+      </div>
+    </div>
+  </div>
+</div>
+
 <!-- Reset statistics confirmation modal -->
 <div id="reset-confirm-modal" class="modal" style="display: none;">
   <div class="modal-content modal-small">
@@ -267,7 +292,7 @@ pg_stat_statements.track = all</pre>
     <div class="query-monitoring-title">
       <span class="monitoring-indicator" id="monitor-indicator"></span>
       <span><%= t("pg_reports.ui.monitoring.query_monitor_title") %></span>
-      <span class="query-monitoring-scope" title="<%= t("pg_reports.ui.monitoring.scope_note_long", default: "Query Monitor subscribes to ActiveSupport::Notifications in the host application's process. It captures every SQL the host app runs, on whichever database the host app is connected to. The dashboard's database selector does not change this scope.") %>">
+      <span class="query-monitoring-scope" tabindex="0" data-tooltip="<%= t("pg_reports.ui.monitoring.scope_note_long", default: "Query Monitor subscribes to ActiveSupport::Notifications in the host application's process. It captures every SQL the host app runs, on whichever database the host app is connected to. The dashboard's database selector does not change this scope.") %>">
         <%= t("pg_reports.ui.monitoring.scope_note_short", default: "scope: host application") %>
       </span>
       <span class="session-badge" id="session-badge" style="display: none;">
@@ -363,7 +388,37 @@ pg_stat_statements.track = all</pre>
   <% end %>
 </div>
 
+<footer class="dashboard-footer">
+  <a href="https://github.com/deadalice/pg_reports" target="_blank" rel="noopener noreferrer">github.com/deadalice/pg_reports</a>
+  <span class="footer-sep">·</span>
+  <a href="mailto:deadalice@gmail.com">deadalice@gmail.com</a>
+</footer>
+
 <style>
+  .dashboard-footer {
+    margin-top: 2rem;
+    padding-top: 1.25rem;
+    border-top: 1px solid var(--border-color);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.6rem;
+    flex-wrap: wrap;
+    color: var(--text-muted);
+    font-size: 0.8rem;
+  }
+  .dashboard-footer a {
+    color: var(--text-secondary);
+    text-decoration: none;
+  }
+  .dashboard-footer a:hover {
+    color: var(--accent-purple);
+    text-decoration: underline;
+  }
+  .dashboard-footer .footer-sep {
+    opacity: 0.5;
+  }
+
   .header-actions {
     display: flex;
     align-items: center;
@@ -375,15 +430,26 @@ pg_stat_statements.track = all</pre>
     font-size: 0.8rem;
   }
 
+  /* Keep the header action button the same height as the status badge and
+     the settings button (all 2.125rem); inline-flex centers the label so no
+     vertical padding is needed. */
+  .header-actions .btn {
+    height: 2.125rem;
+    padding: 0 1rem;
+  }
+
   .btn-info {
-    width: 24px;
-    height: 24px;
+    width: 2.125rem;
+    height: 2.125rem;
     padding: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
     background: var(--bg-tertiary);
     color: var(--text-muted);
     border: 1px solid var(--border-color);
-    border-radius: 50%;
-    font-size: 0.8rem;
+    border-radius: 4px;
+    font-size: 0.9rem;
     font-weight: 600;
     cursor: pointer;
     transition: all 0.15s;
@@ -431,7 +497,7 @@ pg_stat_statements.track = all</pre>
 
   .category-warning {
     padding: 0.625rem 1rem;
-    margin: -1.5rem -1.5rem 1rem -1.5rem;
+    margin: -1rem -1rem 1rem -1rem;
     background: rgba(245, 158, 11, 0.1);
     border-bottom: 1px solid rgba(245, 158, 11, 0.2);
     border-radius: 6px 6px 0 0;
@@ -857,6 +923,18 @@ pg_stat_statements.track = all</pre>
     if (e.target === this) closePgStatModal();
   });
 
+  function showCreateExtensionModal() {
+    document.getElementById('create-extension-modal').style.display = 'flex';
+  }
+
+  function closeCreateExtensionModal() {
+    document.getElementById('create-extension-modal').style.display = 'none';
+  }
+
+  document.getElementById('create-extension-modal')?.addEventListener('click', function(e) {
+    if (e.target === this) closeCreateExtensionModal();
+  });
+
   function showResetConfirmModal() {
     document.getElementById('reset-confirm-modal').style.display = 'flex';
   }
@@ -923,6 +1001,7 @@ pg_stat_statements.track = all</pre>
       } else {
         showToast(data.message, 'error');
         if (data.requires_restart) {
+          closeCreateExtensionModal();
           showPgStatInfo();
         }
         button.disabled = false;

data/bin/pg_reports

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Soft bundler shim: when run straight from the gem checkout (a Gemfile sits at
+# the repo root, next to bin/), activate the bundle so the local `lib` and the
+# dev-group web server are on the load path — letting `./bin/pg_reports` work
+# without an explicit `bundle exec`. Installed as a gem there is no Gemfile
+# alongside the executable, so this is skipped and RubyGems resolves everything.
+gemfile = File.expand_path("../Gemfile", __dir__)
+if File.exist?(gemfile) && !defined?(Bundler)
+  ENV["BUNDLE_GEMFILE"] ||= gemfile
+  begin
+    require "bundler/setup"
+  rescue LoadError
+    # Bundler unavailable — fall through and let RubyGems/$LOAD_PATH resolve.
+  end
+end
+
+require "optparse"
+
+options = {
+  port: 4000,
+  host: "127.0.0.1",
+  mount: "/",
+  database_url: nil,
+  server: nil
+}
+
+banner = <<~BANNER
+  pg_reports — self-contained PostgreSQL insights dashboard
+
+  Usage:
+    pg_reports server [options]
+
+  Connection is resolved from --database-url, else DATABASE_URL, else the
+  standard libpq env vars (PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE).
+
+  Options:
+BANNER
+
+parser = OptionParser.new do |o|
+  o.banner = banner
+  o.on("-p", "--port PORT", Integer, "Port to listen on (default: 4000)") { |v| options[:port] = v }
+  o.on("-b", "--host HOST", "Host/interface to bind (default: 127.0.0.1)") { |v| options[:host] = v }
+  o.on("-m", "--mount PATH", "Path to mount the dashboard at (default: /)") { |v| options[:mount] = v }
+  o.on("-d", "--database-url URL", "PostgreSQL connection URL") { |v| options[:database_url] = v }
+  o.on("-s", "--server NAME", "Web server to use (e.g. puma, webrick)") { |v| options[:server] = v }
+  o.on("-h", "--help", "Show this help") do
+    puts o
+    exit
+  end
+  o.on("-v", "--version", "Show version") do
+    require "pg_reports/version"
+    puts PgReports::VERSION
+    exit
+  end
+end
+
+# parse! permutes, so options are recognized before or after the subcommand
+# (e.g. `pg_reports server --port 4055`).
+parser.parse!(ARGV)
+command = ARGV.shift || "server"
+
+case command
+when "server"
+  require "pg_reports"
+  begin
+    PgReports::Standalone.run(
+      port: options[:port],
+      host: options[:host],
+      mount_path: options[:mount],
+      database_url: options[:database_url],
+      server: options[:server]
+    )
+  rescue PgReports::Standalone::ServerUnavailable => e
+    warn e.message
+    exit 1
+  rescue Interrupt
+    warn "\npg_reports: stopped"
+  end
+else
+  warn "Unknown command: #{command.inspect}"
+  warn parser.help
+  exit 1
+end

data/config/locales/en.yml

@@ -633,11 +633,12 @@ en:
         save_for_comparison: "📌 Save for Comparison"
         saved_marker: "📌 Saved"
       status:
-        pg_stat_ready: "pg_stat_statements ready"
-        extension_installed: "Extension installed, not preloaded"
-        preloaded: "Preloaded, extension not created"
-        not_configured: "Not configured"
+        pg_stat_ready: "Active"
+        not_preloaded: "Preload required"
+        extension_missing: "Extension required"
+        disconnected: "No connection"
         monitoring_unavailable: "Status Unavailable"
+        click_for_details: "Click to see how to enable it"
       modals:
         enable_pg_stat_title: "Enable pg_stat_statements"
         enable_pg_stat_intro: "To enable pg_stat_statements, follow these steps:"
@@ -645,6 +646,9 @@ en:
         restart_postgresql: "Restart PostgreSQL:"
         create_extension_step: "Create extension:"
         enable_button_note: "Or click \"Enable\" button after restart."
+        create_extension_title: "Create pg_stat_statements extension"
+        create_extension_intro: "The pg_stat_statements extension isn't created in this database yet. Click below to create it:"
+        create_extension_note: "If the library isn't preloaded, you'll also need to add it to shared_preload_libraries and restart PostgreSQL."
         reset_stats_title: "⚠️ Reset Statistics"
         reset_stats_confirm: "Are you sure you want to reset pg_stat_statements statistics?"
         reset_stats_warning: "This action will clear all collected query statistics and cannot be undone."
@@ -691,7 +695,7 @@ en:
         cache_hit_detail: "heap blocks from cache"
         long_queries_label: "Long Queries"
         queries_unit: "queries"
-        long_running_threshold: "> 60s runtime"
+        long_running_threshold: "> 5s runtime"
         blocked_label: "Blocked"
         processes_unit: "processes"
         waiting_for_locks: "waiting for locks"

data/config/locales/ru.yml

@@ -598,11 +598,12 @@ ru:
         save_for_comparison: "📌 Сохранить для сравнения"
         saved_marker: "📌 Сохранено"
       status:
-        pg_stat_ready: "pg_stat_statements готов"
-        extension_installed: "Расширение установлено, не предзагружено"
-        preloaded: "Предзагружено, расширение не создано"
-        not_configured: "Не настроено"
+        pg_stat_ready: "Активно"
+        not_preloaded: "Требуется предзагрузка"
+        extension_missing: "Требуется расширение"
+        disconnected: "Нет соединения"
         monitoring_unavailable: "Статус недоступен"
+        click_for_details: "Нажмите, чтобы узнать, как включить"
       modals:
         enable_pg_stat_title: "Включение pg_stat_statements"
         enable_pg_stat_intro: "Чтобы включить pg_stat_statements, выполните следующие шаги:"
@@ -610,6 +611,9 @@ ru:
         restart_postgresql: "Перезапустите PostgreSQL:"
         create_extension_step: "Создайте расширение:"
         enable_button_note: "Или нажмите кнопку «Создать расширение» после перезапуска."
+        create_extension_title: "Создание расширения pg_stat_statements"
+        create_extension_intro: "Расширение pg_stat_statements ещё не создано в этой базе данных. Нажмите, чтобы создать его:"
+        create_extension_note: "Если библиотека не предзагружена, её также нужно добавить в shared_preload_libraries и перезапустить PostgreSQL."
         reset_stats_title: "⚠️ Сброс статистики"
         reset_stats_confirm: "Вы уверены, что хотите сбросить статистику pg_stat_statements?"
         reset_stats_warning: "Это действие очистит всю собранную статистику запросов и не может быть отменено."
@@ -656,7 +660,7 @@ ru:
         cache_hit_detail: "блоки heap из кэша"
         long_queries_label: "Долгие запросы"
         queries_unit: "запросов"
-        long_running_threshold: "> 60с выполнения"
+        long_running_threshold: "> 5с выполнения"
         blocked_label: "Заблокировано"
         processes_unit: "процессов"
         waiting_for_locks: "ждут блокировок"

data/config/locales/uk.yml

@@ -598,11 +598,12 @@ uk:
         save_for_comparison: "📌 Зберегти для порівняння"
         saved_marker: "📌 Збережено"
       status:
-        pg_stat_ready: "pg_stat_statements готовий"
-        extension_installed: "Розширення встановлено, не передзавантажено"
-        preloaded: "Передзавантажено, розширення не створено"
-        not_configured: "Не налаштовано"
+        pg_stat_ready: "Активно"
+        not_preloaded: "Потрібне передзавантаження"
+        extension_missing: "Потрібне розширення"
+        disconnected: "Немає з'єднання"
         monitoring_unavailable: "Статус недоступний"
+        click_for_details: "Натисніть, щоб дізнатися, як увімкнути"
       modals:
         enable_pg_stat_title: "Увімкнення pg_stat_statements"
         enable_pg_stat_intro: "Щоб увімкнути pg_stat_statements, виконайте такі кроки:"
@@ -610,6 +611,9 @@ uk:
         restart_postgresql: "Перезапустіть PostgreSQL:"
         create_extension_step: "Створіть розширення:"
         enable_button_note: "Або натисніть кнопку «Створити розширення» після перезапуску."
+        create_extension_title: "Створення розширення pg_stat_statements"
+        create_extension_intro: "Розширення pg_stat_statements ще не створено в цій базі даних. Натисніть, щоб створити його:"
+        create_extension_note: "Якщо бібліотеку не передзавантажено, її також потрібно додати до shared_preload_libraries та перезапустити PostgreSQL."
         reset_stats_title: "⚠️ Скидання статистики"
         reset_stats_confirm: "Ви впевнені, що хочете скинути статистику pg_stat_statements?"
         reset_stats_warning: "Ця дія очистить усю зібрану статистику запитів і не може бути скасована."
@@ -656,7 +660,7 @@ uk:
         cache_hit_detail: "блоки heap із кешу"
         long_queries_label: "Довгі запити"
         queries_unit: "запитів"
-        long_running_threshold: "> 60с виконання"
+        long_running_threshold: "> 5с виконання"
         blocked_label: "Заблоковано"
         processes_unit: "процесів"
         waiting_for_locks: "чекають блокувань"

data/lib/pg_reports/connection/target.rb

@@ -49,7 +49,7 @@ module PgReports
       # 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
+        rows = connection_for.exec_query(<<~SQL, "PgReports").to_a
           SELECT datname AS name,
                  pg_size_pretty(pg_database_size(datname)) AS size
           FROM pg_database

data/lib/pg_reports/executor.rb

@@ -17,10 +17,15 @@ module PgReports
       execute(sql, **params)
     end
 
-    # Execute raw SQL and return results as array of hashes
+    # Execute raw SQL and return results as array of hashes.
+    #
+    # Every query is tagged with the "PgReports" AR statement name so the Query
+    # Monitor can skip our own queries by name (see QueryMonitor#should_skip?),
+    # reliably and independent of backtrace depth — the internal live_metrics /
+    # status polling would otherwise leak into the monitor's history.
     def execute(sql, **params)
       processed_sql = interpolate_params(sql, params)
-      result = connection.exec_query(processed_sql)
+      result = connection.exec_query(processed_sql, "PgReports")
       result.to_a
     end
 

data/lib/pg_reports/modules/system.rb

@@ -44,13 +44,37 @@ module PgReports
         false
       end
 
-      # Get pg_stat_statements status details
+      # Whether the database connection can execute a basic query.
+      # Used to tell "the connection itself is down" apart from
+      # "connected, but pg_stat_statements isn't set up yet".
+      # @return [Boolean]
+      def connected?
+        executor.execute("SELECT 1")
+        true
+      rescue
+        false
+      end
+
+      # Get pg_stat_statements status details.
+      #
+      # Note: whether pg_stat_statements is in shared_preload_libraries cannot be
+      # read by a plain monitoring role (that requires the pg_read_all_settings
+      # role), so we never look at the setting. Instead we derive the state from
+      # signals every role can observe: can we run a query at all, does the
+      # extension exist in pg_extension, and is its view queryable.
+      #
       # @return [Hash] Status information
       def pg_stat_statements_status
+        unless connected?
+          return {connected: false, extension_installed: false, preloaded: false, ready: false}
+        end
+
+        installed = pg_stat_statements_available?
         {
-          extension_installed: pg_stat_statements_available?,
+          connected: true,
+          extension_installed: installed,
           preloaded: pg_stat_statements_preloaded?,
-          ready: pg_stat_statements_available? && pg_stat_statements_preloaded?
+          ready: installed && pg_stat_statements_preloaded?
         }
       end
 
@@ -58,7 +82,7 @@ module PgReports
       # @param long_query_threshold [Integer] Threshold in seconds for long queries
       # @return [Hash] Metrics data
       # @raise [StandardError] If no data is returned
-      def live_metrics(long_query_threshold: 60)
+      def live_metrics(long_query_threshold: 5)
         data = executor.execute_from_file(:system, :live_metrics,
           long_query_threshold: long_query_threshold)
 

data/lib/pg_reports/standalone.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module PgReports
+  # Runs the dashboard as a self-contained application, without a host Rails app.
+  #
+  # It boots a minimal Rails::Application that mounts PgReports::Engine and points
+  # ActiveRecord::Base at a PostgreSQL database, then serves it over HTTP. This is
+  # what powers the `pg_reports server` executable and the `pg_reports:server`
+  # rake task, so the project can be launched straight from the gem's root folder.
+  #
+  # Dependency note: this relies only on gems already pulled in transitively by
+  # the gem's runtime deps (rack via actionpack, rackup via railties). The actual
+  # web server (puma / webrick) is resolved at run time and is NOT a hard
+  # dependency — installed-gem users bring their own.
+  module Standalone
+    extend self
+
+    DEFAULT_PORT = 4000
+    DEFAULT_HOST = "127.0.0.1"
+    DEFAULT_MOUNT = "/"
+
+    # Rack handlers tried, in order, when none is named explicitly.
+    CANDIDATE_SERVERS = %w[puma webrick].freeze
+
+    class ServerUnavailable < PgReports::Error; end
+
+    # Boot the app and start a (blocking) web server.
+    #
+    # @param port [Integer]
+    # @param host [String]
+    # @param mount_path [String] where the engine is mounted (default "/")
+    # @param database_url [String, nil] explicit connection URL; otherwise resolved
+    #   from DATABASE_URL or libpq-style PG* env vars
+    # @param server [String, nil] Rack handler name to force (e.g. "puma")
+    def run(port: DEFAULT_PORT, host: DEFAULT_HOST, mount_path: DEFAULT_MOUNT,
+      database_url: nil, server: nil)
+      # Rails' ActiveRecord railtie reads the connection from DATABASE_URL when no
+      # config/database.yml exists — so we route our resolved connection through
+      # it. The connection registry then auto-registers it as the :primary target,
+      # and database switching / multi-cluster all work unchanged.
+      ENV["DATABASE_URL"] = connection_url(database_url)
+
+      app = build_application(mount_path)
+      app.initialize!
+      verify_connection!
+
+      handler_name, handler = resolve_server(server)
+      banner(host: host, port: port, server: handler_name)
+      handler.run(app, Host: host, Port: port)
+    end
+
+    # Resolve the connection URL. Priority: explicit url > DATABASE_URL >
+    # libpq-style PG* env vars (PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE).
+    def connection_url(explicit = nil)
+      return explicit if explicit && !explicit.empty?
+      return ENV["DATABASE_URL"] if ENV["DATABASE_URL"] && !ENV["DATABASE_URL"].empty?
+
+      require "erb"
+      user = ENV["PGUSER"] || ENV["USER"]
+      password = ENV["PGPASSWORD"]
+      host = ENV["PGHOST"] || "localhost"
+      port = ENV["PGPORT"] || 5432
+      database = ENV["PGDATABASE"] || "postgres"
+
+      userinfo = +""
+      if user && !user.empty?
+        userinfo << ERB::Util.url_encode(user)
+        userinfo << ":#{ERB::Util.url_encode(password)}" if password && !password.empty?
+        userinfo << "@"
+      end
+
+      "postgresql://#{userinfo}#{host}:#{port}/#{ERB::Util.url_encode(database)}"
+    end
+
+    private
+
+    # Build (and register as Rails.application) a minimal Rails app that mounts
+    # the engine. Kept intentionally small: no asset pipeline (views are inline),
+    # cookie sessions for the dashboard's database selector + CSRF.
+    def build_application(mount_path)
+      require "rails"
+      require "action_controller/railtie"
+      require "active_record/railtie"
+      require "tmpdir"
+      # pg_reports.rb only requires the engine when Rails::Engine is already
+      # defined; when loaded outside a Rails app that guard was false, so load it
+      # now that the railties are present. This also registers its initializers.
+      require "pg_reports/engine"
+
+      target_mount = mount_path
+      # A throwaway, empty app root. We must NOT use the gem root here — Rails
+      # would then load the gem's engine config/routes.rb (and config/locales) as
+      # the *application's* own, which double-loads and breaks. The engine loads
+      # those itself relative to its own root; the app only needs the mount below.
+      app_root = Dir.mktmpdir("pg_reports-standalone")
+      at_exit { FileUtils.remove_entry(app_root, true) }
+
+      Class.new(Rails::Application) do
+        config.root = app_root
+        config.eager_load = false
+        config.consider_all_requests_local = true
+        config.secret_key_base = ENV["SECRET_KEY_BASE"] || SecureRandom.hex(64)
+        config.session_store :cookie_store, key: "_pg_reports_session"
+        config.hosts.clear # local tool: don't block by Host header
+        config.logger = ::Logger.new($stdout)
+        config.log_level = (ENV["LOG_LEVEL"] || "info").to_sym
+        config.active_support.report_deprecations = false
+
+        routes.append do
+          mount PgReports::Engine, at: target_mount, as: "pg_reports"
+        end
+      end
+    end
+
+    # Force an actual connection so the user gets a clear error at startup rather
+    # than a 500 on the first request when the database is unreachable.
+    def verify_connection!
+      ActiveRecord::Base.connection
+    rescue => e
+      raise PgReports::Error, "Cannot connect to the database (#{ENV["DATABASE_URL"]}): #{e.message}"
+    end
+
+    # Find a usable Rack handler. Honors an explicit name, otherwise tries the
+    # candidates in order and uses the first that is installed.
+    def resolve_server(name)
+      require "rackup"
+
+      candidates = name ? [name] : CANDIDATE_SERVERS
+      candidates.each do |candidate|
+        handler = begin
+          Rackup::Handler.get(candidate)
+        rescue LoadError, NameError
+          nil
+        end
+        return [candidate, handler] if handler
+      end
+
+      raise ServerUnavailable, <<~MSG.strip
+        No web server found (tried: #{candidates.join(", ")}).
+        Add one to run the standalone dashboard, e.g. `gem install puma`
+        (or add `gem "puma"` to your Gemfile).
+      MSG
+    end
+
+    def banner(host:, port:, server:)
+      url_host = (host == "0.0.0.0") ? "localhost" : host
+      warn "pg_reports: serving dashboard via #{server} on http://#{url_host}:#{port} (Ctrl-C to stop)"
+    end
+  end
+end

data/lib/pg_reports/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgReports
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

data/lib/pg_reports.rb

@@ -43,6 +43,10 @@ require_relative "pg_reports/grafana/dashboard_builder"
 # Rails Engine
 require_relative "pg_reports/engine" if defined?(Rails::Engine)
 
+# Standalone runner (no host app). Only defines methods; the heavy Rails/web
+# requires happen lazily inside PgReports::Standalone.run.
+require_relative "pg_reports/standalone"
+
 module PgReports
   class << self
     # Query analysis methods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_reports
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Eldar Avatov
@@ -140,7 +140,8 @@ description: A comprehensive PostgreSQL monitoring and analysis library that pro
   a beautiful web dashboard and Telegram notifications.
 email:
 - eldar.avatov@gmail.com
-executables: []
+executables:
+- pg_reports
 extensions: []
 extra_rdoc_files: []
 files:
@@ -158,6 +159,7 @@ files:
 - app/views/pg_reports/dashboard/_target_selector.html.erb
 - app/views/pg_reports/dashboard/index.html.erb
 - app/views/pg_reports/dashboard/show.html.erb
+- bin/pg_reports
 - config/locales/en.yml
 - config/locales/ru.yml
 - config/locales/uk.yml
@@ -284,6 +286,7 @@ files:
 - lib/pg_reports/sql/tables/update_hotspots.sql
 - lib/pg_reports/sql/tables/vacuum_needed.sql
 - lib/pg_reports/sql_loader.rb
+- lib/pg_reports/standalone.rb
 - lib/pg_reports/telegram_sender.rb
 - lib/pg_reports/version.rb
 - lib/tasks/pg_reports.rake
@@ -308,7 +311,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 3.6.9
 specification_version: 4
 summary: PostgreSQL analysis and reporting tool with Telegram integration
 test_files: []