pg_reports 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67cc51703472362dd188536abd8196660d5e4bb928d9f9ee53d7e2939290772e
-  data.tar.gz: 99fe7733e13344ac1e6b0a9a981728525005437a36e6c17846da455de5365a9b
+  metadata.gz: 70975bd7aa15cac037bc8ac3f658c7cabe1e7492a3c37a1db588c92bce3d0f3d
+  data.tar.gz: 587f0a5474d427303c483603467155c4e0602ff604d5628c39e45d7137d1354d
 SHA512:
-  metadata.gz: f408472b95f858f7770511b89885afd98b14074ee5fa3ed67c75ae36b29cb34a96adf1ac17ec0f6cf69bb9cbb51843def46483ff60ee121e2317d930da23deaf
-  data.tar.gz: fb4760d0e84fbe5a29b157cb37ee765454e7a26863a01b64aee1ba4262d83b28272e16664b7e797981f72594deb192e7f1a22a0c93ef6fb1399d584932446d91
+  metadata.gz: 3174ba9362c38d77da9a41653453de23e6c462fac8be71ceacf82b645fffb68343eb09421df8cfbab9f1100d1ca70fbca6234bc3a4450e83e5be9c35079653da
+  data.tar.gz: 70f91b168cc0890414741f75de6aea545400d738ef2a00e5a664a7555aac9bcfd923ba53ce169ca2ffa610efe9dbd95ff26902c77dcbfcf79b872421cf63e644

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-01
+
+### Added
+
+- **Multi-database dashboard.** Switch between databases on the connected cluster from a dropdown in the dashboard header — no configuration required. The selected database persists across requests in the session and applies to every report on every page.
+  - New `PgReports::Connection::Registry` with auto-registered `:primary` target derived from `ActiveRecord::Base.connection_db_config`. Existing setups need no changes.
+  - New block-scoped APIs: `PgReports.with_target(:name, database: ...)`, `PgReports.with_database("name")`. Honored by `Executor` even when memoized inside modules — the connection is now resolved on every call rather than at construction.
+  - New helpers: `PgReports.list_databases`, `PgReports.list_targets`, `PgReports.current_target_name`, `PgReports.current_database_name`.
+  - New `Configuration#add_target(name, spec)` and `default_target=` for explicitly registering additional targets (host/port/user/database) when the dashboard should reach databases the host app cannot.
+  - Database switching opens an isolated AR connection pool per `(target, database)` so the host application's pool is never disturbed; the primary target's default database keeps using `ActiveRecord::Base` directly.
+- **Human-readable connection errors.** `PgReports::Connection::ErrorTranslator` maps `PG::Error` SQLSTATEs (`42501`, `3D000`, `28P01`, `08006`, `53300`) and AR-wrapped variants into a `{ title, detail, hint, code }` hash. Permission errors include a concrete `GRANT ...` remediation hint. The dashboard renders the translation as a banner on the index when it can't list databases.
+- **Schema Analysis category gated to the primary target.** When the dashboard is pointed at a non-primary database (where the host app's models don't apply), the Schema Analysis category is greyed out with an explanation, and direct URL access redirects to the index with a flash message. Same gating extends to the JSON endpoints (`run`, `download`, `send_to_telegram`).
+- **Configuration reference** moved to [docs/configuration.md](docs/configuration.md).
+
+### Security
+
+- **CSRF protection** is now enforced on the dashboard controller (`protect_from_forgery with: :exception`). Previously the controller inherited from `ActionController::Base` without opting in — every state-changing endpoint (`switch_database`, `switch_target`, `execute_query`, `explain_analyze`, `create_migration`, `reset_statistics`, telegram delivery, query_monitor start/stop) was reachable cross-origin from any logged-in user's browser. The dashboard already shipped `authenticity_token` in forms and `X-CSRF-Token` in XHR — only the server enforcement was missing.
+- **`create_migration` is now opt-in via `config.allow_migration_creation`** (default `Rails.env.development?` to preserve prior behavior; toggleable via `PG_REPORTS_ALLOW_MIGRATION_CREATION`). The endpoint writes Ruby code into `db/migrate/`. With CSRF fixed and a denied-by-default flag, a dashboard exposed without auth no longer trivially leads to RCE on next `rails db:migrate`. Combine with `dashboard_auth` for layered defense.
+
 ## [0.7.0] - 2026-04-26
 
 ### Added

data/README.md

@@ -5,12 +5,13 @@
 [![Rails](https://img.shields.io/badge/Rails-5.0%2B-red.svg)](https://rubyonrails.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A comprehensive PostgreSQL monitoring and analysis library for Rails applications. Get insights into query performance, index usage, table statistics, connection health, and more. Includes a beautiful web dashboard and Telegram integration for notifications.
+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.
 
 ![Dashboard Screenshot](docs/dashboard.png)
 
 ## Features
 
+- 🗄️ **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
 - 📋 **Table Statistics** - Monitor table sizes, bloat, vacuum needs, and cache hit ratios
@@ -58,7 +59,7 @@ end
 
 Visit `http://localhost:3000/pg_reports`.
 
-For query analysis, also enable `pg_stat_statements` — see [setup](#pg_stat_statements-setup) below.
+For query analysis, also enable `pg_stat_statements` — see [setup instructions in docs/configuration.md](docs/configuration.md#pg_stat_statements-setup).
 
 ## Usage
 
@@ -79,107 +80,43 @@ PgReports.slow_queries.send_to_telegram
 
 **[Full list of reports →](docs/reports.md)**
 
+## Multi-database
+
+The dashboard auto-discovers every database on the cluster you're connected to and shows a dropdown next to the *Status* panel. Switching is zero-config — credentials and host come from your existing `database.yml`. Schema-analysis reports stay scoped to the primary database (they introspect the host app's models); the dropdown greys them out elsewhere.
+
+Programmatic access:
+
+```ruby
+PgReports.with_database("logs")    { PgReports.table_sizes }
+PgReports.with_target(:analytics)  { PgReports.slow_queries }
+```
+
+For multi-cluster setups (separate analytics warehouse, replica with different credentials, etc.), register additional targets explicitly. **[Multi-database reference in docs/configuration.md →](docs/configuration.md#multi-database-support)**
+
 ## Configuration
 
+PgReports works out of the box once mounted. Common options:
+
 ```ruby
 # config/initializers/pg_reports.rb
 PgReports.configure do |config|
-  # Telegram (optional)
-  config.telegram_bot_token = ENV["PG_REPORTS_TELEGRAM_TOKEN"]
-  config.telegram_chat_id   = ENV["PG_REPORTS_TELEGRAM_CHAT_ID"]
-
-  # Thresholds
+  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.heavy_query_threshold_calls  = 1000
-  config.expensive_query_threshold_ms = 10_000
   config.unused_index_threshold_scans = 50
   config.bloat_threshold_percent      = 20
-  config.dead_rows_threshold          = 10_000
 
-  # Output
-  config.max_query_length = 200
-
-  # Auth (optional)
+  # Strongly recommended in production
   config.dashboard_auth = -> {
     authenticate_or_request_with_http_basic do |user, pass|
       user == ENV["PG_REPORTS_USER"] && pass == ENV["PG_REPORTS_PASSWORD"]
     end
   }
-
-  # Google Fonts (default: false — no external requests)
-  config.load_external_fonts = false
 end
 ```
 
-<details>
-<summary><strong>Locale (EN / RU / UK)</strong></summary>
-
-PgReports follows your application's `I18n.locale`. Set it the way you set it for the rest of the app — there's no PgReports-specific knob. The dashboard supports `en`, `ru`, and `uk` out of the box.
-
-</details>
-
-<details>
-<summary><strong>Raw query execution (EXPLAIN ANALYZE / Execute Query)</strong></summary>
-
-⚠️ Disabled by default. The dashboard's "Execute Query" and "EXPLAIN ANALYZE" buttons require this opt-in.
-
-```ruby
-PgReports.configure do |config|
-  config.allow_raw_query_execution = Rails.env.development? || Rails.env.staging?
-end
-```
-
-</details>
-
-<details>
-<summary><strong>Query source tracking (Rails query logs)</strong></summary>
-
-PgReports parses query annotations to show **where queries originated**. On Rails 7.0+ use the built-in `ActiveRecord::QueryLogs` (no extra gem needed). On older Rails, install [Marginalia](https://github.com/basecamp/marginalia) — PgReports auto-detects both formats.
-
-Minimal setup — adds controller/action:
-
-```ruby
-# config/application.rb
-config.active_record.query_log_tags_enabled = true
-config.active_record.query_log_tags = [:controller, :action]
-```
-
-To also surface **file path and line number** (so source links jump to the actual call site, not just the controller), add a custom `source_location` lambda that walks `caller_locations` and skips gem/framework frames:
-
-```ruby
-# config/application.rb
-config.active_record.query_log_tags_enabled = true
-config.active_record.query_log_tags = [
-  :controller,
-  :action,
-  :job,
-  {
-    source_location: -> {
-      ignore = %r{/(gems|active_record|active_support|active_model|railties|
-                    action_controller|action_view|action_pack|action_dispatch|
-                    rack|core_ext|relation|associations|scoping|connection_adapters)/}x
-      loc = caller_locations.find { |l| !l.path.match?(ignore) }
-      "#{loc.path}:#{loc.lineno}" if loc
-    }
-  }
-]
-```
-
-PgReports recognizes the `source_location` tag and splits it into file and line for the **source** column.
-
-</details>
-
-## pg_stat_statements setup
-
-1. Edit `postgresql.conf`:
-   ```
-   shared_preload_libraries = 'pg_stat_statements'
-   pg_stat_statements.track = all
-   ```
-2. Restart PostgreSQL: `sudo systemctl restart postgresql`
-3. Create the extension (via dashboard button or `PgReports.enable_pg_stat_statements!`).
-
-> PgReports does **not** require the `pg_read_all_settings` role — extension availability is detected directly. Works with CloudnativePG, managed databases, and other restricted environments.
+**Multi-database, thresholds, query monitor, Grafana, raw query execution, source tracking, locale, Telegram —**
+**[full reference in docs/configuration.md →](docs/configuration.md)**
 
 ## Report object
 

data/app/controllers/pg_reports/dashboard_controller.rb

@@ -4,14 +4,59 @@ module PgReports
   class DashboardController < ActionController::Base
     layout "pg_reports/application"
 
+    # CSRF protection. ActionController::Base does NOT enforce this by default;
+    # we opt in explicitly because every state-changing endpoint here
+    # (switch_*, execute_query, create_migration, reset_statistics, telegram
+    # delivery, query_monitor start/stop) is sensitive. The dashboard already
+    # ships authenticity_token in forms and X-CSRF-Token in XHR.
+    protect_from_forgery with: :exception
+
     before_action :authenticate_dashboard!, if: -> { PgReports.config.dashboard_auth.present? }
     before_action :set_categories
+    before_action :resolve_database_selection
+    around_action :within_selected_database
+
+    helper_method :category_disabled_reason, :category_disabled?
 
     def index
       @pg_stat_status = PgReports.pg_stat_statements_status
       @current_database = PgReports.system.current_database
     end
 
+    # POST /switch_database
+    # Persists the chosen database in session and redirects back. The actual
+    # connection switch happens on the next request via #within_selected_database.
+    def switch_database
+      requested = params[:database].to_s
+
+      if requested.empty?
+        session.delete(:pg_reports_database)
+      elsif valid_database?(requested)
+        session[:pg_reports_database] = requested
+      end
+
+      redirect_back fallback_location: root_path
+    end
+
+    # POST /switch_target
+    # Persists the chosen target in session, clears the database choice (each
+    # target has its own list of databases), and redirects back.
+    def switch_target
+      requested = params[:target].to_s
+
+      if requested.empty?
+        session.delete(:pg_reports_target)
+        session.delete(:pg_reports_database)
+      elsif PgReports.connection_registry.target?(requested)
+        session[:pg_reports_target] = requested
+        # Database list is target-specific; reset so the next request picks the
+        # new target's default rather than carrying a stale name.
+        session.delete(:pg_reports_database)
+      end
+
+      redirect_back fallback_location: root_path
+    end
+
     def enable_pg_stat_statements
       result = PgReports.enable_pg_stat_statements!
       render json: result
@@ -72,6 +117,12 @@ module PgReports
         return
       end
 
+      reason = category_disabled_reason(@category)
+      if reason
+        redirect_to root_path, alert: reason
+        return
+      end
+
       # Get documentation for the report
       @documentation = Dashboard::ReportsRegistry.documentation(@report_key)
       @thresholds = Dashboard::ReportsRegistry.thresholds(@report_key)
@@ -322,8 +373,7 @@ module PgReports
     end
 
     def create_migration
-      # Only allow migration creation in development environment
-      unless Rails.env.development?
+      unless PgReports.config.allow_migration_creation
         render json: {
           success: false,
           error: I18n.t("pg_reports.ui.errors.migration_dev_only")
@@ -492,6 +542,68 @@ module PgReports
       @categories = Dashboard::ReportsRegistry.all
     end
 
+    # Resolves which target/database every action should run against, based on:
+    # 1. session[:pg_reports_target]   (set by #switch_target)
+    # 2. session[:pg_reports_database] (set by #switch_database)
+    # Falls back to the registry's default target and that target's default
+    # database when either is missing or invalid.
+    #
+    # Exposes @selected_target / @available_targets / @selected_database /
+    # @available_databases / @target_default_database / @database_error for the
+    # layout to render the selectors. Connection errors are swallowed so the
+    # dashboard still renders with a banner instead of a 500.
+    def resolve_database_selection
+      registry = PgReports.connection_registry
+
+      # Target resolution (must come first — database list depends on it)
+      @available_targets = registry.targets
+      requested_target = session[:pg_reports_target].to_s
+      @selected_target = if requested_target.present? && registry.target?(requested_target)
+        requested_target.to_sym
+      else
+        registry.default_name
+      end
+
+      # Resolve database list under the chosen target so list_databases hits
+      # the right cluster.
+      @available_databases = []
+      @database_error = nil
+      @target_default_database = registry.fetch(@selected_target).default_database
+
+      begin
+        registry.with_context(target: @selected_target) do
+          @available_databases = registry.fetch(@selected_target).list_databases(current: @target_default_database)
+        end
+      rescue => e
+        @database_error = PgReports::Connection::ErrorTranslator.translate(e)
+      end
+
+      requested_database = session[:pg_reports_database].to_s
+      @selected_database = if requested_database.present? && @available_databases.any? { |d| d["name"] == requested_database }
+        requested_database
+      else
+        @target_default_database
+      end
+    end
+
+    def within_selected_database
+      database_override = (@selected_database && @selected_database != @target_default_database) ? @selected_database : nil
+      target_override = (@selected_target && @selected_target != PgReports.connection_registry.default_name) ? @selected_target : nil
+
+      if target_override || database_override
+        PgReports.with_target(target_override || PgReports.connection_registry.default_name,
+          database: database_override) { yield }
+      else
+        yield
+      end
+    end
+
+    def valid_database?(name)
+      # Reuse the list already fetched in #resolve_database_selection so the
+      # switch_database POST hits pg_database once per request, not twice.
+      Array(@available_databases).any? { |row| row["name"] == name }
+    end
+
     def load_report_filters(category, report_key)
       definition = ReportLoader.get(category.to_s, report_key.to_s)
       return {} unless definition
@@ -530,6 +642,9 @@ module PgReports
     end
 
     def execute_report(category, report_key, **filter_params)
+      reason = category_disabled_reason(category)
+      raise ArgumentError, reason if reason
+
       mod = case category
       when :queries then Modules::Queries
       when :indexes then Modules::Indexes
@@ -547,6 +662,31 @@ module PgReports
       mod.public_send(report_key, **filter_params)
     end
 
+    # nil if the category is available in the current target/database context,
+    # otherwise a localized string explaining why it is disabled. Exposed to
+    # views via helper_method.
+    def category_disabled_reason(category)
+      constraint = Dashboard::ReportsRegistry.target_constraint(category)
+      return nil unless constraint == :primary_default_database_only
+      return nil if on_primary_default_database?
+
+      I18n.t("pg_reports.ui.categories.primary_only_reason",
+        default: "This report category only runs on the primary database " \
+          "because it inspects the host application's models. Switch back to " \
+          "the default database to use it.")
+    end
+
+    def category_disabled?(category)
+      category_disabled_reason(category).present?
+    end
+
+    def on_primary_default_database?
+      return true if @target_default_database.nil?
+
+      @selected_target == PgReports.connection_registry.default_name &&
+        @selected_database == @target_default_database
+    end
+
     def substitute_params(query, params_hash)
       result = query.dup
 

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

@@ -633,6 +633,16 @@
       font-size: 0.9rem;
     }
 
+    .query-monitoring-scope {
+      font-weight: 400;
+      font-size: 0.75rem;
+      color: var(--text-muted);
+      background: var(--bg-tertiary);
+      padding: 0.125rem 0.5rem;
+      border-radius: 999px;
+      cursor: help;
+    }
+
     .monitoring-indicator {
       width: 7px;
       height: 7px;
@@ -989,6 +999,121 @@
     .modal-small {
       max-width: 360px;
     }
+
+    /* 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. */
+    .db-selector-form {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5rem;
+      margin: 0;
+      max-width: 100%;
+      min-width: 0;
+    }
+
+    .db-selector-label {
+      font-size: 0.75rem;
+      color: var(--text-secondary);
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      font-weight: 600;
+      white-space: nowrap;
+    }
+
+    .db-selector {
+      background: var(--bg-card, rgba(255, 255, 255, 0.04));
+      color: var(--text-primary);
+      border: 1px solid var(--border-color, rgba(255, 255, 255, 0.1));
+      border-radius: 6px;
+      padding: 0.375rem 0.625rem;
+      font-size: 0.875rem;
+      cursor: pointer;
+      width: auto;
+      max-width: 100%;
+      min-width: 0;
+    }
+
+    .db-selector option.is-default {
+      font-weight: 700;
+    }
+
+    .db-selector:hover {
+      border-color: var(--accent-blue, #6b9fe8);
+    }
+
+    .db-selector:focus {
+      outline: none;
+      border-color: var(--accent-blue, #6b9fe8);
+      box-shadow: 0 0 0 2px rgba(107, 159, 232, 0.2);
+    }
+
+    .db-selector-static {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5rem;
+      font-size: 0.875rem;
+      color: var(--text-secondary);
+    }
+
+    .db-selector-static strong {
+      color: var(--text-primary);
+    }
+
+    .db-selector-error {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.375rem;
+      padding: 0.375rem 0.625rem;
+      background: rgba(232, 107, 107, 0.1);
+      border: 1px solid rgba(232, 107, 107, 0.3);
+      border-radius: 6px;
+      font-size: 0.8125rem;
+      color: var(--accent-red, #e86b6b);
+      cursor: help;
+    }
+
+    .breadcrumb-spacer {
+      flex: 1;
+    }
+
+    .breadcrumb {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+    }
+
+    .db-error-banner {
+      background: rgba(232, 107, 107, 0.08);
+      border: 1px solid rgba(232, 107, 107, 0.3);
+      border-radius: 8px;
+      padding: 0.875rem 1.125rem;
+      margin-bottom: 1rem;
+      display: flex;
+      flex-direction: column;
+      gap: 0.375rem;
+    }
+
+    .db-error-banner strong {
+      color: var(--accent-red, #e86b6b);
+      font-size: 0.9375rem;
+    }
+
+    .db-error-banner span {
+      font-size: 0.875rem;
+      color: var(--text-secondary);
+    }
+
+    .db-error-banner code {
+      font-family: ui-monospace, SFMono-Regular, monospace;
+      font-size: 0.8125rem;
+      background: rgba(0, 0, 0, 0.25);
+      padding: 0.375rem 0.625rem;
+      border-radius: 4px;
+      color: var(--text-primary);
+      display: inline-block;
+      width: fit-content;
+    }
   </style>
 </head>
 <body>

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

@@ -0,0 +1,39 @@
+<%# locals: (show_label: true) %>
+<% if @available_databases.present? && @available_databases.size > 1 %>
+  <form class="db-selector-form"
+        action="<%= switch_database_path %>"
+        method="post"
+        data-turbo="false">
+    <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+    <% if local_assigns.fetch(:show_label, true) %>
+      <label class="db-selector-label" for="pg-reports-db-select">
+        <%= t("pg_reports.ui.database_selector.label", default: "Database") %>
+      </label>
+    <% end %>
+    <select id="pg-reports-db-select"
+            name="database"
+            class="db-selector"
+            onchange="this.form.submit()">
+      <% @available_databases.each do |row| %>
+        <option value="<%= row["name"] %>"
+                class="<%= "is-default" if row["name"] == @target_default_database %>"
+                <%= "selected" if row["name"] == @selected_database %>>
+          <%= row["name"] %><%= " (#{row["size"]})" if row["size"].present? %>
+        </option>
+      <% end %>
+    </select>
+  </form>
+<% elsif @available_databases.present? && @available_databases.size == 1 %>
+  <span class="db-selector-static">
+    <% if local_assigns.fetch(:show_label, true) %>
+      <span class="db-selector-label">
+        <%= t("pg_reports.ui.database_selector.label", default: "Database") %>:
+      </span>
+    <% end %>
+    <strong><%= @available_databases.first["name"] %></strong>
+  </span>
+<% elsif @database_error %>
+  <span class="db-selector-error" title="<%= @database_error[:detail] %>">
+    ⚠ <%= @database_error[:title] %>
+  </span>
+<% end %>

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

@@ -0,0 +1,27 @@
+<%# locals: (show_label: true) %>
+<% if @available_targets.present? && @available_targets.size > 1 %>
+  <form class="db-selector-form"
+        action="<%= switch_target_path %>"
+        method="post"
+        data-turbo="false">
+    <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+    <% if local_assigns.fetch(:show_label, true) %>
+      <label class="db-selector-label" for="pg-reports-target-select">
+        <%= t("pg_reports.ui.target_selector.label", default: "Target") %>
+      </label>
+    <% end %>
+    <select id="pg-reports-target-select"
+            name="target"
+            class="db-selector"
+            onchange="this.form.submit()">
+      <% default_target_name = PgReports.connection_registry.default_name %>
+      <% @available_targets.each do |target| %>
+        <option value="<%= target.name %>"
+                class="<%= "is-default" if target.name == default_target_name %>"
+                <%= "selected" if target.name == @selected_target %>>
+          <%= target.name %><%= " (#{target.default_database})" if target.default_database.present? %>
+        </option>
+      <% end %>
+    </select>
+  </form>
+<% end %>