pg_reports 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67cc51703472362dd188536abd8196660d5e4bb928d9f9ee53d7e2939290772e
-  data.tar.gz: 99fe7733e13344ac1e6b0a9a981728525005437a36e6c17846da455de5365a9b
+  metadata.gz: 2ff4489af5016c4bfbe14f7187daa5ca2ea279b15887bab928c8effefc4b2dad
+  data.tar.gz: 26815859090bbf8a84000acb3545c1eecb982887f8d0f07d9ab0e582f2380c58
 SHA512:
-  metadata.gz: f408472b95f858f7770511b89885afd98b14074ee5fa3ed67c75ae36b29cb34a96adf1ac17ec0f6cf69bb9cbb51843def46483ff60ee121e2317d930da23deaf
-  data.tar.gz: fb4760d0e84fbe5a29b157cb37ee765454e7a26863a01b64aee1ba4262d83b28272e16664b7e797981f72594deb192e7f1a22a0c93ef6fb1399d584932446d91
+  metadata.gz: f94d1f175001f3a8140d8ef9b826d353bb20963d3b75487aace882fde54186466be500840252bc9e87268e55244bb96746f59fd82b6ba648271a828b596b47d4
+  data.tar.gz: f89ff6622a18f3daf33fabf898a8736da510e2ecf84f4455e5720a8a07f3a219ed1336a1f1a286437a23da505560e724679bb27957b74b501567db2cfaee9f17

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-07-03
+
+### Added
+
+- **Standalone mode — run the dashboard without a host Rails app.** A new `pg_reports server` executable (and `rake pg_reports:server` task) boots a minimal Rails application that mounts the engine at `/` and serves it on port **4000**, straight from the gem's root folder. The connection is resolved from `--database-url`, then `DATABASE_URL`, then libpq-style `PG*` env vars; flags cover `--port`, `--host`, `--mount`, and `--server`. All existing multi-database / multi-cluster switching works unchanged, since the connection registry auto-registers the standalone connection as the `:primary` target.
+  - **No new runtime dependencies.** `rack` and `rackup` already ship transitively via `actionpack`/`railties`; the web server (Puma, WEBrick, …) is resolved at run time and is not a hard dependency — the runner uses whichever is installed and prints a clear message if none is.
+  - New `PgReports::Standalone` module encapsulating app construction, connection resolution, and server boot.
+  - `./bin/pg_reports` runs from a checkout without `bundle exec` via a soft bundler shim (activated only when a Gemfile sits next to the executable; skipped for the installed gem).
+  - **[docs/standalone.md](docs/standalone.md).**
+- **Dashboard footer** with links to the project on GitHub and a contact address.
+- **ESC closes any open modal.** A single global handler triggers the modal's own close button, so per-modal cleanup still runs.
+
+### Changed
+
+- **Redesigned the pg_stat_statements status badge.** The header badge now reports four clearly distinguished states with plain-language labels instead of a raw identifier glued to an adjective (`pg_stat_statements готовий`):
+  - 🟢 **Active** — monitoring works.
+  - 🟡 **Preload required** — the extension exists but isn't in `shared_preload_libraries`; clicking the badge opens the setup instructions.
+  - 🟡 **Extension required** — the library is loaded but the extension isn't created; clicking opens a modal with a one-click **Create extension** button.
+  - 🔴 **No connection** — the database itself is unreachable.
+  Warning/error badges are now clickable and self-explanatory. The redundant `?` info button and the header **Create extension** button were removed in favor of the badge-driven modals. Labels no longer use a negative "Not …" framing. Translations updated for `en` / `uk` / `ru`.
+- **pg_stat_statements status detection no longer reads `shared_preload_libraries`.** That setting requires the `pg_read_all_settings` role and is unreadable by a typical monitoring user, which made the "preloaded but extension missing" state unreachable. State is now derived entirely from signals every role can observe: connectivity (`SELECT 1`), extension presence in `pg_extension`, and whether the `pg_stat_statements` view is queryable. `pg_stat_statements_status` gains a `connected:` key, and `PgReports.system.connected?` is a new public helper.
+- **Primary buttons toned down.** `btn-primary` (Start monitoring, Run report, Create extension, …) switched from a solid accent fill to a subtle tinted style, so it reads as the accent action without dominating the page.
+- **Live-metrics "long queries" threshold lowered from 60s to 5s** — the default the top-of-dashboard tile counts against.
+- **Header/layout polish** — the status badge, settings button, and Reset button are unified to the same height; the settings button is now square; the pg_stat_statements category warning banner no longer overhangs its card; and the "scope: host application" note in the query monitor uses a real styled tooltip (hover + keyboard focus) instead of the unreliable native `title`.
+- **README trimmed**: standalone, Telegram, and Grafana/Prometheus details moved to dedicated docs ([docs/standalone.md](docs/standalone.md), [docs/telegram.md](docs/telegram.md), [docs/grafana.md](docs/grafana.md)).
+
+### Fixed
+
+- **Query Monitor no longer records pg_reports' own queries.** Internal queries (live-metrics polling, status checks, database listing) run through `Executor`/`Target` are now tagged with a `"PgReports"` statement name, so `QueryMonitor#should_skip?` filters them by name regardless of backtrace depth. Previously the deep `ActiveSupport::Notifications` stack could push the pg_reports frames past the 30-frame backtrace scan, leaking these queries into the monitor history.
+- **Dashboard requests broke when the engine is mounted at the root path** (e.g. standalone). The client base path resolved to `/`, so `fetch` URLs became `//live_metrics` — a protocol-relative URL the browser sent to a bogus host, breaking live metrics and report runs. The base now strips a trailing slash.
+
+## [0.8.0] - 2026-05-01
+
+### Added
+
+- **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,18 @@ 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).
+
+## Standalone (no host app)
+
+You can also run the dashboard on its own, straight from the gem's root folder — no Rails app to mount it in. It serves at `/` on port **4000** and connects via `DATABASE_URL` or libpq env vars:
+
+```bash
+./bin/pg_reports server        # from a checkout; no `bundle exec` needed
+DATABASE_URL=postgres://user:pass@localhost/myapp bundle exec pg_reports server
+```
+
+Adds no runtime dependencies to the gem. **[Standalone guide → docs/standalone.md](docs/standalone.md)**
 
 ## Usage
 
@@ -72,114 +84,45 @@ report = PgReports.expensive_queries
 report.to_text
 report.to_csv
 report.to_a
+```
+
+**[Full list of reports →](docs/reports.md)**  ·  **[Send reports to Telegram →](docs/telegram.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.
 
-# Telegram
-PgReports.slow_queries.send_to_telegram
+Programmatic access:
+
+```ruby
+PgReports.with_database("logs")    { PgReports.table_sizes }
+PgReports.with_target(:analytics)  { PgReports.slow_queries }
 ```
 
-**[Full list of reports →](docs/reports.md)**
+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.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, raw query execution, source tracking, locale —**
+**[full reference in docs/configuration.md →](docs/configuration.md)** &nbsp;·&nbsp; **[Telegram](docs/telegram.md)** &nbsp;·&nbsp; **[Grafana / Prometheus](docs/grafana.md)**
 
 ## Report object
 
@@ -303,66 +246,9 @@ The Export dropdown includes **Copy Prompt** (visible on actionable reports). It
 <details>
 <summary><strong>Grafana / Prometheus exporter</strong></summary>
 
-Expose selected reports at `<mount_point>/metrics` in Prometheus exposition format. The default mount is `/pg_reports`, so the endpoint is typically `/pg_reports/metrics` — but it follows whatever path you used in `mount PgReports::Engine, at: "..."`. Severity (`ok` / `warning` / `critical`) is derived automatically from the thresholds defined in [`Dashboard::ReportsRegistry::REPORT_CONFIG`](lib/pg_reports/dashboard/reports_registry.rb).
-
-```ruby
-PgReports.configure do |config|
-  config.grafana_favorites = [
-    :slow_queries,
-    :unused_indexes,
-    :bloated_tables,
-    :missing_validations,
-    :polymorphic_without_index
-  ]
-  config.grafana_metrics_token = ENV["PG_REPORTS_METRICS_TOKEN"]  # optional bearer token
-  config.grafana_cache_ttl     = 60                                # seconds
-end
-```
-
-Scrape with Prometheus:
-
-```yaml
-scrape_configs:
-  - job_name: pg_reports
-    metrics_path: /pg_reports/metrics    # adjust to your Engine mount point
-    scrape_interval: 60s
-    authorization: { credentials: "${PG_REPORTS_METRICS_TOKEN}" }
-    static_configs:
-      - targets: ["app.internal:3000"]
-```
-
-> [!WARNING]
-> Reports are cached via `Rails.cache` for `grafana_cache_ttl` so frequent scrapes don't hammer the database. Without it, Prometheus' default 15s scrape interval against heavy reports like `missing_validations` will DDoS your own DB. Always set a TTL ≥ scrape interval, and consider a longer per-report TTL for expensive reports.
-
-The exporter also emits a `pg_reports_row` series per report row (each column becomes a Prometheus label), so the auto-generated dashboard can show a **table panel** with the actual rows that need fixing — not just an aggregate count.
-
-Generate a matching Grafana dashboard from the same favorites:
-
-```bash
-bundle exec rake pg_reports:grafana:dashboard
-# writes pg_reports.json in pwd; then Dashboards → Import in Grafana
-```
-
-**[Full Grafana integration guide →](docs/grafana.md)** &nbsp;·&nbsp; **[Local Prometheus + Grafana without Docker →](docs/grafana-local-setup.md)**
-
-</details>
-
-<details>
-<summary><strong>Telegram delivery</strong></summary>
-
-Get a bot token from [@BotFather](https://t.me/BotFather) and your chat ID from [@userinfobot](https://t.me/userinfobot), then:
-
-```ruby
-PgReports.configure do |config|
-  config.telegram_bot_token = "123456:ABC-DEF..."
-  config.telegram_chat_id   = "-1001234567890"
-end
-
-PgReports.slow_queries.send_to_telegram
-PgReports.health_report.send_to_telegram_as_file
-```
+Expose selected reports at `<mount_point>/metrics` in Prometheus exposition format, with severity (`ok` / `warning` / `critical`) derived automatically from each report's thresholds. Reports are cached per a configurable TTL so frequent scrapes don't hammer the database, and a matching Grafana dashboard can be generated from the same favorites (`rake pg_reports:grafana:dashboard`).
 
-Reports under ~50 rows go as a message; larger ones are sent as a file attachment.
+**[Grafana / Prometheus integration guide →](docs/grafana.md)** &nbsp;·&nbsp; **[Local Prometheus + Grafana without Docker →](docs/grafana-local-setup.md)**
 
 </details>
 
@@ -386,8 +272,8 @@ bundle exec rubocop
 
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Acknowledgments
 
-Inspired by [rails-pg-extras](https://github.com/pawurb/rails-pg-extras). UI built with [Claude](https://www.anthropic.com/claude) by Anthropic.
+Inspired by [rails-pg-extras](https://github.com/pawurb/rails-pg-extras) and built with ❤️ for the Rails community.

data/app/controllers/pg_reports/dashboard_controller.rb

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