pg_reports 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff4489af5016c4bfbe14f7187daa5ca2ea279b15887bab928c8effefc4b2dad
-  data.tar.gz: 26815859090bbf8a84000acb3545c1eecb982887f8d0f07d9ab0e582f2380c58
+  metadata.gz: 8a307810bc4ac9d34917eddd4d3a231a4a9fd0010f2b8bd1d1f56a654336028b
+  data.tar.gz: 175e0568589ca06b81a7482550d6eb1e3bfe05089ea1fda74b47fc33901aa4d0
 SHA512:
-  metadata.gz: f94d1f175001f3a8140d8ef9b826d353bb20963d3b75487aace882fde54186466be500840252bc9e87268e55244bb96746f59fd82b6ba648271a828b596b47d4
-  data.tar.gz: f89ff6622a18f3daf33fabf898a8736da510e2ecf84f4455e5720a8a07f3a219ed1336a1f1a286437a23da505560e724679bb27957b74b501567db2cfaee9f17
+  metadata.gz: 2f817ec173d59b77e7a70ec69b15292bd9a7eb9e074d7c5edd1cd82003f76bd382efdecc754313a453e5f851d3c1bd5c447cf6bd29723afae49110f49e95631e
+  data.tar.gz: 7188d4caa875624d210c4b00fbd4d3e3046b0df7bce877b5484d3ebad919d8a19df908e6c923fe2f48ac62e0595cfa5a48699accfccfc5c4cb4bc603e9dba5db

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-16
+
+### Changed
+- **The CI matrix now resolves against committed lockfiles.** `gemfiles/*.gemfile.lock` were gitignored, so every matrix job re-resolved dependencies from scratch and drifted with whatever was newest on the day — which is how the Rails 6.1 job silently moved onto a json 3.x that ActiveSupport 6.1 cannot use, turning green builds red with no code change. Each lockfile is generated with that entry's own Ruby and pinned to the runner's `x86_64-linux` platform. The Rails 6.1 lockfile deliberately pins json 3.0.2, so the incompatibility that started this stays covered rather than being pinned away.
+- **Updated `json`, `loofah` and `rails-html-sanitizer`** in the root lockfile to clear open advisories (`bundler-audit`).
+- **Dashboard visual overhaul — a single design system instead of three drifting stylesheets.** The three `<style>` blocks (layout, `index`, `_show_styles`) had grown independent, conflicting copies of the same components: `.modal-close` was 28px in one and 32px in another, `.modal-small` was 360px and 420px, `.toast` and the whole `.btn` family were defined twice with different colours, and `.explain-stats` / `.explain-result` were each declared twice within one file. All shared components now live once in the layout, and the per-page blocks only hold what is genuinely page-specific. `_show_styles.html.erb` shrank from 1678 to ~1500 lines with no loss of coverage.
+  - **Design tokens.** New `:root` tokens for radii (`--radius-sm`/`--radius`/`--radius-lg`), control height, shadows, fonts, and an accent-tint scale (`--amber-soft`/`--amber-line`, …) derived from the actual `--accent-*` values. Every hard-coded `rgba()`/hex tint was replaced — many were leftover Tailwind-palette values (`#ef4444`, `rgba(59,130,246,…)`) that no longer matched the accent they bordered.
+  - **Fixed two undeclared variables.** `--text-tertiary` and `--accent-red` were referenced but never defined, so those rules silently fell back to inherited colour; both are now declared. Removed the unused `--accent-indigo`, `--gradient-start` and `--gradient-end`.
+- **Buttons are solid, classic controls.** `.btn-primary` was a translucent tinted outline (`rgba(124,138,246,.14)` fill, accent text, accent border); it is now a filled button with white text, plus proper `:active` and `:focus-visible` states. `.btn-secondary`/`.btn-danger`/`.btn-muted`/`.btn-ghost`/`.btn-icon` share one height, radius and transition, and every variant is declared in exactly one place.
+- **Status is no longer signalled by coloured left stripes.** The live metric cards carried a 3px green/amber/rose `border-left` — "healthy" was as decorated as "critical". Status now reads from the corner dot, the value colour and the sparkline, with the card's own border tinting only for warning and critical. The same treatment replaced the coloured rails and `linear-gradient` washes on EXPLAIN summary cards, problem cards and stat tiles.
+  - Table problem rows used `border-left` on `<tr>`, which does not render under `border-collapse: collapse`; they now use an inset shadow on the first cell, so the marker is actually visible.
+- **Sparkline colour encodes state, not identity.** Each metric drew its trend in its own hue (blue/green/purple/amber/rose), which read as decoration. All five now draw in a muted neutral, switching to amber or rose only when that metric crosses its threshold.
+- **Emoji replaced with an inline SVG icon sprite.** Emoji were used as UI icons throughout — the header logo tile, category and metric icons, the settings gear, lock, play/pause, and as prefixes baked into ~48 locale strings per language (`"📋 Copy"`, `"⬇ Export"`, `"🔒 Requires pg_stat_statements"`). They rendered differently on every OS and could not be coloured. All are now stroke-drawn `<symbol>`s defined once in the layout and referenced with `<use>`, inheriting colour and size from their context. Locale strings carry text only.
+- **Removed the header logo tile.** The wordmark and version carry the branding.
+- **Dropped the decorative motion.** Hover lifts (`translateY(-1px/-2px)`, `translateX(4px)` plus shadow), the glassmorphism `backdrop-filter: blur()` on modals, and the pulsing animation on the static status-badge dot are gone. Non-interactive panels no longer light up in accent purple on hover.
+- **Typography.** Plus Jakarta Sans → Inter, body line-height 1.6 → 1.5, and a consistent type scale for a dense dashboard. Numeric surfaces (result tables, live metric values, EXPLAIN stats) use `tabular-nums` so digits stop reflowing as values refresh.
+- **Accessibility.** Added `:focus-visible` rings on buttons, inputs and textareas; icon-only buttons carry `aria-label`; decorative icons are `aria-hidden`.
+- **Source locations in `.rake`, `.jbuilder`, `config.ru` and extensionless files were not recognised at all.** The client-side parser matched paths against a hardcoded extension allow-list (`rb|erb|js|ts|py|go|java`); anything outside it fell through unparsed, which silently cost it the root-stripping, the start-clipping *and* its IDE link — a `/lib/tasks/setup.rake:17` rendered as the raw absolute path, home directory included. The allow-list is gone: the matcher now takes any path followed by `:<line>`, which also fixes Windows paths (`C:\app\models\post.rb:12`) that the old `[^:]+` broke on at the drive letter. Sources that still don't parse (`PostsController#index`) are clipped from the start too, instead of having their tail cut off.
+- **Source locations are shown short, and never truncated where it matters.** The badge used to print the path verbatim and clip it with `text-overflow: ellipsis` — which cuts the *end*, throwing away the file name and line and leaving only a long shared prefix. It now strips the host application's root (when the engine is mounted in one), collapses a bundled gem's install prefix to the gem's own directory (`…/lib/ruby/gems/3.4.0/gems/activerecord-8.1.3/lib/…` → `activerecord-8.1.3/lib/…`), and clips what remains from the *start*, so the line number is the last thing to go: the directory is given up first and almost entirely, and only once there is no directory left does the file name itself start losing leading characters. The badge is capped at its cell's width and clips its own overflow, so a single long unbreakable file name can no longer push the badge past the column. The directory is dimmed, the file and line are not. Standalone mode has no host-app root to strip, so it gets the gem collapse and the start-clipping. The full path is unchanged in the tooltip, the expanded row and the exports, and IDE links are still built from it.
+- **"Load History (50)" is now "Load History", and is disabled when there is nothing to load.** The number was the request's page size, not a count of anything the user had; read as "50 entries are waiting". The button is also enabled only when history is actually retrievable — it reads from `config.query_monitor_log_file`, so with no log file configured (or none written yet) it could only ever no-op. `QueryMonitor#status` now reports `history_available`, and the disabled button explains why in its tooltip.
+- **The report page's "Back" button moved into the breadcrumb.** It sat at the far right of the action row — away from the navigation context, and a second control doing what the "Dashboard" crumb already did. The first crumb is now the back action, with a left-arrow icon making the affordance explicit.
+- **One vertical rhythm for text and code blocks.** The global `* { margin: 0 }` reset leaves prose containers with no spacing of their own, and the per-element margins that filled the gap had drifted into asymmetry — a `<pre>` inherited 1rem above (from the preceding `<p>`'s `margin-bottom`) and 0 below, so snippets floated away from their intro line and collided with the line under them. Spacing is now owned by one `> * + *` rule per container, driven by a `--flow-gap` token, with the ad-hoc `margin-bottom`/`margin-top` on each block removed.
+- **One code-block definition.** The same "here is how to enable this feature" panel existed in five hand-spaced copies (`<br><br>` for paragraph breaks, `&nbsp;&nbsp;` for indentation, inline `style=` for the box) across the SQL Console, EXPLAIN, Execute Query and migration flows. All five now render through a shared `pgReportsDisabledNotice()` helper using a real `<pre class="code-block">`, so indentation is actual whitespace and every snippet in the UI is styled identically.
+- **One field-label definition.** `.explain-label`, `.explain-stat-label`, `.row-detail-label`, `.problem-field-label`, `.saved-record-field-name` and `.saved-record-detail-label` were six variants of "small-caps label above a value", spread across 0.65–0.8rem, three letter-spacings and two colours. Collapsed into a single rule.
+
+### Fixed
+- **The dashboard broke out of the viewport on a phone.** The `@media (max-width: 768px)` block covered the container, the header and the report actions, and nothing else, so everything added since was laid out at desktop proportions: the breadcrumb squeezed the database selector down to a few characters, the results header packed its title and three meta items into one unwrappable row, filter labels fought their inputs for the same line, and the `.btn { flex: 1 }` in that block stretched *every* button on the page — including "Clear All", which then overran the "Saved for Comparison" title next to it. Two things pushed the page itself sideways: the Query Monitor's scope tooltip (a 320px absolutely-positioned `::after` anchored mid-row, which widened the layout viewport and dragged the fixed toast with it), and the toast's own `max-width: 26rem`, wider than the screen and pinned by `right`. The expanded-row detail was the worst of it — a two-column grid inside the horizontally scrolling results table, with its second column parked off-screen. It is now one column, pinned to the viewport with `position: sticky` so it stays readable while the table scrolls sideways under it; the generic cell rule's `overflow: hidden`, which made the cell its own scroll container and killed the sticky, is lifted for that one cell. The tooltip becomes a bottom sheet, the toast spans the screen width, and the button stretch is scoped to the page's actual action bars. Verified at 320/360/390/414/768px across the dashboard and five report pages: no page-level horizontal overflow anywhere, with only the results table scrolling sideways as intended.
+- **The proxy scrollbar above a wide results table was dead space on touch.** It renders a 12px strip whose only purpose is to be dragged, and touch devices draw no scrollbar in it; it is now skipped when the pointer is coarse, where the table is dragged directly anyway.
+- **Query-monitor file logging silently wrote nothing on Rails <= 7.0 with json >= 3.** The writer serialized with `#to_json`, which ActiveSupport overrides and (up to Rails 7.0) calls with json's `quirks_mode` option — removed in json 3, so it raises `ArgumentError: unknown keyword: quirks_mode`. The writer's `rescue` swallowed that by design ("don't break monitoring if the file write fails"), so the log file just stayed empty with no visible error. Serialization now goes through `JSON.generate`, json's own generator, which takes no such option. Covered by a regression spec.
+
+
+- **Migration-disabled toast was hardcoded Russian** in an otherwise fully translated UI. Now goes through `errors.migration_disabled_toast` (added to all three locales).
+- **Migration-disabled panel title was hardcoded English.** Now goes through `modals.migration_disabled_title` (added to all three locales).
+- **Switching to a database without pg_stat_statements leaked `PG::UndefinedTable` into the UI.** The extension is created per-database, but the availability gate lived only in the dashboard template (`category_key == :queries && !@pg_stat_status[:ready]`). `show`, `run`, `download` and `send_to_telegram` never consulted it, so opening a Queries report and then switching the database ran the report anyway and rendered the driver's `relation "pg_stat_statements" does not exist LINE 11:` in the error banner. The requirement is now declared on the category (`requires: :pg_stat_statements`) and enforced in `#category_disabled_reason`, which every entry point already calls — the dashboard template now reads that same value instead of repeating the rule. The message distinguishes the two remedies: an extension that was never created here, versus one that exists but is missing from `shared_preload_libraries`. An unreachable database is left to the existing connection-error banner rather than being mislabelled as a missing extension.
+- **Redirects out of an unavailable report were silent.** `show` has always redirected to the dashboard with `alert:` when a category is unavailable, but no view rendered `flash`, so the user was bounced with no explanation. The layout now renders `flash[:alert]` / `flash[:notice]`.
+- **`ErrorTranslator` handles missing relations and functions** (`42P01`, `42883`). When the missing relation is one an extension provides, it names the extension and hints the `CREATE EXTENSION` instead of echoing the raw driver message. The three report endpoints route failures through the translator; the raw-SQL endpoints (SQL Console, Execute Query, EXPLAIN) still return PostgreSQL's own wording, which is what you want for a query you typed yourself.
+- `ExplainAnalyzer` no longer emits a `status_icon` emoji from the analysis layer; the dashboard picks the icon from `status`.
+
+## [0.8.2] - 2026-07-10
+
+### Added
+
+- **SQL Console — free-form SQL editor.** A new **SQL Console** button in the dashboard header opens a large modal with a SQL textarea (⌘/Ctrl+Enter to run) and a results table with row count and execution time. Renamed from the initial "Run Query" label, which read too similarly to the existing **▶ Run Report** button. Unlike *Execute Query* (which only ever runs server-generated, hash-cached queries — see 0.5.1 below), this accepts client-typed SQL directly, so the same SELECT-only/no-semicolon/keyword-denylist validation is applied straight to the submitted text via a new shared `enforce_select_only!` check. Gated by the existing `config.allow_raw_query_execution` flag; new `POST /run_query` endpoint.
+- **Bounded statement timeout for raw query execution.** `Execute Query`, `EXPLAIN ANALYZE`, and `SQL Console` now run inside a transaction with `SET LOCAL statement_timeout`, configurable via `config.raw_query_statement_timeout_ms` (default 5000ms, `PG_REPORTS_RAW_QUERY_STATEMENT_TIMEOUT_MS`, `0` disables). Prevents a runaway or accidentally expensive query from holding a connection open indefinitely; a cancelled query now surfaces a clear "query timed out" error instead of an opaque `PG::QueryCanceled`.
+- **Rate limiting for privileged dashboard endpoints.** `explain_analyze`, `execute_query`, `run_query`, and `create_migration` are now throttled per client IP via `config.raw_query_rate_limit` (default 30 requests, `PG_REPORTS_RAW_QUERY_RATE_LIMIT`) within `config.raw_query_rate_limit_window_seconds` (default 60s, `PG_REPORTS_RAW_QUERY_RATE_LIMIT_WINDOW_SECONDS`). Backed by `Rails.cache`; best-effort (not a hardened distributed limiter) and fails open if the cache is unavailable. Set `raw_query_rate_limit = nil` to disable.
+
+### Changed
+
+- **SQL Query Monitor is no longer shown in standalone mode.** It works by subscribing to `ActiveSupport::Notifications` in a host application's process — standalone mode has no separate host app, so the panel had nothing meaningful to monitor. The dashboard panel is now hidden and the `/query_monitor/*` endpoints return `403 Forbidden` when `PgReports.config.standalone` is true.
+
 ## [0.8.1] - 2026-07-03
 
 ### Added

data/README.md

@@ -7,10 +7,14 @@
 
 A comprehensive PostgreSQL monitoring and analysis library for Rails applications. Get insights into query performance, index usage, table statistics, connection health, and more — across **every database on the cluster**, switchable from the dashboard with no extra configuration. Includes a beautiful web dashboard, a Grafana / Prometheus exporter, and Telegram delivery.
 
+> [!NOTE]
+> **It now runs standalone, too** — launch the dashboard against any PostgreSQL database without a host Rails app, straight from the gem with a single command (`pg_reports server`). It still needs a Ruby runtime installed. Docker images (no Ruby required) are planned for the near future. See **[Standalone mode →](docs/standalone.md)**.
+
 ![Dashboard Screenshot](docs/dashboard.png)
 
 ## Features
 
+- 🚀 **Standalone or mounted** - Run inside your Rails app, or launch the dashboard on its own with `pg_reports server` (requires Ruby; Docker images coming soon).
 - 🗄️ **Multi-database** - Auto-discovers every database on the cluster and lets you switch from a dropdown in the dashboard. No configuration required.
 - 📊 **Query Analysis** - Identify slow, heavy, and expensive queries using `pg_stat_statements`
 - 📇 **Index Analysis** - Find unused, duplicate, invalid, and missing indexes
@@ -24,7 +28,8 @@ A comprehensive PostgreSQL monitoring and analysis library for Rails application
 - 🔗 **IDE Integration** - Open source locations in VS Code, Cursor, RubyMine, or IntelliJ (with WSL support)
 - 📌 **Comparison Mode** - Save records to compare before/after optimization
 - 📊 **EXPLAIN ANALYZE** - Advanced query plan analyzer with problem detection and recommendations
-- 🔍 **SQL Query Monitoring** - Real-time monitoring of all executed SQL queries with source location tracking
+- 🖥️ **SQL Console** - Free-form SQL editor in a modal, run SELECT queries and view results directly from the dashboard
+- 🔍 **SQL Query Monitoring** - Real-time monitoring of all executed SQL queries with source location tracking (not available in standalone mode)
 - 🔌 **Connection Pool Analytics** - Monitor pool usage, wait times, saturation warnings, and connection churn
 - 🤖 **AI Prompt Export** - Copy a ready-to-paste prompt for Claude Code, Cursor, or Codex with problem context and report data
 - 🗑️ **Migration Generator** - Generate Rails migrations to drop unused indexes
@@ -68,9 +73,10 @@ You can also run the dashboard on its own, straight from the gem's root folder
 ```bash
 ./bin/pg_reports server        # from a checkout; no `bundle exec` needed
 DATABASE_URL=postgres://user:pass@localhost/myapp bundle exec pg_reports server
+./bin/pg_reports server --allow-raw-query-execution   # opt into the Run SQL panel
 ```
 
-Adds no runtime dependencies to the gem. **[Standalone guide → docs/standalone.md](docs/standalone.md)**
+Settings come from `PG_REPORTS_*` env vars, an auto-detected `./pg_reports.rb` config file (full `PgReports.configure` access), or CLI flags — in that order of precedence. Adds no runtime dependencies to the gem. **[Standalone guide → docs/standalone.md](docs/standalone.md)**
 
 ## Usage
 
@@ -178,6 +184,19 @@ Requires `config.allow_raw_query_execution = true`.
 
 </details>
 
+<details>
+<summary><strong>SQL Console — free-form SQL editor</strong></summary>
+
+Click **SQL Console** in the header to open a large modal with a SQL editor. Type or paste a query, run it (⌘/Ctrl+Enter also works), and see the results in a table with row count and execution time.
+
+Only `SELECT` statements are allowed — the same denylist validation used for the query-hash based **Execute Query** panel (single statement, no `INSERT`/`UPDATE`/`DELETE`/`DROP`/`ALTER`/`CREATE`/`TRUNCATE`/`GRANT`/`REVOKE`) applies here, since this is client-typed SQL rather than a server-generated query. See [Security model](docs/configuration.md#security-model) for the full threat model and residual risks (this is a denylist, not a sandbox).
+
+Every query (here and in Execute Query / EXPLAIN ANALYZE) runs under a bounded `statement_timeout` (`config.raw_query_statement_timeout_ms`, default 5s) and these endpoints are rate-limited per client IP (`config.raw_query_rate_limit`, default 30/min) — see [Raw query execution](docs/configuration.md#raw-query-execution-explain-analyze--execute-query--sql-console).
+
+Requires `config.allow_raw_query_execution = true`.
+
+</details>
+
 <details>
 <summary><strong>SQL Query Monitor — real-time query capture</strong></summary>
 
@@ -200,6 +219,8 @@ end
 
 Use cases: debugging N+1, identifying slow queries during feature development, tracking down unexpected queries, teaching ActiveRecord behavior.
 
+Not available in [standalone mode](docs/standalone.md) — there is no host application process to subscribe to, so the panel and its API are both disabled.
+
 </details>
 
 <details>

data/app/controllers/pg_reports/dashboard_controller.rb

@@ -15,11 +15,18 @@ module PgReports
     before_action :set_categories
     before_action :resolve_database_selection
     around_action :within_selected_database
+    before_action :block_query_monitor_in_standalone, only: %i[
+      start_query_monitoring stop_query_monitoring query_monitor_status
+      query_monitor_feed load_query_history download_query_monitor
+    ]
+    before_action :enforce_rate_limit!, only: %i[
+      explain_analyze execute_query run_query create_migration
+    ]
 
     helper_method :category_disabled_reason, :category_disabled?
 
     def index
-      @pg_stat_status = PgReports.pg_stat_statements_status
+      @pg_stat_status = pg_stat_status
       @current_database = PgReports.system.current_database
     end
 
@@ -133,7 +140,7 @@ module PgReports
 
       @report = execute_report(@category, @report_key)
     rescue => e
-      @error = e.message
+      @error = report_error_message(e)
       @report = nil
     end
 
@@ -174,7 +181,7 @@ module PgReports
         problem_explanations: problem_explanations
       }
     rescue => e
-      render json: {success: false, error: e.message}, status: :unprocessable_entity
+      render json: {success: false, error: report_error_message(e)}, status: :unprocessable_entity
     end
 
     def send_to_telegram
@@ -191,7 +198,7 @@ module PgReports
 
       render json: {success: true, message: I18n.t("pg_reports.ui.success.telegram_sent")}
     rescue => e
-      render json: {success: false, error: e.message}, status: :unprocessable_entity
+      render json: {success: false, error: report_error_message(e)}, status: :unprocessable_entity
     end
 
     def download
@@ -220,7 +227,7 @@ module PgReports
           disposition: "attachment"
       end
     rescue => e
-      render json: {success: false, error: e.message}, status: :unprocessable_entity
+      render json: {success: false, error: report_error_message(e)}, status: :unprocessable_entity
     end
 
     def explain_analyze
@@ -275,8 +282,11 @@ module PgReports
         return
       end
 
-      result = ActiveRecord::Base.connection.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) #{final_query}")
-      explain_output = result.map { |r| r["QUERY PLAN"] }.join("\n")
+      explain_output = nil
+      with_statement_timeout do
+        result = ActiveRecord::Base.connection.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) #{final_query}")
+        explain_output = result.map { |r| r["QUERY PLAN"] }.join("\n")
+      end
 
       # Analyze the EXPLAIN output
       analyzer = ExplainAnalyzer.new(explain_output)
@@ -290,6 +300,8 @@ module PgReports
         problems: analysis[:problems],
         summary: analysis[:summary]
       }
+    rescue ActiveRecord::QueryCanceled
+      render json: {success: false, error: query_timed_out_message}, status: :unprocessable_entity
     rescue => e
       render json: {success: false, error: e.message}, status: :unprocessable_entity
     end
@@ -340,23 +352,95 @@ module PgReports
       # Execute with LIMIT to prevent huge result sets
       limited_query = add_limit_if_missing(final_query, 100)
 
-      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = ActiveRecord::Base.connection.execute(limited_query)
-      end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      execution_time = ((end_time - start_time) * 1000).round(2)
+      rows = columns = nil
+      total_count = 0
+      truncated = false
+      execution_time = nil
+
+      with_statement_timeout do
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = ActiveRecord::Base.connection.execute(limited_query)
+        end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        execution_time = ((end_time - start_time) * 1000).round(2)
+
+        rows = result.to_a
+        columns = rows.first&.keys || []
+        total_count = rows.size
+
+        # Check if we need to get total count
+        if rows.size >= 100
+          count_result = ActiveRecord::Base.connection.execute("SELECT COUNT(*) FROM (#{final_query}) AS count_query")
+          total_count = count_result.first["count"].to_i
+          truncated = total_count > 100
+        end
+      end
 
-      rows = result.to_a
-      columns = rows.first&.keys || []
+      render json: {
+        success: true,
+        columns: columns,
+        rows: rows,
+        count: rows.size,
+        total_count: total_count,
+        truncated: truncated,
+        execution_time: execution_time
+      }
+    rescue ActiveRecord::QueryCanceled
+      render json: {success: false, error: query_timed_out_message}, status: :unprocessable_entity
+    rescue => e
+      render json: {success: false, error: e.message}, status: :unprocessable_entity
+    end
 
-      # Check if we need to get total count
-      total_count = rows.size
-      truncated = false
+    # POST /run_query
+    # Free-text SQL runner backing the "Run Query" modal. Unlike #execute_query
+    # (which only ever runs queries the server itself generated and cached by
+    # hash — see CHANGELOG 0.5.1), this endpoint accepts client-typed SQL
+    # directly, so it applies the same SELECT-only/denylist validation that
+    # normally happens on cache retrieval directly to the submitted text.
+    def run_query
+      raw_query = params[:query].to_s
+
+      if raw_query.blank?
+        render json: {success: false, error: I18n.t("pg_reports.ui.errors.query_required")}, status: :unprocessable_entity
+        return
+      end
+
+      unless PgReports.config.allow_raw_query_execution
+        render json: {
+          success: false,
+          error: I18n.t("pg_reports.ui.errors.query_execution_disabled")
+        }, status: :forbidden
+        return
+      end
+
+      begin
+        enforce_select_only!(raw_query)
+      rescue SecurityError => e
+        render json: {success: false, error: "#{I18n.t("pg_reports.ui.errors.security_violation_prefix")} #{e.message}"}, status: :forbidden
+        return
+      end
+
+      limited_query = add_limit_if_missing(raw_query, 100)
 
-      if rows.size >= 100
-        # Check if there are more rows
-        count_result = ActiveRecord::Base.connection.execute("SELECT COUNT(*) FROM (#{final_query}) AS count_query")
-        total_count = count_result.first["count"].to_i
-        truncated = total_count > 100
+      rows = columns = nil
+      total_count = 0
+      truncated = false
+      execution_time = nil
+
+      with_statement_timeout do
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = ActiveRecord::Base.connection.execute(limited_query)
+        end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        execution_time = ((end_time - start_time) * 1000).round(2)
+
+        rows = result.to_a
+        columns = rows.first&.keys || []
+        total_count = rows.size
+
+        if rows.size >= 100
+          count_result = ActiveRecord::Base.connection.execute("SELECT COUNT(*) FROM (#{raw_query}) AS count_query")
+          total_count = count_result.first["count"].to_i
+          truncated = total_count > 100
+        end
       end
 
       render json: {
@@ -368,6 +452,8 @@ module PgReports
         truncated: truncated,
         execution_time: execution_time
       }
+    rescue ActiveRecord::QueryCanceled
+      render json: {success: false, error: query_timed_out_message}, status: :unprocessable_entity
     rescue => e
       render json: {success: false, error: e.message}, status: :unprocessable_entity
     end
@@ -450,7 +536,8 @@ module PgReports
         success: true,
         enabled: status[:enabled],
         session_id: status[:session_id],
-        query_count: status[:query_count]
+        query_count: status[:query_count],
+        history_available: status[:history_available]
       }
     rescue => e
       render json: {success: false, error: e.message}, status: :unprocessable_entity
@@ -666,8 +753,31 @@ module PgReports
     # otherwise a localized string explaining why it is disabled. Exposed to
     # views via helper_method.
     def category_disabled_reason(category)
+      # pg_stat_statements is created per-database. A category that reads it is
+      # available on one database in the cluster and missing on the next, so the
+      # check belongs here — where every entry point (show, run, download,
+      # telegram) already asks — rather than in the dashboard template alone.
+      # Only meaningful once we know the connection itself works: an unreachable
+      # database has its own banner and must not be reported as a missing
+      # extension.
+      if Dashboard::ReportsRegistry.requires(category) == :pg_stat_statements &&
+          pg_stat_status[:connected] && !pg_stat_status[:ready]
+        return pg_stat_unavailable_reason
+      end
+
       constraint = Dashboard::ReportsRegistry.target_constraint(category)
       return nil unless constraint == :primary_default_database_only
+
+      # In standalone mode there is no host application, so its ActiveRecord
+      # models don't exist — these reports would inspect nothing. Disable the
+      # whole category with an explanation instead of returning empty results.
+      if PgReports.config.standalone
+        return I18n.t("pg_reports.ui.categories.standalone_no_host_app_reason",
+          default: "🔒 This category isn't available in standalone mode — it " \
+            "inspects the host application's models, and there is no host app " \
+            "when running the dashboard on its own.")
+      end
+
       return nil if on_primary_default_database?
 
       I18n.t("pg_reports.ui.categories.primary_only_reason",
@@ -680,6 +790,89 @@ module PgReports
       category_disabled_reason(category).present?
     end
 
+    # A report failing because the selected database lacks an extension-provided
+    # relation is the common case here (extensions are per-database, the
+    # dashboard's database picker is not), and "PG::UndefinedTable: ERROR:
+    # relation ... does not exist LINE 11:" is not something to show a user.
+    def report_error_message(error)
+      info = Connection::ErrorTranslator.translate(error)
+      [info[:detail], info[:hint]].reject { |part| part.to_s.strip.empty? }.join(" ")
+    rescue
+      error.message
+    end
+
+    # Scoped to the request's selected database by the surrounding
+    # #within_selected_database, and memoized because the dashboard asks once
+    # per category while rendering the grid.
+    def pg_stat_status
+      @pg_stat_status ||= PgReports.pg_stat_statements_status
+    end
+
+    # The two failure modes need different remedies: an extension that was never
+    # created here can be created, one that isn't preloaded needs a restart.
+    def pg_stat_unavailable_reason
+      database = @selected_database.presence || PgReports.system.current_database
+
+      if pg_stat_status[:extension_installed]
+        I18n.t("pg_reports.ui.categories.pg_stat_not_preloaded_reason",
+          database: database,
+          default: "Requires pg_stat_statements. The extension exists on " \
+            "\"%{database}\" but is not in shared_preload_libraries, so it " \
+            "returns no data until PostgreSQL is restarted with it preloaded.")
+      else
+        I18n.t("pg_reports.ui.categories.pg_stat_missing_reason",
+          database: database,
+          default: "Requires pg_stat_statements, which is not installed on " \
+            "\"%{database}\". Create the extension there, or switch to a " \
+            "database that has it.")
+      end
+    end
+
+    # SQL Query Monitor taps ActiveSupport::Notifications in the host
+    # application's process. In standalone mode there is no host app — pg_reports
+    # is the only process running, so there's nothing meaningful to observe.
+    # Blocks the API even if a client calls it directly (the UI panel is also
+    # hidden in standalone, see dashboard/index view).
+    def block_query_monitor_in_standalone
+      return unless PgReports.config.standalone
+
+      render json: {
+        success: false,
+        error: I18n.t("pg_reports.ui.errors.query_monitor_unavailable_standalone")
+      }, status: :forbidden
+    end
+
+    # Soft per-IP throttle for the dashboard's privileged raw-query and
+    # migration endpoints. This is not a hardened distributed rate limiter —
+    # just a best-effort guard against a single client hammering these
+    # expensive/privileged actions, backed by Rails.cache (works with or
+    # without a shared cache backend across processes). Fails open if the
+    # cache is unavailable, consistent with the rest of the dashboard (see
+    # #resolve_database_selection, #retrieve_query_by_hash).
+    def enforce_rate_limit!
+      limit = PgReports.config.raw_query_rate_limit
+      return if limit.nil?
+
+      window = PgReports.config.raw_query_rate_limit_window_seconds
+      key = "pg_reports:rate_limit:#{request.remote_ip}:#{params[:action]}"
+
+      count = begin
+        current = (Rails.cache.read(key) || 0) + 1
+        Rails.cache.write(key, current, expires_in: window)
+        current
+      rescue => e
+        Rails.logger.warn("PgReports: Rate limit cache unavailable: #{e.message}") if defined?(Rails.logger)
+        return
+      end
+
+      return if count <= limit
+
+      render json: {
+        success: false,
+        error: I18n.t("pg_reports.ui.errors.rate_limit_exceeded")
+      }, status: :too_many_requests
+    end
+
     def on_primary_default_database?
       return true if @target_default_database.nil?
 
@@ -768,7 +961,15 @@ module PgReports
         return nil
       end
 
-      # Strict validation: must be a SELECT query only
+      enforce_select_only!(query)
+
+      query
+    end
+
+    # Strict validation: must be a single SELECT statement, no dangerous
+    # keywords. This is a denylist, not a sandbox (see docs/configuration.md)
+    # — shared by #retrieve_query_by_hash and the free-text #run_query action.
+    def enforce_select_only!(query)
       normalized = query.strip.gsub(/\s+/, " ").downcase
 
       # Check for semicolons (prevents multiple statements)
@@ -788,8 +989,24 @@ module PgReports
           raise SecurityError, "Dangerous keyword detected: #{keyword.upcase}"
         end
       end
+    end
 
-      query
+    # Bounds how long a single raw-query execution (Execute Query / EXPLAIN
+    # ANALYZE / SQL Console) can run, so a runaway query can't hang the
+    # connection indefinitely. SET LOCAL only takes effect inside a
+    # transaction and reverts automatically at its end (commit or rollback) —
+    # safe here since every caller only ever runs SELECTs.
+    def with_statement_timeout
+      ActiveRecord::Base.transaction do
+        timeout_ms = PgReports.config.raw_query_statement_timeout_ms.to_i
+        ActiveRecord::Base.connection.execute("SET LOCAL statement_timeout = #{timeout_ms}") if timeout_ms.positive?
+        yield
+      end
+    end
+
+    def query_timed_out_message
+      I18n.t("pg_reports.ui.errors.query_timed_out",
+        ms: PgReports.config.raw_query_statement_timeout_ms.to_i)
     end
 
     def generate_query_monitor_csv(queries)