pg_reports 0.7.0 → 0.8.1

data/bin/pg_reports

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

data/config/locales/en.yml

@@ -592,6 +592,10 @@ en:
       navigation:
         dashboard: "Dashboard"
         back: "← Back"
+      database_selector:
+        label: "Database"
+      target_selector:
+        label: "Target"
       actions:
         cancel: "Cancel"
         retry: "Retry"
@@ -629,11 +633,12 @@ en:
         save_for_comparison: "📌 Save for Comparison"
         saved_marker: "📌 Saved"
       status:
-        pg_stat_ready: "pg_stat_statements ready"
-        extension_installed: "Extension installed, not preloaded"
-        preloaded: "Preloaded, extension not created"
-        not_configured: "Not configured"
-        monitoring_unavailable: "Live Monitoring Unavailable"
+        pg_stat_ready: "Active"
+        not_preloaded: "Preload required"
+        extension_missing: "Extension required"
+        disconnected: "No connection"
+        monitoring_unavailable: "Status Unavailable"
+        click_for_details: "Click to see how to enable it"
       modals:
         enable_pg_stat_title: "Enable pg_stat_statements"
         enable_pg_stat_intro: "To enable pg_stat_statements, follow these steps:"
@@ -641,6 +646,9 @@ en:
         restart_postgresql: "Restart PostgreSQL:"
         create_extension_step: "Create extension:"
         enable_button_note: "Or click \"Enable\" button after restart."
+        create_extension_title: "Create pg_stat_statements extension"
+        create_extension_intro: "The pg_stat_statements extension isn't created in this database yet. Click below to create it:"
+        create_extension_note: "If the library isn't preloaded, you'll also need to add it to shared_preload_libraries and restart PostgreSQL."
         reset_stats_title: "⚠️ Reset Statistics"
         reset_stats_confirm: "Are you sure you want to reset pg_stat_statements statistics?"
         reset_stats_warning: "This action will clear all collected query statistics and cannot be undone."
@@ -665,7 +673,7 @@ en:
         ide_cursor_wsl: "Cursor (WSL)"
         ide_cursor: "Cursor"
       monitoring:
-        live_title: "Live Monitoring"
+        live_title: "Status"
         update_interval: "Updates every 5s"
         toggle_title: "Toggle live monitoring"
         query_monitor_title: "SQL Query Monitor"
@@ -675,6 +683,8 @@ en:
         feed_no_queries: "No queries captured yet..."
         unknown_source: "Unknown source"
         expand_collapse_title: "Expand/Collapse"
+        scope_note_short: "scope: host application"
+        scope_note_long: "Query Monitor subscribes to ActiveSupport::Notifications in the host application's process. It captures every SQL the host app runs, on whichever database the host app is connected to. The dashboard's database selector does not change this scope."
       metrics:
         connections_label: "Connections"
         tps_label: "TPS"
@@ -685,7 +695,7 @@ en:
         cache_hit_detail: "heap blocks from cache"
         long_queries_label: "Long Queries"
         queries_unit: "queries"
-        long_running_threshold: "> 60s runtime"
+        long_running_threshold: "> 5s runtime"
         blocked_label: "Blocked"
         processes_unit: "processes"
         waiting_for_locks: "waiting for locks"
@@ -693,6 +703,7 @@ en:
       categories:
         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."
       documentation:
         toggle_title: "📖 What does this report show?"
         what_section: "📋 What"

data/config/locales/ru.yml

@@ -557,6 +557,10 @@ ru:
       navigation:
         dashboard: "Дашборд"
         back: "← Назад"
+      database_selector:
+        label: "База данных"
+      target_selector:
+        label: "Сервер"
       actions:
         cancel: "Отмена"
         retry: "Повторить"
@@ -594,11 +598,12 @@ ru:
         save_for_comparison: "📌 Сохранить для сравнения"
         saved_marker: "📌 Сохранено"
       status:
-        pg_stat_ready: "pg_stat_statements готов"
-        extension_installed: "Расширение установлено, не предзагружено"
-        preloaded: "Предзагружено, расширение не создано"
-        not_configured: "Не настроено"
-        monitoring_unavailable: "Live-мониторинг недоступен"
+        pg_stat_ready: "Активно"
+        not_preloaded: "Требуется предзагрузка"
+        extension_missing: "Требуется расширение"
+        disconnected: "Нет соединения"
+        monitoring_unavailable: "Статус недоступен"
+        click_for_details: "Нажмите, чтобы узнать, как включить"
       modals:
         enable_pg_stat_title: "Включение pg_stat_statements"
         enable_pg_stat_intro: "Чтобы включить pg_stat_statements, выполните следующие шаги:"
@@ -606,6 +611,9 @@ ru:
         restart_postgresql: "Перезапустите PostgreSQL:"
         create_extension_step: "Создайте расширение:"
         enable_button_note: "Или нажмите кнопку «Создать расширение» после перезапуска."
+        create_extension_title: "Создание расширения pg_stat_statements"
+        create_extension_intro: "Расширение pg_stat_statements ещё не создано в этой базе данных. Нажмите, чтобы создать его:"
+        create_extension_note: "Если библиотека не предзагружена, её также нужно добавить в shared_preload_libraries и перезапустить PostgreSQL."
         reset_stats_title: "⚠️ Сброс статистики"
         reset_stats_confirm: "Вы уверены, что хотите сбросить статистику pg_stat_statements?"
         reset_stats_warning: "Это действие очистит всю собранную статистику запросов и не может быть отменено."
@@ -630,7 +638,7 @@ ru:
         ide_cursor_wsl: "Cursor (WSL)"
         ide_cursor: "Cursor"
       monitoring:
-        live_title: "Live-мониторинг"
+        live_title: "Статус"
         update_interval: "Обновление каждые 5с"
         toggle_title: "Переключить live-мониторинг"
         query_monitor_title: "Монитор SQL-запросов"
@@ -640,6 +648,8 @@ ru:
         feed_no_queries: "Запросы пока не захвачены..."
         unknown_source: "Источник неизвестен"
         expand_collapse_title: "Развернуть / свернуть"
+        scope_note_short: "область: хост-приложение"
+        scope_note_long: "Монитор SQL-запросов подписан на ActiveSupport::Notifications в процессе хост-приложения и захватывает каждый SQL, который выполняет приложение, в той базе, к которой приложение подключено. Селектор базы данных в дашборде на эту область не влияет."
       metrics:
         connections_label: "Соединения"
         tps_label: "TPS"
@@ -650,7 +660,7 @@ ru:
         cache_hit_detail: "блоки heap из кэша"
         long_queries_label: "Долгие запросы"
         queries_unit: "запросов"
-        long_running_threshold: "> 60с выполнения"
+        long_running_threshold: "> 5с выполнения"
         blocked_label: "Заблокировано"
         processes_unit: "процессов"
         waiting_for_locks: "ждут блокировок"
@@ -658,6 +668,7 @@ ru:
       categories:
         requires_pg_stat: "🔒 Требуется pg_stat_statements"
         reports_count_suffix: "отчётов"
+        primary_only_reason: "🔒 Эта категория работает только на первичной базе — она проверяет модели хост-приложения. Чтобы пользоваться, переключитесь обратно на базу по умолчанию."
       documentation:
         toggle_title: "📖 Что показывает этот отчёт?"
         what_section: "📋 Что"

data/config/locales/uk.yml

@@ -557,6 +557,10 @@ uk:
       navigation:
         dashboard: "Дашборд"
         back: "← Назад"
+      database_selector:
+        label: "База даних"
+      target_selector:
+        label: "Сервер"
       actions:
         cancel: "Скасувати"
         retry: "Повторити"
@@ -594,11 +598,12 @@ uk:
         save_for_comparison: "📌 Зберегти для порівняння"
         saved_marker: "📌 Збережено"
       status:
-        pg_stat_ready: "pg_stat_statements готовий"
-        extension_installed: "Розширення встановлено, не передзавантажено"
-        preloaded: "Передзавантажено, розширення не створено"
-        not_configured: "Не налаштовано"
-        monitoring_unavailable: "Live-моніторинг недоступний"
+        pg_stat_ready: "Активно"
+        not_preloaded: "Потрібне передзавантаження"
+        extension_missing: "Потрібне розширення"
+        disconnected: "Немає з'єднання"
+        monitoring_unavailable: "Статус недоступний"
+        click_for_details: "Натисніть, щоб дізнатися, як увімкнути"
       modals:
         enable_pg_stat_title: "Увімкнення pg_stat_statements"
         enable_pg_stat_intro: "Щоб увімкнути pg_stat_statements, виконайте такі кроки:"
@@ -606,6 +611,9 @@ uk:
         restart_postgresql: "Перезапустіть PostgreSQL:"
         create_extension_step: "Створіть розширення:"
         enable_button_note: "Або натисніть кнопку «Створити розширення» після перезапуску."
+        create_extension_title: "Створення розширення pg_stat_statements"
+        create_extension_intro: "Розширення pg_stat_statements ще не створено в цій базі даних. Натисніть, щоб створити його:"
+        create_extension_note: "Якщо бібліотеку не передзавантажено, її також потрібно додати до shared_preload_libraries та перезапустити PostgreSQL."
         reset_stats_title: "⚠️ Скидання статистики"
         reset_stats_confirm: "Ви впевнені, що хочете скинути статистику pg_stat_statements?"
         reset_stats_warning: "Ця дія очистить усю зібрану статистику запитів і не може бути скасована."
@@ -630,7 +638,7 @@ uk:
         ide_cursor_wsl: "Cursor (WSL)"
         ide_cursor: "Cursor"
       monitoring:
-        live_title: "Live-моніторинг"
+        live_title: "Статус"
         update_interval: "Оновлення кожні 5с"
         toggle_title: "Перемкнути live-моніторинг"
         query_monitor_title: "Монітор SQL-запитів"
@@ -640,6 +648,8 @@ uk:
         feed_no_queries: "Запитів поки не захоплено..."
         unknown_source: "Джерело невідоме"
         expand_collapse_title: "Розгорнути / згорнути"
+        scope_note_short: "область: хост-застосунок"
+        scope_note_long: "Монітор SQL-запитів підписаний на ActiveSupport::Notifications у процесі хост-застосунку та захоплює кожен SQL, який виконує застосунок, у тій базі, до якої він підключений. Селектор бази даних у дашборді на цю область не впливає."
       metrics:
         connections_label: "З'єднання"
         tps_label: "TPS"
@@ -650,7 +660,7 @@ uk:
         cache_hit_detail: "блоки heap із кешу"
         long_queries_label: "Довгі запити"
         queries_unit: "запитів"
-        long_running_threshold: "> 60с виконання"
+        long_running_threshold: "> 5с виконання"
         blocked_label: "Заблоковано"
         processes_unit: "процесів"
         waiting_for_locks: "чекають блокувань"
@@ -658,6 +668,7 @@ uk:
       categories:
         requires_pg_stat: "🔒 Потрібен pg_stat_statements"
         reports_count_suffix: "звітів"
+        primary_only_reason: "🔒 Ця категорія працює лише на первинній базі — вона перевіряє моделі хост-застосунку. Щоб користуватися, перемкніться на базу за замовчуванням."
       documentation:
         toggle_title: "📖 Що показує цей звіт?"
         what_section: "📋 Що"

data/config/routes.rb

@@ -7,6 +7,9 @@ PgReports::Engine.routes.draw do
 
   get "live_metrics", to: "dashboard#live_metrics", as: :live_metrics
 
+  post "switch_database", to: "dashboard#switch_database", as: :switch_database
+  post "switch_target", to: "dashboard#switch_target", as: :switch_target
+
   post "enable_pg_stat_statements", to: "dashboard#enable_pg_stat_statements", as: :enable_pg_stat_statements
   post "reset_statistics", to: "dashboard#reset_statistics", as: :reset_statistics
   post "explain_analyze", to: "dashboard#explain_analyze", as: :explain_analyze

data/lib/pg_reports/configuration.rb

@@ -20,7 +20,7 @@ module PgReports
     attr_accessor :dead_rows_threshold          # Tables with more dead rows need vacuum
 
     # Connection settings
-    attr_accessor :connection_pool              # Custom connection pool (optional)
+    attr_accessor :connection_pool              # Custom connection pool (optional, legacy override)
 
     # Output settings
     attr_accessor :max_query_length             # Truncate query text to this length
@@ -41,6 +41,7 @@ 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/
 
     # Grafana / Prometheus exporter settings
     attr_accessor :grafana_favorites            # Reports exposed at /metrics (Array of keys or Hash with per-report opts)
@@ -92,6 +93,14 @@ module PgReports
       @allow_raw_query_execution = ActiveModel::Type::Boolean.new.cast(
         ENV.fetch("PG_REPORTS_ALLOW_RAW_QUERY_EXECUTION", false)
       )
+      # Migration creation defaults to Rails dev — preserves prior behavior —
+      # but is now explicitly togglable so it can be disabled even in dev.
+      env_override = ENV["PG_REPORTS_ALLOW_MIGRATION_CREATION"]
+      @allow_migration_creation = if env_override.nil?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.development?
+      else
+        ActiveModel::Type::Boolean.new.cast(env_override)
+      end
 
       # Grafana / Prometheus exporter
       @grafana_favorites = []
@@ -100,7 +109,28 @@ module PgReports
     end
 
     def connection
-      @connection_pool || ActiveRecord::Base.connection
+      return @connection_pool if @connection_pool
+
+      PgReports.connection_registry.current_connection
+    end
+
+    # Register an additional named target (besides the auto-detected :primary).
+    # Spec accepts the same keys as ActiveRecord::Base.establish_connection.
+    #
+    # Example:
+    #   config.add_target :analytics,
+    #     host: "...", user: "...", password: ENV["..."], database: "warehouse"
+    def add_target(name, spec)
+      PgReports.connection_registry.register(name, spec)
+    end
+
+    # Override the default target name (default is :primary).
+    def default_target=(name)
+      PgReports.connection_registry.default_name = name
+    end
+
+    def default_target
+      PgReports.connection_registry.default_name
     end
 
     def telegram_configured?

data/lib/pg_reports/connection/error_translator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Connection
+    # Translates raw PG / ActiveRecord exceptions into human-readable messages
+    # with concrete remediation hints (typically a GRANT statement).
+    #
+    # Usage:
+    #   PgReports::Connection::ErrorTranslator.translate(error)
+    #   # => { title: "...", detail: "...", hint: "GRANT ...", code: "42501" }
+    module ErrorTranslator
+      module_function
+
+      # Returns a Hash with :title, :detail, :hint, :code, :raw_message.
+      # The shape is suitable for rendering in the dashboard.
+      def translate(error)
+        sqlstate = sqlstate_for(error)
+        message = error.message.to_s
+
+        info = case sqlstate
+        when "42501" then permission_denied(message)
+        when "3D000" then database_does_not_exist(message)
+        when "28000", "28P01" then auth_failed(message)
+        when "08001", "08006", "08000", "08003", "08004" then connection_refused(message)
+        when "53300" then too_many_connections(message)
+        else generic(error)
+        end
+
+        info.merge(code: sqlstate, raw_message: message)
+      end
+
+      def sqlstate_for(error)
+        case error
+        when PG::Error
+          error.result&.error_field(PG::Result::PG_DIAG_SQLSTATE)
+        when ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+          sqlstate_for(error.cause) if error.cause && !error.cause.equal?(error)
+        end
+      rescue
+        nil
+      end
+
+      def permission_denied(message)
+        target = extract_object(message, /permission denied for (?:database|schema|table|relation|view) "?([\w.]+)"?/)
+        kind = extract_object(message, /permission denied for (database|schema|table|relation|view)/)
+
+        hint = if kind && target
+          case kind
+          when "database" then "GRANT CONNECT ON DATABASE #{target} TO <role>;"
+          when "schema" then "GRANT USAGE ON SCHEMA #{target} TO <role>;"
+          when "table", "relation", "view" then "GRANT SELECT ON #{target} TO <role>;"
+          end
+        end
+
+        {
+          title: "Permission denied",
+          detail: (kind && target) ? "The connecting role does not have the required privilege on #{kind} \"#{target}\"." : "The connecting role lacks the required privilege.",
+          hint: hint
+        }
+      end
+
+      def database_does_not_exist(message)
+        target = extract_object(message, /database "([^"]+)" does not exist/)
+        {
+          title: "Database not found",
+          detail: target ? "PostgreSQL has no database named \"#{target}\"." : "The requested database does not exist on this server.",
+          hint: nil
+        }
+      end
+
+      def auth_failed(_message)
+        {
+          title: "Authentication failed",
+          detail: "PostgreSQL rejected the credentials for this target.",
+          hint: "Verify the username/password in the target configuration; check pg_hba.conf for the connecting host."
+        }
+      end
+
+      def connection_refused(_message)
+        {
+          title: "Cannot reach PostgreSQL",
+          detail: "The server is unreachable or refused the connection.",
+          hint: "Check host/port, network reachability, and that PostgreSQL is accepting connections."
+        }
+      end
+
+      def too_many_connections(_message)
+        {
+          title: "Too many connections",
+          detail: "PostgreSQL refused the connection because max_connections is reached.",
+          hint: "Wait, increase max_connections, or use a connection pooler (PgBouncer)."
+        }
+      end
+
+      def generic(error)
+        {
+          title: error.class.name.split("::").last,
+          detail: error.message,
+          hint: nil
+        }
+      end
+
+      def extract_object(message, regex)
+        match = message.match(regex)
+        match && match[1]
+      end
+    end
+  end
+end

data/lib/pg_reports/connection/registry.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module PgReports
+  module Connection
+    # Registry of named PostgreSQL targets.
+    #
+    # In a Rails app the :primary target is auto-registered on first access from
+    # ActiveRecord::Base.connection_db_config — no configuration is required.
+    # Additional targets can be registered explicitly via Configuration#add_target
+    # for setups where the dashboard should reach databases the host app cannot.
+    #
+    # Current target/database is tracked in a Thread.current slot, switched via
+    # PgReports.with_target / PgReports.with_database for block-scoped usage.
+    class Registry
+      THREAD_KEY_TARGET = :pg_reports_current_target
+      THREAD_KEY_DATABASE = :pg_reports_current_database
+
+      class UnknownTarget < PgReports::Error; end
+
+      def initialize
+        @targets = {}
+        @default_name = :primary
+        @auto_registered = false
+        @mutex = Mutex.new
+      end
+
+      attr_reader :default_name
+
+      def default_name=(name)
+        @default_name = name.to_sym
+      end
+
+      # Register or overwrite a target.
+      def register(name, spec)
+        @targets[name.to_sym] = Target.new(name, spec)
+      end
+
+      # All known targets (auto-registers :primary if needed first).
+      def targets
+        ensure_default_registered!
+        @targets.values
+      end
+
+      def target_names
+        targets.map(&:name)
+      end
+
+      def target?(name)
+        targets.any? { |t| t.name == name.to_sym }
+      end
+
+      def fetch(name = nil)
+        ensure_default_registered!
+        key = (name || current_name || @default_name).to_sym
+        @targets.fetch(key) { raise UnknownTarget, "Unknown target #{key.inspect}. Known: #{@targets.keys.inspect}" }
+      end
+
+      # Resolve the AR connection to use right now (current target + database).
+      # Honors PgReports.with_target / with_database thread-local context.
+      def current_connection
+        target = fetch(current_name)
+        target.connection_for(current_database)
+      end
+
+      # Returns the target that current_connection would resolve to.
+      def current_target
+        fetch(current_name)
+      end
+
+      # The database name in effect for the current target.
+      def current_database_name
+        current_database || fetch(current_name).default_database
+      end
+
+      def current_name
+        Thread.current[THREAD_KEY_TARGET]
+      end
+
+      def current_database
+        Thread.current[THREAD_KEY_DATABASE]
+      end
+
+      # Switch target and/or database for the duration of the block. Semantics:
+      # - target given      → switches target AND clears the database override
+      #                       (the previous database belongs to the previous
+      #                       target's cluster and would not be valid on a new
+      #                       one). Pass `database:` explicitly to override on
+      #                       the new target.
+      # - target nil        → keeps the active target, switches only database.
+      # - database nil      → uses the (possibly new) target's default database.
+      def with_context(target: nil, database: nil)
+        prev_target = Thread.current[THREAD_KEY_TARGET]
+        prev_database = Thread.current[THREAD_KEY_DATABASE]
+
+        if target
+          Thread.current[THREAD_KEY_TARGET] = target.to_sym
+          Thread.current[THREAD_KEY_DATABASE] = database&.to_s
+        elsif database
+          Thread.current[THREAD_KEY_DATABASE] = database.to_s
+        end
+
+        yield
+      ensure
+        Thread.current[THREAD_KEY_TARGET] = prev_target
+        Thread.current[THREAD_KEY_DATABASE] = prev_database
+      end
+
+      # For tests / reload scenarios. Restores the registry to a fresh state —
+      # closes all derived pools, drops all registered targets, resets
+      # default_name back to :primary, and re-arms auto-registration.
+      def reset!
+        @mutex.synchronize do
+          @targets.each_value(&:disconnect!)
+          @targets.clear
+          @default_name = :primary
+          @auto_registered = false
+        end
+      end
+
+      # Auto-discover the :primary target from ActiveRecord on first need.
+      # Idempotent and thread-safe.
+      def ensure_default_registered!
+        return if @auto_registered
+        return unless defined?(ActiveRecord::Base)
+
+        @mutex.synchronize do
+          return if @auto_registered
+
+          unless @targets.key?(:primary)
+            spec = primary_spec_from_active_record
+            @targets[:primary] = Target.new(:primary, spec) if spec
+          end
+
+          @auto_registered = true
+        end
+      end
+
+      private
+
+      def primary_spec_from_active_record
+        config = ActiveRecord::Base.connection_db_config
+        return nil unless config
+
+        config.configuration_hash.transform_keys(&:to_sym)
+      rescue ActiveRecord::ConnectionNotEstablished
+        nil
+      end
+    end
+  end
+end