pg_reports 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff4489af5016c4bfbe14f7187daa5ca2ea279b15887bab928c8effefc4b2dad
-  data.tar.gz: 26815859090bbf8a84000acb3545c1eecb982887f8d0f07d9ab0e582f2380c58
+  metadata.gz: 2800846cf0c02bdf3a2605151d0bfe7b7775a1eda3a1a920eed26bc3f731748d
+  data.tar.gz: 6f07d07fcd9e396d6c9dd885f9e9c2e0c9d10595f5b8817eba59a2c8c734981a
 SHA512:
-  metadata.gz: f94d1f175001f3a8140d8ef9b826d353bb20963d3b75487aace882fde54186466be500840252bc9e87268e55244bb96746f59fd82b6ba648271a828b596b47d4
-  data.tar.gz: f89ff6622a18f3daf33fabf898a8736da510e2ecf84f4455e5720a8a07f3a219ed1336a1f1a286437a23da505560e724679bb27957b74b501567db2cfaee9f17
+  metadata.gz: 2c5165e3eaff390afb0f9369aa6a9a2351dbe410cf64fd26a5df0be6cd3492513d0510d84758886dfa42d04b378e524d8483490f991ab63f3cef25ed8594b088
+  data.tar.gz: 312d69fcb4a15c0216a1381ec04d9db6bf4811b326b89e70ecd5ce5ed43974eddc38ab6ed3c59e7358eb4ce2e1f0fd7ffc054be0da747f3d903f40b808e205c1

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,6 +15,13 @@ 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?
 
@@ -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
+
+      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
+
+    # 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
 
-      rows = result.to_a
-      columns = rows.first&.keys || []
+      if raw_query.blank?
+        render json: {success: false, error: I18n.t("pg_reports.ui.errors.query_required")}, status: :unprocessable_entity
+        return
+      end
 
-      # Check if we need to get total count
-      total_count = rows.size
-      truncated = false
+      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
 
-      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
+      limited_query = add_limit_if_missing(raw_query, 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
@@ -668,6 +754,17 @@ module PgReports
     def category_disabled_reason(category)
       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 +777,51 @@ module PgReports
       category_disabled_reason(category).present?
     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 +910,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 +938,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)

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

@@ -23,6 +23,9 @@
   </div>
 
   <div class="header-actions">
+    <button class="btn btn-small btn-primary" onclick="showRunQueryModal()" id="run-query-open-btn">
+      <%= t("pg_reports.ui.actions.run_query") %>
+    </button>
     <% if @pg_stat_status[:ready] %>
       <button class="btn btn-small btn-muted" onclick="showResetConfirmModal()" id="reset-btn">
         <%= t("pg_reports.ui.actions.reset_statistics") %>
@@ -167,6 +170,42 @@ pg_stat_statements.track = all</pre>
   </div>
 </div>
 
+<!-- Run Query Modal -->
+<div id="run-query-modal" class="modal" style="display: none;">
+  <div class="modal-content modal-run-query">
+    <div class="modal-header">
+      <h3><%= t("pg_reports.ui.modals.run_query_title") %></h3>
+      <button class="modal-close" onclick="closeRunQueryModal()">&times;</button>
+    </div>
+    <div class="modal-body">
+      <% if PgReports.config.allow_raw_query_execution %>
+        <label class="explain-label" for="run-query-input"><%= t("pg_reports.ui.modals.query_label") %></label>
+        <textarea id="run-query-input" class="run-query-textarea" spellcheck="false" placeholder="<%= t("pg_reports.ui.modals.run_query_placeholder") %>"></textarea>
+        <div class="run-query-actions">
+          <button class="btn btn-secondary" onclick="clearRunQuery()"><%= t("pg_reports.ui.actions.clear_all") %></button>
+          <button class="btn btn-primary" onclick="executeRunQuery()" id="btn-run-query"><%= t("pg_reports.ui.actions.run_query") %></button>
+        </div>
+        <div id="run-query-loading" class="loading" style="display: none;">
+          <div class="spinner"></div>
+        </div>
+        <div id="run-query-content"></div>
+      <% else %>
+        <div class="error-message">
+          <strong><%= t("pg_reports.ui.modals.query_execution_disabled_title") %></strong><br><br>
+          <%= t("pg_reports.ui.modals.query_execution_disabled_intro") %><br>
+          <code style="display: block; margin-top: 0.5rem; padding: 0.5rem; background: rgba(0,0,0,0.2); border-radius: 4px;">
+PgReports.configure do |config|<br>
+&nbsp;&nbsp;config.allow_raw_query_execution = true<br>
+end
+          </code>
+          <p style="margin-top: 0.75rem;"><%= t("pg_reports.ui.modals.query_execution_disabled_env_note") %></p>
+          <code style="display: block; margin-top: 0.5rem; padding: 0.5rem; background: rgba(0,0,0,0.2); border-radius: 4px;">PG_REPORTS_ALLOW_RAW_QUERY_EXECUTION=true</code>
+        </div>
+      <% end %>
+    </div>
+  </div>
+</div>
+
 <!-- Live Monitoring Panel -->
 <div id="live-monitoring" class="live-monitoring-panel" style="display: none;">
   <div class="live-monitoring-header">
@@ -286,7 +325,11 @@ pg_stat_statements.track = all</pre>
   </div>
 </div>
 
-<!-- Query Monitoring Panel -->
+<!-- Query Monitoring Panel: taps ActiveSupport::Notifications in the host
+     application's process. There is no host app in standalone mode, so the
+     panel is hidden entirely rather than showing a monitor with nothing to
+     monitor. -->
+<% unless PgReports.config.standalone %>
 <div id="query-monitoring" class="query-monitoring-panel" style="display: none;">
   <div class="query-monitoring-header">
     <div class="query-monitoring-title">
@@ -331,6 +374,7 @@ pg_stat_statements.track = all</pre>
     </div>
   </div>
 </div>
+<% end %>
 
 <div class="categories-grid">
   <% @categories.each do |category_key, category| %>
@@ -907,9 +951,254 @@ pg_stat_statements.track = all</pre>
   .toast.toast-warning {
     border-left: 3px solid var(--accent-amber);
   }
+
+  /* Run Query Modal */
+  .modal-run-query {
+    max-width: 1100px;
+    width: 95%;
+  }
+
+  .explain-label {
+    display: block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    margin-bottom: 0.5rem;
+  }
+
+  .run-query-textarea {
+    width: 100%;
+    min-height: 180px;
+    padding: 1rem;
+    background: var(--bg-primary);
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    color: var(--text-primary);
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 0.85rem;
+    line-height: 1.5;
+    resize: vertical;
+  }
+
+  .run-query-textarea:focus {
+    outline: none;
+    border-color: var(--accent-blue);
+    box-shadow: 0 0 0 2px rgba(107, 159, 232, 0.2);
+  }
+
+  .run-query-textarea::placeholder {
+    color: var(--text-muted);
+    font-style: italic;
+  }
+
+  .run-query-actions {
+    display: flex;
+    gap: 0.75rem;
+    margin: 1rem 0;
+  }
+
+  .run-query-actions .btn {
+    flex: 1;
+  }
+
+  /* Query Results Table (mirrors _show_styles.html.erb — index.html.erb has
+     its own <style> block and isn't loaded through that partial) */
+  .query-results-wrapper {
+    margin-top: 1rem;
+    max-height: 400px;
+    overflow: auto;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+  }
+
+  .query-results-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 0.75rem;
+  }
+
+  .query-results-table th {
+    position: sticky;
+    top: 0;
+    padding: 0.75rem;
+    text-align: left;
+    background: var(--bg-tertiary);
+    color: var(--text-muted);
+    font-weight: 500;
+    text-transform: uppercase;
+    font-size: 0.65rem;
+    letter-spacing: 0.05em;
+    border-bottom: 1px solid var(--border-color);
+  }
+
+  .query-results-table td {
+    padding: 0.5rem 0.75rem;
+    border-bottom: 1px solid var(--border-color);
+    color: var(--text-secondary);
+    max-width: 300px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .query-results-table tr:hover td {
+    background: var(--bg-tertiary);
+    color: var(--text-primary);
+  }
+
+  .query-results-info {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.75rem 1rem;
+    background: var(--bg-tertiary);
+    border-radius: 8px;
+    margin-top: 1rem;
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+  }
+
+  .query-results-info .count {
+    color: var(--accent-blue);
+    font-weight: 600;
+  }
+
+  .query-results-info .time {
+    color: var(--accent-green);
+    font-weight: 600;
+  }
 </style>
 
 <script>
+  const allowRawQueryExecution = <%= PgReports.config.allow_raw_query_execution.to_s.downcase %>;
+
+  function escapeHtmlAttr(text) {
+    return String(text)
+      .replace(/&/g, '&amp;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  function showRunQueryModal() {
+    document.getElementById('run-query-modal').style.display = 'flex';
+    document.getElementById('run-query-input')?.focus();
+  }
+
+  function closeRunQueryModal() {
+    document.getElementById('run-query-modal').style.display = 'none';
+  }
+
+  document.getElementById('run-query-modal')?.addEventListener('click', function(e) {
+    if (e.target === this) closeRunQueryModal();
+  });
+
+  document.getElementById('run-query-input')?.addEventListener('keydown', function(e) {
+    if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+      e.preventDefault();
+      executeRunQuery();
+    }
+  });
+
+  function clearRunQuery() {
+    document.getElementById('run-query-input').value = '';
+    document.getElementById('run-query-content').innerHTML = '';
+  }
+
+  async function executeRunQuery() {
+    const input = document.getElementById('run-query-input');
+    const loading = document.getElementById('run-query-loading');
+    const content = document.getElementById('run-query-content');
+    const query = input.value.trim();
+
+    if (!query) {
+      showToast(PG_REPORTS_I18N.errors.query_required, 'error');
+      return;
+    }
+
+    if (!allowRawQueryExecution) {
+      showToast(PG_REPORTS_I18N.errors.execute_disabled_toast, 'error');
+      content.innerHTML = `<div class="error-message">
+        <strong>${PG_REPORTS_I18N.modals.query_execution_disabled_title}</strong><br><br>
+        ${PG_REPORTS_I18N.modals.query_execution_disabled_intro}<br>
+        <code style="display: block; margin-top: 0.5rem; padding: 0.5rem; background: rgba(0,0,0,0.2); border-radius: 4px;">
+PgReports.configure do |config|<br>
+&nbsp;&nbsp;config.allow_raw_query_execution = true<br>
+end
+        </code>
+      </div>`;
+      return;
+    }
+
+    loading.style.display = 'flex';
+    content.innerHTML = '';
+
+    try {
+      const response = await fetch(`${pgReportsRoot}/run_query`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]')?.content || ''
+        },
+        body: JSON.stringify({ query: query })
+      });
+
+      const data = await response.json();
+      loading.style.display = 'none';
+
+      if (data.success) {
+        let html = '';
+
+        html += `<div class="query-results-info">
+          <span>${PG_REPORTS_I18N.results.rows_label} <span class="count">${data.count}</span></span>
+          <span>${PG_REPORTS_I18N.results.execution_time_label} <span class="time">${data.execution_time} ms</span></span>
+        </div>`;
+
+        if (data.rows && data.rows.length > 0) {
+          html += '<div class="query-results-wrapper">';
+          html += '<table class="query-results-table">';
+
+          html += '<thead><tr>';
+          data.columns.forEach(col => {
+            html += `<th>${escapeHtml(col)}</th>`;
+          });
+          html += '</tr></thead>';
+
+          html += '<tbody>';
+          data.rows.forEach(row => {
+            html += '<tr>';
+            data.columns.forEach(col => {
+              const value = row[col];
+              const displayValue = value === null ? PG_REPORTS_I18N.results.null_placeholder : String(value);
+              html += `<td title="${escapeHtmlAttr(displayValue)}">${escapeHtml(displayValue)}</td>`;
+            });
+            html += '</tr>';
+          });
+          html += '</tbody>';
+
+          html += '</table>';
+          html += '</div>';
+
+          if (data.truncated) {
+            html += `<p style="margin-top: 0.5rem; color: var(--text-muted); font-size: 0.75rem;">${pgReportsFormat(PG_REPORTS_I18N.results.showing_first_of_total, { count: data.rows.length, total: data.total_count })}</p>`;
+          }
+        } else {
+          html += '<p style="margin-top: 1rem; color: var(--text-muted);">' + PG_REPORTS_I18N.results.no_rows_returned + '</p>';
+        }
+
+        content.innerHTML = html;
+      } else {
+        content.innerHTML = `<div class="error-message">${escapeHtml(data.error || PG_REPORTS_I18N.errors.run_query_failed)}</div>`;
+      }
+    } catch (error) {
+      loading.style.display = 'none';
+      content.innerHTML = `<div class="error-message">${PG_REPORTS_I18N.errors.network_error_prefix} ${escapeHtml(error.message)}</div>`;
+    }
+  }
+
   function showPgStatInfo() {
     document.getElementById('pg-stat-modal').style.display = 'flex';
   }

data/bin/pg_reports

@@ -23,7 +23,16 @@ options = {
   host: "127.0.0.1",
   mount: "/",
   database_url: nil,
-  server: nil
+  server: nil,
+  config_file: nil
+}
+
+# Per-setting overrides from flags. nil means "unset" — the config file / ENV
+# value is kept. Populated below and forwarded to Standalone.run(overrides:).
+overrides = {
+  allow_raw_query_execution: nil,
+  allow_migration_creation: nil,
+  load_external_fonts: nil
 }
 
 banner = <<~BANNER
@@ -35,6 +44,12 @@ banner = <<~BANNER
   Connection is resolved from --database-url, else DATABASE_URL, else the
   standard libpq env vars (PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE).
 
+  Configuration is layered, lowest to highest precedence:
+    PG_REPORTS_* env vars  <  config file  <  the flags below.
+  A config file (--config, else ./pg_reports.rb or config/pg_reports.rb) is
+  plain Ruby calling `PgReports.configure` — the way to set every option that
+  has no flag (thresholds, Telegram, Grafana, dashboard_auth, …).
+
   Options:
 BANNER
 
@@ -45,6 +60,10 @@ parser = OptionParser.new do |o|
   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("-c", "--config PATH", "Ruby config file to load (default: ./pg_reports.rb or config/pg_reports.rb)") { |v| options[:config_file] = v }
+  o.on("--[no-]allow-raw-query-execution", "Allow running raw SQL / EXPLAIN ANALYZE from the dashboard") { |v| overrides[:allow_raw_query_execution] = v }
+  o.on("--[no-]allow-migration-creation", "Allow the dashboard to write migration files to db/migrate/") { |v| overrides[:allow_migration_creation] = v }
+  o.on("--[no-]external-fonts", "Load Google Fonts in the dashboard (off by default)") { |v| overrides[:load_external_fonts] = v }
   o.on("-h", "--help", "Show this help") do
     puts o
     exit
@@ -70,11 +89,18 @@ when "server"
       host: options[:host],
       mount_path: options[:mount],
       database_url: options[:database_url],
-      server: options[:server]
+      server: options[:server],
+      config_file: options[:config_file],
+      overrides: overrides
     )
   rescue PgReports::Standalone::ServerUnavailable => e
     warn e.message
     exit 1
+  rescue PgReports::Error => e
+    # Config-file and connection problems surface as PgReports::Error with a
+    # human-readable message — print it, not a backtrace.
+    warn "pg_reports: #{e.message}"
+    exit 1
   rescue Interrupt
     warn "\npg_reports: stopped"
   end

data/config/brakeman.ignore

@@ -0,0 +1,74 @@
+{
+  "ignored_warnings": [
+    {
+      "warning_type": "SQL Injection",
+      "warning_code": 0,
+      "fingerprint": "5209397462e689c349f77e534f897c12a8550b9a013bd535153a929c12b944e2",
+      "check_name": "SQL",
+      "message": "Possible SQL injection",
+      "file": "app/controllers/pg_reports/dashboard_controller.rb",
+      "line": 357,
+      "link": "https://brakemanscanner.org/docs/warning_types/sql_injection/",
+      "code": "ActiveRecord::Base.connection.execute(\"SELECT COUNT(*) FROM (#{substitute_params(retrieve_query_by_hash(params[:query_hash]), (params[:params] or {}))}) AS count_query\")",
+      "render_path": null,
+      "location": {
+        "type": "method",
+        "class": "PgReports::DashboardController",
+        "method": "execute_query"
+      },
+      "user_input": "params[:params]",
+      "confidence": "High",
+      "cwe_id": [
+        89
+      ],
+      "note": "Reviewed & accepted: user-query execution feature (execute_query count). Gated by config.allow_raw_query_execution; the query is fetched by hash from an internal registry (retrieve_query_by_hash), parameters are validated/substituted, and SecurityError checks reject dangerous input. Not arbitrary attacker-controlled SQL."
+    },
+    {
+      "warning_type": "Cross-Site Request Forgery",
+      "warning_code": 7,
+      "fingerprint": "b9682cc0e0a1cd86fddef96834d4f71c3558989c2136fe58b5ff51c75b83c8b4",
+      "check_name": "ForgerySetting",
+      "message": "`protect_from_forgery` should be called in `PgReports::MetricsController`",
+      "file": "app/controllers/pg_reports/metrics_controller.rb",
+      "line": 6,
+      "link": "https://brakemanscanner.org/docs/warning_types/cross-site_request_forgery/",
+      "code": null,
+      "render_path": null,
+      "location": {
+        "type": "controller",
+        "controller": "PgReports::MetricsController"
+      },
+      "user_input": null,
+      "confidence": "High",
+      "cwe_id": [
+        352
+      ],
+      "note": "Reviewed & accepted: read-only Prometheus /metrics endpoint. Uses bearer-token auth (config.grafana_metrics_token) with constant-time compare; CSRF protection is not applicable to a GET scrape endpoint."
+    },
+    {
+      "warning_type": "SQL Injection",
+      "warning_code": 0,
+      "fingerprint": "f133378f2542f3c09b527aebcc0939a1d227c46b0ab124be613e1e5aac829c79",
+      "check_name": "SQL",
+      "message": "Possible SQL injection",
+      "file": "app/controllers/pg_reports/dashboard_controller.rb",
+      "line": 278,
+      "link": "https://brakemanscanner.org/docs/warning_types/sql_injection/",
+      "code": "ActiveRecord::Base.connection.execute(\"EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) #{substitute_params(retrieve_query_by_hash(params[:query_hash]), (params[:params] or {}))}\")",
+      "render_path": null,
+      "location": {
+        "type": "method",
+        "class": "PgReports::DashboardController",
+        "method": "explain_analyze"
+      },
+      "user_input": "params[:params]",
+      "confidence": "High",
+      "cwe_id": [
+        89
+      ],
+      "note": "Reviewed & accepted: EXPLAIN ANALYZE feature. Same safeguards as execute_query - query resolved by hash from internal registry, params validated, SecurityError guards. Intentional DBA tooling."
+    }
+  ],
+  "updated": "2026-07-04 20:27:49 +0300",
+  "brakeman_version": "8.0.5"
+}

data/config/locales/en.yml

@@ -622,6 +622,7 @@ en:
         ide_settings_button_title: "IDE Settings"
         explain_analyze: "📊 EXPLAIN ANALYZE"
         execute_query: "▶ Execute Query"
+        run_query: "SQL Console"
         create_migration_file: "📁 Create File & Open in IDE"
         start_monitoring: "▶ Start Monitoring"
         stop_monitoring: "⏹ Stop Monitoring"
@@ -663,6 +664,9 @@ en:
         migration_warning_dev_only: "This operation should only be performed in a local development environment."
         query_execution_disabled_title: "⚠️ Query execution is disabled"
         query_execution_disabled_intro: "To enable this feature, add to your configuration:"
+        query_execution_disabled_env_note: "...or set the following environment variable instead:"
+        run_query_title: "SQL Console"
+        run_query_placeholder: "SELECT * FROM users LIMIT 10;"
       settings:
         default_ide_label: "Default IDE for source links:"
         ide_show_menu: "Show menu (default)"
@@ -704,6 +708,7 @@ en:
         requires_pg_stat: "🔒 Requires pg_stat_statements"
         reports_count_suffix: "reports"
         primary_only_reason: "🔒 This category only runs on the primary database — it inspects the host application's models. Switch back to the default database to use it."
+        standalone_no_host_app_reason: "🔒 Not available in standalone mode — this category inspects the host application's models, and there is no host app when running the dashboard on its own."
       documentation:
         toggle_title: "📖 What does this report show?"
         what_section: "📋 What"
@@ -768,6 +773,8 @@ en:
         decode_query_failed: "Failed to decode query"
         explain_analyze_failed: "Failed to run EXPLAIN ANALYZE"
         execute_query_failed: "Failed to execute query"
+        run_query_failed: "Failed to run query"
+        query_required: "Please enter a query"
         create_migration_failed: "Failed to create migration"
         explain_disabled_toast: "⚠️ EXPLAIN ANALYZE is disabled. Enable in configuration: config.allow_raw_query_execution = true"
         execute_disabled_toast: "⚠️ Query execution is disabled. Enable in configuration: config.allow_raw_query_execution = true"
@@ -775,6 +782,9 @@ en:
         query_hash_required: "Query hash is required"
         query_execution_disabled: "Query execution from dashboard is disabled. Enable it in configuration with 'config.allow_raw_query_execution = true'"
         query_not_found_expired: "Query not found or expired. Please refresh the page."
+        query_monitor_unavailable_standalone: "SQL Query Monitor isn't available in standalone mode — there is no host application process to observe."
+        query_timed_out: "Query timed out after %{ms}ms (statement_timeout). Try narrowing the query or increase config.raw_query_statement_timeout_ms."
+        rate_limit_exceeded: "Too many requests. Please wait a bit before trying again."
         security_violation_prefix: "Security violation:"
         trigger_variables_not_allowed: "Cannot EXPLAIN ANALYZE queries with trigger variables (NEW, OLD). These are only available within trigger functions."
         missing_parameter_values: "Please provide values for all parameter placeholders ($1, $2, etc.)"

data/config/locales/ru.yml

@@ -587,6 +587,7 @@ ru:
         ide_settings_button_title: "Настройки IDE"
         explain_analyze: "📊 EXPLAIN ANALYZE"
         execute_query: "▶ Выполнить запрос"
+        run_query: "SQL-консоль"
         create_migration_file: "📁 Создать файл и открыть в IDE"
         start_monitoring: "▶ Запустить мониторинг"
         stop_monitoring: "⏹ Остановить мониторинг"
@@ -628,6 +629,9 @@ ru:
         migration_warning_dev_only: "Эту операцию следует выполнять только в локальном dev-окружении."
         query_execution_disabled_title: "⚠️ Выполнение запросов отключено"
         query_execution_disabled_intro: "Чтобы включить эту функцию, добавьте в конфигурацию:"
+        query_execution_disabled_env_note: "...или вместо этого установите переменную окружения:"
+        run_query_title: "SQL-консоль"
+        run_query_placeholder: "SELECT * FROM users LIMIT 10;"
       settings:
         default_ide_label: "IDE по умолчанию для ссылок на исходники:"
         ide_show_menu: "Показывать меню (по умолчанию)"
@@ -669,6 +673,7 @@ ru:
         requires_pg_stat: "🔒 Требуется pg_stat_statements"
         reports_count_suffix: "отчётов"
         primary_only_reason: "🔒 Эта категория работает только на первичной базе — она проверяет модели хост-приложения. Чтобы пользоваться, переключитесь обратно на базу по умолчанию."
+        standalone_no_host_app_reason: "🔒 Недоступно в автономном режиме — эта категория проверяет модели хост-приложения, а при самостоятельном запуске дашборда хост-приложения нет."
       documentation:
         toggle_title: "📖 Что показывает этот отчёт?"
         what_section: "📋 Что"
@@ -733,6 +738,8 @@ ru:
         decode_query_failed: "Не удалось декодировать запрос"
         explain_analyze_failed: "Не удалось выполнить EXPLAIN ANALYZE"
         execute_query_failed: "Не удалось выполнить запрос"
+        run_query_failed: "Не удалось выполнить запрос"
+        query_required: "Введите запрос"
         create_migration_failed: "Не удалось создать миграцию"
         explain_disabled_toast: "⚠️ EXPLAIN ANALYZE отключен. Включите в конфигурации: config.allow_raw_query_execution = true"
         execute_disabled_toast: "⚠️ Выполнение запросов отключено. Включите в конфигурации: config.allow_raw_query_execution = true"
@@ -740,6 +747,9 @@ ru:
         query_hash_required: "Требуется хэш запроса"
         query_execution_disabled: "Выполнение запросов из дашборда отключено. Включите в конфигурации: 'config.allow_raw_query_execution = true'"
         query_not_found_expired: "Запрос не найден или истёк срок действия. Обновите страницу."
+        query_monitor_unavailable_standalone: "SQL Query Monitor недоступен в автономном режиме — нет процесса основного приложения для наблюдения."
+        query_timed_out: "Превышено время ожидания запроса (%{ms} мс, statement_timeout). Сузьте запрос или увеличьте config.raw_query_statement_timeout_ms."
+        rate_limit_exceeded: "Слишком много запросов. Подождите немного и попробуйте снова."
         security_violation_prefix: "Нарушение безопасности:"
         trigger_variables_not_allowed: "Нельзя выполнить EXPLAIN ANALYZE для запросов с триггерными переменными (NEW, OLD). Они доступны только в контексте триггерных функций."
         missing_parameter_values: "Укажите значения для всех плейсхолдеров параметров ($1, $2 и т.д.)"

data/config/locales/uk.yml

@@ -587,6 +587,7 @@ uk:
         ide_settings_button_title: "Налаштування IDE"
         explain_analyze: "📊 EXPLAIN ANALYZE"
         execute_query: "▶ Виконати запит"
+        run_query: "SQL-консоль"
         create_migration_file: "📁 Створити файл і відкрити в IDE"
         start_monitoring: "▶ Запустити моніторинг"
         stop_monitoring: "⏹ Зупинити моніторинг"
@@ -628,6 +629,9 @@ uk:
         migration_warning_dev_only: "Цю операцію слід виконувати лише в локальному dev-середовищі."
         query_execution_disabled_title: "⚠️ Виконання запитів вимкнено"
         query_execution_disabled_intro: "Щоб увімкнути цю функцію, додайте до конфігурації:"
+        query_execution_disabled_env_note: "...або замість цього встановіть змінну середовища:"
+        run_query_title: "SQL-консоль"
+        run_query_placeholder: "SELECT * FROM users LIMIT 10;"
       settings:
         default_ide_label: "IDE за замовчуванням для посилань на джерела:"
         ide_show_menu: "Показувати меню (за замовчуванням)"
@@ -669,6 +673,7 @@ uk:
         requires_pg_stat: "🔒 Потрібен pg_stat_statements"
         reports_count_suffix: "звітів"
         primary_only_reason: "🔒 Ця категорія працює лише на первинній базі — вона перевіряє моделі хост-застосунку. Щоб користуватися, перемкніться на базу за замовчуванням."
+        standalone_no_host_app_reason: "🔒 Недоступно в автономному режимі — ця категорія перевіряє моделі хост-застосунку, а при самостійному запуску дашборда хост-застосунку немає."
       documentation:
         toggle_title: "📖 Що показує цей звіт?"
         what_section: "📋 Що"
@@ -733,6 +738,8 @@ uk:
         decode_query_failed: "Не вдалося декодувати запит"
         explain_analyze_failed: "Не вдалося виконати EXPLAIN ANALYZE"
         execute_query_failed: "Не вдалося виконати запит"
+        run_query_failed: "Не вдалося виконати запит"
+        query_required: "Введіть запит"
         create_migration_failed: "Не вдалося створити міграцію"
         explain_disabled_toast: "⚠️ EXPLAIN ANALYZE вимкнено. Увімкніть у конфігурації: config.allow_raw_query_execution = true"
         execute_disabled_toast: "⚠️ Виконання запитів вимкнено. Увімкніть у конфігурації: config.allow_raw_query_execution = true"
@@ -740,6 +747,9 @@ uk:
         query_hash_required: "Потрібен хеш запиту"
         query_execution_disabled: "Виконання запитів із дашборду вимкнено. Увімкніть у конфігурації: 'config.allow_raw_query_execution = true'"
         query_not_found_expired: "Запит не знайдено або термін дії минув. Оновіть сторінку."
+        query_monitor_unavailable_standalone: "SQL Query Monitor недоступний в автономному режимі — немає процесу основного застосунку для спостереження."
+        query_timed_out: "Перевищено час очікування запиту (%{ms} мс, statement_timeout). Звузьте запит або збільшіть config.raw_query_statement_timeout_ms."
+        rate_limit_exceeded: "Забагато запитів. Зачекайте трохи і спробуйте знову."
         security_violation_prefix: "Порушення безпеки:"
         trigger_variables_not_allowed: "Не можна виконати EXPLAIN ANALYZE для запитів із тригерними змінними (NEW, OLD). Вони доступні лише в контексті тригерних функцій."
         missing_parameter_values: "Вкажіть значення для всіх плейсхолдерів параметрів ($1, $2 тощо)"

data/config/routes.rb

@@ -14,6 +14,7 @@ PgReports::Engine.routes.draw do
   post "reset_statistics", to: "dashboard#reset_statistics", as: :reset_statistics
   post "explain_analyze", to: "dashboard#explain_analyze", as: :explain_analyze
   post "execute_query", to: "dashboard#execute_query", as: :execute_query
+  post "run_query", to: "dashboard#run_query", as: :run_query
   post "create_migration", to: "dashboard#create_migration", as: :create_migration
 
   # Query monitoring

data/lib/pg_reports/configuration.rb

@@ -27,6 +27,7 @@ module PgReports
 
     # Dashboard settings
     attr_accessor :dashboard_auth               # Proc for dashboard authentication
+    attr_accessor :standalone                   # True when running via PgReports::Standalone (no host app)
 
     # Assets / privacy settings
     attr_accessor :load_external_fonts          # When true, loads Google Fonts in the dashboard layout
@@ -42,6 +43,9 @@ module PgReports
     # Security settings
     attr_accessor :allow_raw_query_execution    # Allow execute_query and explain_analyze from dashboard
     attr_accessor :allow_migration_creation     # Allow dashboard's "Generate Migration" button to write files into db/migrate/
+    attr_accessor :raw_query_statement_timeout_ms    # Postgres statement_timeout (ms) applied to Execute Query / EXPLAIN ANALYZE / SQL Console. 0 disables it.
+    attr_accessor :raw_query_rate_limit              # Max privileged requests (raw query execution / Generate Migration) per client IP per window. nil disables rate limiting.
+    attr_accessor :raw_query_rate_limit_window_seconds # Window size (seconds) for raw_query_rate_limit
 
     # Grafana / Prometheus exporter settings
     attr_accessor :grafana_favorites            # Reports exposed at /metrics (Array of keys or Hash with per-report opts)
@@ -74,6 +78,7 @@ module PgReports
 
       # Dashboard
       @dashboard_auth = nil
+      @standalone = false
 
       # Assets / privacy
       @load_external_fonts = ActiveModel::Type::Boolean.new.cast(ENV.fetch("PG_REPORTS_LOAD_EXTERNAL_FONTS", false))
@@ -101,6 +106,9 @@ module PgReports
       else
         ActiveModel::Type::Boolean.new.cast(env_override)
       end
+      @raw_query_statement_timeout_ms = ENV.fetch("PG_REPORTS_RAW_QUERY_STATEMENT_TIMEOUT_MS", 5_000).to_i
+      @raw_query_rate_limit = ENV.fetch("PG_REPORTS_RAW_QUERY_RATE_LIMIT", 30).to_i
+      @raw_query_rate_limit_window_seconds = ENV.fetch("PG_REPORTS_RAW_QUERY_RATE_LIMIT_WINDOW_SECONDS", 60).to_i
 
       # Grafana / Prometheus exporter
       @grafana_favorites = []

data/lib/pg_reports/grafana/exporter.rb

@@ -105,7 +105,11 @@ module PgReports
         mod = module_for(key) or raise ArgumentError, "Unknown report: #{key}"
 
         started = @clock.now
-        report = mod.public_send(key, **report_args(opts))
+        args = report_args(opts)
+        # Call with no arguments when there are no kwargs to forward. On Ruby 2.7
+        # `public_send(key, **{})` does not reliably elide to a no-arg call, which
+        # breaks report methods (and `have_received(...).with(no_args)` matchers).
+        report = args.empty? ? mod.public_send(key) : mod.public_send(key, **args)
         finished = @clock.now
 
         {

data/lib/pg_reports/standalone.rb

@@ -24,6 +24,10 @@ module PgReports
     # Rack handlers tried, in order, when none is named explicitly.
     CANDIDATE_SERVERS = %w[puma webrick].freeze
 
+    # Config files auto-loaded (first that exists), relative to the working
+    # directory, when no explicit --config path is given.
+    DEFAULT_CONFIG_FILES = %w[pg_reports.rb config/pg_reports.rb].freeze
+
     class ServerUnavailable < PgReports::Error; end
 
     # Boot the app and start a (blocking) web server.
@@ -34,14 +38,27 @@ module PgReports
     # @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")
+    # @param config_file [String, nil] path to a Ruby config file that calls
+    #   `PgReports.configure`; auto-detected from DEFAULT_CONFIG_FILES otherwise
+    # @param overrides [Hash] per-setting overrides applied last (from CLI flags);
+    #   nil values are ignored. Keys are Configuration attribute names.
     def run(port: DEFAULT_PORT, host: DEFAULT_HOST, mount_path: DEFAULT_MOUNT,
-      database_url: nil, server: nil)
+      database_url: nil, server: nil, config_file: nil, overrides: {})
       # 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)
 
+      # Mark this process as standalone so the dashboard can hide reports that
+      # only make sense with a host app (e.g. Schema Analysis, which introspects
+      # the host application's ActiveRecord models — there are none here).
+      PgReports.config.standalone = true
+
+      # Layer settings on top of the ENV-derived defaults: config file first, then
+      # explicit CLI overrides win.
+      apply_configuration(config_file: config_file, overrides: overrides)
+
       app = build_application(mount_path)
       app.initialize!
       verify_connection!
@@ -76,6 +93,47 @@ module PgReports
 
     private
 
+    # Apply configuration in increasing order of precedence:
+    #   ENV vars (already read when Configuration was built)
+    #     < config file (full Ruby, calls PgReports.configure)
+    #     < CLI overrides (individual flags)
+    #
+    # The config file is the escape hatch for every setting that has no dedicated
+    # flag — thresholds, Telegram, Grafana favorites, even the dashboard_auth
+    # proc. CLI flags cover only the handful of common security toggles.
+    def apply_configuration(config_file:, overrides:)
+      path = config_file || detect_config_file
+      load_config_file(path) if path
+
+      overrides.each do |key, value|
+        next if value.nil? # unset flag — leave the file/ENV value in place
+        PgReports.config.public_send(:"#{key}=", value)
+      end
+    end
+
+    # First existing DEFAULT_CONFIG_FILES entry (relative to the working dir), or
+    # nil when the user keeps no config file.
+    def detect_config_file
+      DEFAULT_CONFIG_FILES
+        .map { |f| File.expand_path(f, Dir.pwd) }
+        .find { |f| File.file?(f) }
+    end
+
+    # Evaluate a Ruby config file. A missing explicit path is an error (the user
+    # asked for it); a broken file is reported with context rather than a raw
+    # backtrace.
+    def load_config_file(path)
+      full = File.expand_path(path)
+      raise PgReports::Error, "Config file not found: #{path}" unless File.file?(full)
+
+      warn "pg_reports: loading config from #{full}"
+      load full
+    rescue PgReports::Error
+      raise
+    rescue => e
+      raise PgReports::Error, "Failed to load config file #{full}: #{e.message}"
+    end
+
     # 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.

data/lib/pg_reports/version.rb

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

data/lib/pg_reports.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# ActiveSupport < 7.1 relies on Ruby's `logger` being loaded implicitly, which
+# concurrent-ruby dropped in 1.3.5. Require it up front so pg_reports loads on
+# Rails 6.1/7.0 (and any bundle with a modern concurrent-ruby). Harmless on
+# newer Rails, which require it themselves.
+require "logger"
 require "active_support"
 require "active_support/core_ext"
 require "active_record"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_reports
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Eldar Avatov
@@ -160,6 +160,7 @@ files:
 - app/views/pg_reports/dashboard/index.html.erb
 - app/views/pg_reports/dashboard/show.html.erb
 - bin/pg_reports
+- config/brakeman.ignore
 - config/locales/en.yml
 - config/locales/ru.yml
 - config/locales/uk.yml