rails-pg-extras 5.6.15 → 5.6.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1b176294ac8dfee0602dac9a7719b685cbe2b4303bf96421853a87a1f7fdd1b
-  data.tar.gz: 2a9208ba3675bda0ff32fa6da55cf68f8bcfa70b1ecdf51d3456d505acaf56a9
+  metadata.gz: 714a0f5659226e30d168cac200be9fa570ff608977b2ac8400a13e18a1c1e1f5
+  data.tar.gz: 803ec924433eeda21828d30ff23524007a108db4dfc02d83002fb4b0b2527fc6
 SHA512:
-  metadata.gz: 6fde9b532cc4afeb2581405cb11f51d965de7d5a68f7dd89feddf2646a9d1c2281b354a8f7a67d74378758f8f1cacf6658dabac8dc8d9b30f2b387231fb23dc9
-  data.tar.gz: 341f88edb6018e20d42994f9520961a0f5fc0c0a82118d4ceff76b626ef86188d7f9253b92b964048036555ab819b56eead63943cfa3f1e364871c051f4c9d5b
+  metadata.gz: d0da5717b4d0483ff82707da9ba19715e2d6d8a26feb46d77e0fae3a41a75d9c7dbc03f1881998752f6ece95984c4db408050218fc87bea43731ef3ebe1f0dc5
+  data.tar.gz: 1d72247f4fed436a0220051b98ba8e0ea619b2f12737c2958c895c73d8e19050a707d3baa96479de968248f5aa431a532f9aee358e533322727d12f2c9fa1ec7

data/README.md

@@ -12,7 +12,7 @@ Optionally you can enable a visual interface:
 
 ![Web interface](https://github.com/pawurb/rails-pg-extras/raw/main/pg-extras-ui-3.png)
 
-[rails-pg-extras-mcp gem](https://github.com/pawurb/rails-pg-extras-mcp) provides an MCP (Model Context Protocol) interface enabling PostgreSQL metadata and performance analysis with an LLM support.  
+[rails-pg-extras-mcp gem](https://github.com/pawurb/rails-pg-extras-mcp) provides an MCP (Model Context Protocol) interface enabling PostgreSQL metadata and performance analysis with an LLM support.
 
 ![LLM interface](https://github.com/pawurb/rails-pg-extras/raw/main/pg-extras-mcp.png)
 
@@ -57,16 +57,27 @@ You should see the similar line in the output:
 RailsPgExtras.add_extensions
 ```
 
-By default a primary ActiveRecord database connection is used for running metadata queries, rake tasks and web UI. To connect to a different database you can specify an `ENV['RAILS_PG_EXTRAS_DATABASE_URL']` value in the following format:
+By default rails-pg-extras uses your app’s default `ActiveRecord::Base.connection` (typically `primary`) for running metadata queries, rake tasks and the web UI.
+
+If your app uses Rails multiple databases, the web UI can switch connections dynamically. It reads the available database names from `ActiveRecord::Base.configurations` for the current environment and selects one via the `db_key` query param (thread-local per request, so it’s safe under concurrency):
+
+```ruby
+# examples
+/pg_extras?db_key=primary
+/pg_extras?db_key=animals
+```
+
+To connect to a database that isn’t defined in `database.yml` (or when using rake tasks / Ruby API outside the web UI), you can also provide an explicit URL via `ENV['RAILS_PG_EXTRAS_DATABASE_CONFIG']`:
 
 ```ruby
-ENV["RAILS_PG_EXTRAS_DATABASE_URL"] = "postgresql://postgres:secret@localhost:5432/database_name"
+ENV["RAILS_PG_EXTRAS_DATABASE_CONFIG"] = "postgresql://postgres:secret@localhost:5432/database_name"
 ```
 
-Alternatively, you can specify database URL with a method call:
+Alternatively, you can specify database configuration with a method call:
 
 ```ruby
-RailsPgExtras.database_url = "postgresql://postgres:secret@localhost:5432/database_name"
+RailsPgExtras.database_config = "postgresql://postgres:secret@localhost:5432/database_name"
+RailsPgExtras.database_config = :rails_pg_extras
 ```
 
 ## Usage
@@ -158,7 +169,7 @@ RailsPgExtras.configure do |config|
 end
 ```
 
-You can also configure a default ignore list for the heuristic missing foreign key constraints checker. This helps skip columns that you know should not be considered foreign keys.
+You can also configure default ignore lists for the missing foreign key checkers. This helps skip columns that you know should not be considered foreign keys (constraints) or you intentionally do not want to index (indexes).
 
 ```ruby
 RailsPgExtras.configure do |config|
@@ -168,9 +179,11 @@ RailsPgExtras.configure do |config|
   # - "posts.*"           (ignore all columns on a table)
   # - "*"                 (ignore everything)
   config.missing_fk_constraints_ignore_list = ["posts.category_id", "category_id"]
+  config.missing_fk_indexes_ignore_list = ["feedbacks.team_id", "legacy_id"]
 
   # Or as a comma-separated string:
   # config.missing_fk_constraints_ignore_list = "posts.category_id, category_id"
+  # config.missing_fk_indexes_ignore_list = "feedbacks.team_id, legacy_id"
 end
 ```
 
@@ -238,7 +251,7 @@ you can add this info to the output:
 
 ### `missing_fk_indexes`
 
-This method lists columns likely to be foreign keys (i.e. column name ending in `_id` and related table exists) which don't have an index. It's recommended to always index foreign key columns because they are used for searching relation objects. 
+This method lists **actual foreign key columns** (based on existing foreign key constraints) which don't have a supporting index. It's recommended to always index foreign key columns because they are commonly used for lookups and join conditions.
 
 You can add indexes on the columns returned by this query and later check if they are receiving scans using the [unused_indexes method](#unused_indexes). Please remember that each index decreases write performance and autovacuuming overhead, so be careful when adding multiple indexes to often updated tables.
 
@@ -258,12 +271,32 @@ RailsPgExtras.missing_fk_indexes(args: { table_name: "users" })
 
 `table_name` argument is optional, if omitted, the method will display missing fk indexes for all the tables.
 
+You can also exclude known/intentional cases using `ignore_list` (array or comma-separated string), with entries like:
+- "posts.category_id" (ignore a specific table+column)
+- "category_id" (ignore this column name for all tables)
+- "posts.*" (ignore all columns on a table)
+- "*" (ignore everything)
+
+```ruby
+RailsPgExtras.missing_fk_indexes(args: { table_name: "users", ignore_list: ["feedbacks.team_id", "posts.*"] })
+```
+
 ## `missing_fk_constraints`
 
-Similarly to the previous method, this one shows columns likely to be foreign keys that don't have a corresponding foreign key constraint. Foreign key constraints improve data integrity in the database by preventing relations with nonexisting objects. You can read more about the benefits of using foreign keys [in this blog post](https://pawelurbanek.com/rails-postgresql-data-integrity).
+This method shows **columns that look like foreign keys** but don't have a corresponding foreign key constraint yet. Foreign key constraints improve data integrity in the database by preventing relations with nonexisting objects. You can read more about the benefits of using foreign keys [in this blog post](https://pawelurbanek.com/rails-postgresql-data-integrity).
+
+Heuristic notes:
+- A column is considered a candidate if it matches `<table_singular>_id` and the related table exists (underscored prefixes like `account_user_id` are supported).
+- Rails polymorphic associations (`<name>_id` + `<name>_type`) are ignored since they cannot be expressed as real FK constraints.
+
+You can also exclude known/intentional cases using `ignore_list` (array or comma-separated string), with entries like:
+- "posts.category_id" (ignore a specific table+column)
+- "category_id" (ignore this column name for all tables)
+- "posts.*" (ignore all columns on a table)
+- "*" (ignore everything)
 
 ```ruby
-RailsPgExtras.missing_fk_constraints(args: { table_name: "users" })
+RailsPgExtras.missing_fk_constraints(args: { table_name: "users", ignore_list: ["users.customer_id", "posts.*"] })
 
 +---------------------------------+
 | Missing foreign key constraints |
@@ -278,12 +311,6 @@ RailsPgExtras.missing_fk_constraints(args: { table_name: "users" })
 
 `table_name` argument is optional, if omitted, method will display missing fk constraints for all the tables.
 
-You can optionally pass an `ignore_list` to skip known false positives detected by the heuristic checker. It accepts an Array or a comma-separated String. Entries can be:
-- "posts.category_id" to ignore a specific table+column
-- "category_id" to ignore a column name for all tables
-- "posts.*" to ignore all columns on a specific table
-- "*" to ignore everything
-
 Examples:
 
 ```ruby
@@ -533,7 +560,7 @@ $ rake pg_extras:calls
 (truncated results for brevity)
 ```
 
-This command is much like `pg:outliers`, but ordered by the number of times a statement has been called. 
+This command is much like `pg:outliers`, but ordered by the number of times a statement has been called.
 
 [More info](https://pawelurbanek.com/postgresql-fix-performance#missing-indexes)
 

data/app/views/rails_pg_extras/web/queries/show.html.erb

@@ -3,7 +3,8 @@
 
 <br>
 
-<%= link_to "← Back to Diagnose", queries_path,
+<%= link_to "← Back to Diagnose",
+            queries_path(params[:db_key].present? ? { db_key: params[:db_key] } : {}),
             class: "inline-block bg-blue-500 text-white font-medium px-4 py-2 rounded-lg shadow-md hover:bg-blue-600 transition" %>
 
 <% if @error %>

data/lib/rails-pg-extras.rb

@@ -12,7 +12,10 @@ require "rails_pg_extras/table_info"
 require "rails_pg_extras/table_info_print"
 
 module RailsPgExtras
-  @@database_url = nil
+  extend self
+
+  @@database_config = nil
+
   QUERIES = RubyPgExtras::QUERIES
   DEFAULT_ARGS = RubyPgExtras::DEFAULT_ARGS
   NEW_PG_STAT_STATEMENTS = RubyPgExtras::NEW_PG_STAT_STATEMENTS
@@ -28,7 +31,7 @@ module RailsPgExtras
     end
   end
 
-  def self.run_query(query_name:, in_format:, args: {})
+  def run_query(query_name:, in_format:, args: {})
     RubyPgExtras.run_query_base(
       query_name: query_name,
       conn: connection,
@@ -38,7 +41,7 @@ module RailsPgExtras
     )
   end
 
-  def self.diagnose(in_format: :display_table)
+  def diagnose(in_format: :display_table)
     data = RailsPgExtras::DiagnoseData.call
 
     if in_format == :display_table
@@ -50,14 +53,14 @@ module RailsPgExtras
     end
   end
 
-  def self.measure_duration(&block)
+  def measure_duration(&block)
     starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     block.call
     ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     (ending - starting) * 1000
   end
 
-  def self.measure_queries(&block)
+  def measure_queries(&block)
     queries = {}
     sql_duration = 0
 
@@ -105,7 +108,7 @@ module RailsPgExtras
     }
   end
 
-  def self.index_info(args: {}, in_format: :display_table)
+  def index_info(args: {}, in_format: :display_table)
     data = RailsPgExtras::IndexInfo.call(args[:table_name])
 
     if in_format == :display_table
@@ -119,7 +122,7 @@ module RailsPgExtras
     end
   end
 
-  def self.table_info(args: {}, in_format: :display_table)
+  def table_info(args: {}, in_format: :display_table)
     data = RailsPgExtras::TableInfo.call(args[:table_name])
 
     if in_format == :display_table
@@ -133,77 +136,82 @@ module RailsPgExtras
     end
   end
 
-  def self.missing_fk_indexes(args: {}, in_format: :display_table)
-    result = RailsPgExtras::MissingFkIndexes.call(args[:table_name])
+  def missing_fk_indexes(args: {}, in_format: :display_table)
+    ignore_list = args[:ignore_list]
+    ignore_list ||= RailsPgExtras.configuration.missing_fk_indexes_ignore_list
+    result = RailsPgExtras::MissingFkIndexes.call(args[:table_name], ignore_list: ignore_list)
     RubyPgExtras.display_result(result, title: "Missing foreign key indexes", in_format: in_format)
   end
 
-  def self.missing_fk_constraints(args: {}, in_format: :display_table)
+  def missing_fk_constraints(args: {}, in_format: :display_table)
     ignore_list = args[:ignore_list]
     ignore_list ||= RailsPgExtras.configuration.missing_fk_constraints_ignore_list
     result = RailsPgExtras::MissingFkConstraints.call(args[:table_name], ignore_list: ignore_list)
     RubyPgExtras.display_result(result, title: "Missing foreign key constraints", in_format: in_format)
   end
 
-  def self.database_url=(value)
-    @@database_url = value
+  def database_config
+    @@database_config
+  end
+
+  # Deprecated
+  alias_method :database_url, :database_config
+
+  def database_config=(value)
+    @@database_config = value
   end
 
-  def self.connection
+  # Deprecated
+  alias_method :database_url=, :database_config=
+
+  def connection
     # Priority:
     # 1) Per-request selected db (thread-local), if present -> use named configuration or URL without altering global Base
-    # 2) Explicit URL via setter or ENV override
+    # 2) Explicit config via setter or ENV override
     # 3) Default ActiveRecord::Base connection
     selected_db_key = Thread.current[:rails_pg_extras_db_key]
-    db_url = @@database_url || ENV["RAILS_PG_EXTRAS_DATABASE_URL"]
+    config = @@database_config || ENV["RAILS_PG_EXTRAS_DATABASE_CONFIG"] || ENV["RAILS_PG_EXTRAS_DATABASE_URL"] # Latter is deprecated
 
     if selected_db_key.present?
-      const_name = selected_db_key.classify
-      # Use an isolated abstract class to avoid changing the global connection
-      thread_classes = (Thread.current[:rails_pg_extras_ar_classes] ||= {})
-      ar_class = (thread_classes[selected_db_key] ||= begin
-        if const_defined?(const_name, false)
-          const_get(const_name, false)
-        else
-          klass = Class.new(ActiveRecord::Base)
-          klass.abstract_class = true
-          const_set(const_name, klass)
-        end
-      end)
+      # Prefix thread class key to avoid collisions
+      ar_class = fetch_or_define_ar_class(thread_class_key: "database_#{selected_db_key}", const_name: selected_db_key.classify)
 
-      connector = ar_class.establish_connection(selected_db_key.to_sym)
+      establish_connection(ar_class: ar_class, config: selected_db_key.to_sym)
+    elsif config.present?
+      ar_class = fetch_or_define_ar_class(thread_class_key: :database_config, const_name: :PgExtrasDatabaseConfig)
 
-      if connector.respond_to?(:connection)
-        connector.connection
-      elsif connector.respond_to?(:lease_connection)
-        connector.lease_connection
-      else
-        raise "Unsupported connector: #{connector.class}"
-      end
-    elsif db_url.present?
-      # Use an isolated abstract class to avoid changing the global connection
-      thread_classes = (Thread.current[:rails_pg_extras_ar_classes] ||= {})
-      ar_class = (thread_classes[:database_url] ||= begin
-        if const_defined?(:PgExtrasURLConn, false)
-          const_get(:PgExtrasURLConn, false)
-        else
-          klass = Class.new(ActiveRecord::Base)
-          klass.abstract_class = true
-          const_set(:PgExtrasURLConn, klass)
-        end
-      end)
+      establish_connection(ar_class: ar_class, config: config)
+    else
+      ActiveRecord::Base.connection
+    end
+  end
+
+  private
 
-      connector = ar_class.establish_connection(db_url)
+  # Use an isolated abstract class to avoid changing the global connection
+  def fetch_or_define_ar_class(thread_class_key:, const_name:)
+    thread_classes = Thread.current[:rails_pg_extras_ar_classes] ||= {}
 
-      if connector.respond_to?(:connection)
-        connector.connection
-      elsif connector.respond_to?(:lease_connection)
-        connector.lease_connection
+    thread_classes[thread_class_key] ||=
+      if const_defined?(const_name, false)
+        const_get(const_name, false)
       else
-        raise "Unsupported connector: #{connector.class}"
+        klass = Class.new(ActiveRecord::Base)
+        klass.abstract_class = true
+
+        const_set(const_name, klass)
       end
+  end
+
+  def establish_connection(ar_class:, config:)
+    connector = ar_class.establish_connection(config)
+
+    if connector.respond_to?(:connection)
+      connector.connection
+    elsif connector.respond_to?(:lease_connection)
+      connector.lease_connection
     else
-      ActiveRecord::Base.connection
+      raise "Unsupported connector: #{connector.class}"
     end
   end
 end

data/lib/rails_pg_extras/configuration.rb

@@ -4,16 +4,18 @@ require "rails_pg_extras/web"
 
 module RailsPgExtras
   class Configuration
-    DEFAULT_CONFIG = { enabled_web_actions: Web::ACTIONS - [:kill_all, :kill_pid], public_dashboard: ENV["RAILS_PG_EXTRAS_PUBLIC_DASHBOARD"] == "true", missing_fk_constraints_ignore_list: [] }
+    DEFAULT_CONFIG = { enabled_web_actions: Web::ACTIONS - [:kill_all, :kill_pid], public_dashboard: ENV["RAILS_PG_EXTRAS_PUBLIC_DASHBOARD"] == "true", missing_fk_constraints_ignore_list: [], missing_fk_indexes_ignore_list: [] }
 
     attr_reader :enabled_web_actions
     attr_accessor :public_dashboard
     attr_accessor :missing_fk_constraints_ignore_list
+    attr_accessor :missing_fk_indexes_ignore_list
 
     def initialize(attrs)
       self.enabled_web_actions = attrs[:enabled_web_actions]
       self.public_dashboard = attrs[:public_dashboard]
       self.missing_fk_constraints_ignore_list = attrs[:missing_fk_constraints_ignore_list]
+      self.missing_fk_indexes_ignore_list = attrs[:missing_fk_indexes_ignore_list]
     end
 
     def enabled_web_actions=(*actions)

data/lib/rails_pg_extras/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsPgExtras
-  VERSION = "5.6.15"
+  VERSION = "5.6.16"
 end

data/spec/smoke_spec.rb

@@ -40,15 +40,29 @@ describe RailsPgExtras do
     expect(output.fetch(:count) > 0).to eq(true)
   end
 
+  it "supports custom RAILS_PG_EXTRAS_DATABASE_CONFIG that specifies an URL" do
+    old_value = ENV["RAILS_PG_EXTRAS_DATABASE_CONFIG"]
+    ENV["RAILS_PG_EXTRAS_DATABASE_CONFIG"] = ENV["DATABASE_URL"]
+    puts ENV["RAILS_PG_EXTRAS_DATABASE_CONFIG"]
+
+    expect do
+      RailsPgExtras.calls
+    end.not_to raise_error
+  ensure
+    ENV["RAILS_PG_EXTRAS_DATABASE_CONFIG"] = old_value
+  end
+
+  # Deprecated
   it "supports custom RAILS_PG_EXTRAS_DATABASE_URL" do
+    old_value = ENV["RAILS_PG_EXTRAS_DATABASE_URL"]
     ENV["RAILS_PG_EXTRAS_DATABASE_URL"] = ENV["DATABASE_URL"]
     puts ENV["RAILS_PG_EXTRAS_DATABASE_URL"]
 
     expect do
       RailsPgExtras.calls
     end.not_to raise_error
-
-    ENV["RAILS_PG_EXTRAS_DATABASE_URL"] = nil
+  ensure
+    ENV["RAILS_PG_EXTRAS_DATABASE_URL"] = old_value
   end
 
   describe "missing_fk_indexes" do
@@ -67,14 +81,30 @@ describe RailsPgExtras do
     end
   end
 
+  it "database_config does not affect global connection" do
+    original_connection = ActiveRecord::Base.connection
+
+    old_value = RailsPgExtras.database_config
+    RailsPgExtras.database_config = ENV["DATABASE_URL"]
+    RailsPgExtras.calls
+
+    # Verify global connection unchanged
+    expect(ActiveRecord::Base.connection).to eq(original_connection)
+  ensure
+    RailsPgExtras.database_config = old_value
+  end
+
+  # Deprecated
   it "database_url does not affect global connection" do
     original_connection = ActiveRecord::Base.connection
 
+    old_value = RailsPgExtras.database_url
     RailsPgExtras.database_url = ENV["DATABASE_URL"]
     RailsPgExtras.calls
-    RailsPgExtras.database_url = nil
 
     # Verify global connection unchanged
     expect(ActiveRecord::Base.connection).to eq(original_connection)
+  ensure
+    RailsPgExtras.database_url = old_value
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-pg-extras
 version: !ruby/object:Gem::Version
-  version: 5.6.15
+  version: 5.6.16
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-16 00:00:00.000000000 Z
+date: 2026-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-pg-extras
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.6.15
+        version: 5.6.16
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.6.15
+        version: 5.6.16
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement