ruby-pg-extras 5.6.18 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0de82c2381f728d09ea04bad7af74d9fce31ab7f73c5ffa6fa1b52741d0e25bf
-  data.tar.gz: a24730c633b7a9747b074d574d701aa5fa4f2cc1f764c7ce684c5934d3ab29d4
+  metadata.gz: a23e8afe840227303cb0b15ddd0c795f94dd4004b45a6ca8239da7724b8ffe3d
+  data.tar.gz: fd6d80e6150e1a74ae8d360553dba71de05f9241086894038669f412a39c2376
 SHA512:
-  metadata.gz: 275eee2d2e060752bbde7bc2be03d3cbb1a9af878b1fcc909016613eaa5ad7ccd00a24b59e0238f7e981f692bf984971a1813004109ad31cbd98a6329da93962
-  data.tar.gz: 70b3e1d3b5123bf7e472c1122b1471742aae4693193854f4825ed10c3fae519b4c2313d889fcaded7e50c7b9db7d387f72af26d46404027cccde62f2a41bde15
+  metadata.gz: 2cc3296eb55474f029b0189ab1e7356a209690da28c97ef63898f55f16adaf544d940fd553454e4172e0a46d8a3bee4722e4ee6e56109cb686a969161f137d52
+  data.tar.gz: 1b06eab3cd36804cced29754d5506386d2a4e7eefd445d7b4edc3ac6737b04ace5e27f0aa7913ff5a8ed8e796beda5766cd6ce9a1f9c31172b9186505fba3bfa

data/README.md

@@ -120,6 +120,8 @@ Keep reading to learn about methods that `diagnose` uses under the hood.
 
 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.
 
+Composite indexes only support a foreign key when the foreign key column is the leftmost key column. For example, an index on `(user_id, topic_id)` supports `user_id` lookups, but `topic_id` still needs its own index or an index that starts with `topic_id`. Partial indexes are ignored for this check unless their predicate is exactly the foreign key column `IS NOT NULL`, because foreign key checks only need non-null values.
+
 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.
 
 ```ruby
@@ -225,20 +227,21 @@ RubyPgExtras.table_foreign_keys(args: { table_name: "users" })
 
 ### `index_info`
 
-This method returns summary info about database indexes. You can check index size, how often it is used and what percentage of its total size are NULL values. Like the previous method, it aggregates data from other helper methods in an easy-to-digest format.
+This method returns summary info about database indexes. You can check index size, how often it is used, whether it is unique/primary/partial, what predicate it uses, and what percentage of its total size are NULL values. Like the previous method, it aggregates data from other helper methods in an easy-to-digest format.
+
+Index columns are read from PostgreSQL catalog metadata instead of parsing `CREATE INDEX` strings. This keeps expression indexes, operator classes, sort order, collations, partial predicates, and `INCLUDE` columns represented correctly. `Columns` shows the display form of key columns, while `Included columns` shows non-key columns added with `INCLUDE (...)`.
 
 ```ruby
 
 RubyPgExtras.index_info(args: { table_name: "users" })
 
-| Index name                    | Table name | Columns        | Index size | Index scans | Null frac |
-+-------------------------------+------------+----------------+------------+-------------+-----------+
-| users_pkey                    | users      | id             | 1152 kB    | 163007      | 0.00%     |
-| index_users_on_slack_id       | users      | slack_id       | 1080 kB    | 258870      | 0.00%     |
-| index_users_on_team_id        | users      | team_id        | 816 kB     | 70962       | 0.00%     |
-| index_users_on_uuid           | users      | uuid           | 1032 kB    | 0           | 0.00%     |
-| index_users_on_block_uuid     | users      | block_uuid     | 776 kB     | 19502       | 100.00%   |
-| index_users_on_api_auth_token | users      | api_auth_token | 1744 kB    | 156         | 0.00%     |
+| Index name                   | Table name | Columns                    | Included columns | Method | Unique | Primary | Partial | Predicate          | Index size | Index scans | Null frac |
++------------------------------+------------+----------------------------+------------------+--------+--------+---------+---------+--------------------+------------+-------------+-----------+
+| users_pkey                   | users      | id                         |                  | btree  | true   | true    | false   |                    | 1152 kB    | 163007      | 0.00%     |
+| index_users_on_email_pattern | users      | email text_pattern_ops     |                  | btree  | false  | false   | false   |                    | 1080 kB    | 258870      | 0.00%     |
+| index_users_on_created_at    | users      | created_at DESC NULLS LAST |                  | btree  | false  | false   | false   |                    | 816 kB     | 70962       | 0.00%     |
+| index_users_on_active_email  | users      | email                      |                  | btree  | false  | false   | true    | deleted_at IS NULL | 1032 kB    | 0           | 0.00%     |
+| index_users_on_email_include | users      | email                      | id               | btree  | false  | false   | false   |                    | 776 kB     | 19502       | 100.00%   |
 
 ```
 

data/lib/ruby_pg_extras/index_info.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require "json"
+
 module RubyPgExtras
   class IndexInfo
     def self.call(table_name = nil)
@@ -19,7 +23,17 @@ module RubyPgExtras
         {
           index_name: index_name,
           table_name: index_data.fetch("tablename"),
-          columns: index_data.fetch("columns").split(",").map(&:strip),
+          # Prefer JSON arrays from indexes.sql so expressions containing commas are not split incorrectly.
+          columns: array_value(index_data, json_key: "columns_json", fallback_key: "columns"),
+          # Clean key column names are used separately from display columns that may include opclasses/order/collations.
+          key_columns: array_value(index_data, json_key: "key_column_names", fallback_key: "key_columns"),
+          # INCLUDE columns are stored separately because they are not part of the index search key.
+          included_columns: array_value(index_data, json_key: "included_columns_json", fallback_key: "included_columns"),
+          index_method: index_data.fetch("index_method", "N/A"),
+          unique: boolean_value(index_data.fetch("is_unique", false)),
+          primary: boolean_value(index_data.fetch("is_primary", false)),
+          partial: boolean_value(index_data.fetch("is_partial", false)),
+          predicate: index_data.fetch("predicate", nil),
           index_size: index_size_data.find do |el|
             el.fetch("name") == index_name
           end.fetch("size", "N/A"),
@@ -54,6 +68,22 @@ module RubyPgExtras
 
     private
 
+    def array_value(index_data, json_key:, fallback_key:)
+      # Older/stubbed callers may only provide comma-separated fields, so keep a fallback path.
+      if index_data.key?(json_key) && index_data.fetch(json_key) != nil
+        JSON.parse(index_data.fetch(json_key)).compact
+      elsif index_data.key?(fallback_key) && index_data.fetch(fallback_key) != nil
+        index_data.fetch(fallback_key).split(",").map(&:strip).reject(&:empty?)
+      else
+        []
+      end
+    end
+
+    def boolean_value(value)
+      # PG::Result returns booleans as "t"/"f"; specs may provide real Ruby booleans.
+      [true, "t", "true"].include?(value)
+    end
+
     def query_module
       RubyPgExtras
     end

data/lib/ruby_pg_extras/index_info_print.rb

@@ -14,6 +14,13 @@ module RubyPgExtras
           el.fetch(:index_name),
           el.fetch(:table_name),
           el.fetch(:columns).join(", "),
+          # Included columns are displayed separately because they do not affect the index key order.
+          el.fetch(:included_columns, []).join(", "),
+          el.fetch(:index_method, "N/A"),
+          el.fetch(:unique, false),
+          el.fetch(:primary, false),
+          el.fetch(:partial, false),
+          el.fetch(:predicate, nil),
           el.fetch(:index_size),
           el.fetch(:index_scans),
           el.fetch(:null_frac),
@@ -25,6 +32,12 @@ module RubyPgExtras
           "Index name",
           "Table name",
           "Columns",
+          "Included columns",
+          "Method",
+          "Unique",
+          "Primary",
+          "Partial",
+          "Predicate",
           "Index size",
           "Index scans",
           "Null frac",

data/lib/ruby_pg_extras/missing_fk_indexes.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module RubyPgExtras
   class MissingFkIndexes
     # ignore_list: array (or comma-separated string) of entries like:
@@ -33,7 +35,7 @@ module RubyPgExtras
           # Skip columns explicitly excluded via ignore list.
           next if ignore_list_matcher.ignored?(table: table, column_name: column_name)
 
-          if index_info.none? { |row| row.fetch("columns").split(",").first == column_name }
+          if index_info.none? { |row| usable_index?(row, column_name: column_name) }
             agg.push(
               {
                 table: table,
@@ -49,6 +51,48 @@ module RubyPgExtras
 
     private
 
+    def usable_index?(row, column_name:)
+      # PostgreSQL can use a composite index for FK checks only when the FK column is leftmost.
+      return false unless first_key_column(row) == column_name
+
+      # A full index on the FK column is always usable once the leftmost-column check passes.
+      return true unless boolean_value(row.fetch("is_partial", false))
+
+      # Nullable FK checks only need non-null values, so this partial index is still usable.
+      not_null_predicate_on_column?(row.fetch("predicate", nil), column_name: column_name)
+    end
+
+    def first_key_column(row)
+      # New index metadata exposes clean key column names; fall back for legacy/stubbed rows.
+      if row.key?("key_column_names") && row.fetch("key_column_names") != nil
+        JSON.parse(row.fetch("key_column_names")).first
+      elsif row.key?("key_columns") && row.fetch("key_columns") != nil
+        row.fetch("key_columns").split(",").map(&:strip).first
+      else
+        row.fetch("columns").split(",").map(&:strip).first
+      end
+    end
+
+    def not_null_predicate_on_column?(predicate, column_name:)
+      normalized_predicate = normalized_predicate(predicate)
+
+      # Keep this intentionally narrow: only `fk_column IS NOT NULL` guarantees FK coverage.
+      normalized_predicate.match?(/\A"?#{Regexp.escape(column_name)}"?\s+IS\s+NOT\s+NULL\z/i)
+    end
+
+    def normalized_predicate(predicate)
+      predicate.to_s.strip.then do |value|
+        # pg_get_expr can wrap simple predicates in parentheses, e.g. `(topic_id IS NOT NULL)`.
+        value = value[1...-1].strip while value.start_with?("(") && value.end_with?(")")
+        value
+      end
+    end
+
+    def boolean_value(value)
+      # PG::Result returns booleans as "t"/"f"; specs may provide real Ruby booleans.
+      [true, "t", "true"].include?(value)
+    end
+
     def query_module
       RubyPgExtras
     end

data/lib/ruby_pg_extras/queries/indexes.sql

@@ -1,9 +1,79 @@
 /* List all the indexes with their corresponding tables and columns. */
 
 SELECT
-  schemaname,
-  indexname,
-  tablename,
-  rtrim(split_part(split_part(indexdef, ' WHERE', 1), '(', 2), ')') as columns
-FROM pg_indexes
-where tablename in (select relname from pg_statio_user_tables);
+  n.nspname AS schemaname,
+  i.relname AS indexname,
+  t.relname AS tablename,
+  string_agg(key_column.display_column, ', ' ORDER BY key_column.position) AS columns,
+  json_agg(key_column.display_column ORDER BY key_column.position)::text AS columns_json,
+  COALESCE(
+    string_agg(key_column.attname, ', ' ORDER BY key_column.position) FILTER (WHERE key_column.attname IS NOT NULL),
+    ''
+  ) AS key_columns,
+  json_agg(key_column.attname ORDER BY key_column.position)::text AS key_column_names,
+  COALESCE(included_columns.columns, '') AS included_columns,
+  COALESCE(included_columns.columns_json, '[]') AS included_columns_json,
+  am.amname AS index_method,
+  ix.indisunique AS is_unique,
+  ix.indisprimary AS is_primary,
+  (ix.indpred IS NOT NULL) AS is_partial,
+  pg_get_expr(ix.indpred, ix.indrelid) AS predicate
+FROM pg_index ix
+JOIN pg_class i ON i.oid = ix.indexrelid
+JOIN pg_class t ON t.oid = ix.indrelid
+JOIN pg_namespace n ON n.oid = t.relnamespace
+JOIN pg_am am ON am.oid = i.relam
+-- Expand each index into one row per key position so column/opclass/collation/options stay aligned.
+CROSS JOIN LATERAL (
+  SELECT
+    key_position.position,
+    a.attname,
+    concat_ws(
+      ' ',
+      pg_get_indexdef(i.oid, key_position.position, true),
+      CASE
+        WHEN c.oid IS NOT NULL AND c.collname <> 'default' AND (a.attcollation IS NULL OR c.oid <> a.attcollation)
+          THEN 'COLLATE ' || quote_ident(c.collname)
+      END,
+      CASE
+        WHEN oc.oid IS NOT NULL AND oc.opcdefault = false THEN oc.opcname
+      END,
+      CASE
+        WHEN (index_option.option_value & 1) = 1 THEN 'DESC'
+      END,
+      CASE
+        WHEN (index_option.option_value & 2) = 2 THEN 'NULLS FIRST'
+        WHEN (index_option.option_value & 1) = 1 THEN 'NULLS LAST'
+      END
+    ) AS display_column
+  FROM generate_series(1, ix.indnkeyatts) AS key_position(position)
+  LEFT JOIN pg_attribute a
+    ON a.attrelid = t.oid
+    AND a.attnum = (string_to_array(ix.indkey::text, ' '))[key_position.position]::int
+  LEFT JOIN pg_opclass oc
+    ON oc.oid = (string_to_array(ix.indclass::text, ' '))[key_position.position]::oid
+  LEFT JOIN pg_collation c
+    ON c.oid = (string_to_array(ix.indcollation::text, ' '))[key_position.position]::oid
+  CROSS JOIN LATERAL (
+    SELECT COALESCE((string_to_array(ix.indoption::text, ' '))[key_position.position]::int, 0) AS option_value
+  ) index_option
+) key_column
+-- INCLUDE columns are stored after key columns in pg_index and must be reported separately.
+LEFT JOIN LATERAL (
+  SELECT
+    string_agg(pg_get_indexdef(i.oid, included_position.position, true), ', ' ORDER BY included_position.position) AS columns,
+    json_agg(pg_get_indexdef(i.oid, included_position.position, true) ORDER BY included_position.position)::text AS columns_json
+  FROM generate_series(ix.indnkeyatts + 1, ix.indnatts) AS included_position(position)
+) included_columns ON true
+WHERE t.oid IN (SELECT relid FROM pg_statio_user_tables)
+GROUP BY
+  n.nspname,
+  i.relname,
+  t.relname,
+  included_columns.columns,
+  included_columns.columns_json,
+  am.amname,
+  ix.indisunique,
+  ix.indisprimary,
+  ix.indpred,
+  ix.indrelid;

data/lib/ruby_pg_extras/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyPgExtras
-  VERSION = "5.6.18"
+  VERSION = "5.7.0"
 end

data/spec/index_info_spec.rb

@@ -12,8 +12,38 @@ describe RubyPgExtras::IndexInfo do
       before do
         expect(RubyPgExtras).to receive(:indexes) {
           [
-            { "schemaname" => "public", "indexname" => "index_users_on_api_auth_token", "tablename" => "users", "columns" => "api_auth_token, column2" },
-            { "schemaname" => "public", "indexname" => "index_teams_on_slack_id", "tablename" => "teams", "columns" => "slack_id" },
+            {
+              "schemaname" => "public",
+              "indexname" => "index_users_on_api_auth_token",
+              "tablename" => "users",
+              "columns" => "api_auth_token, column2",
+              "columns_json" => '["api_auth_token","column2"]',
+              "key_columns" => "api_auth_token, column2",
+              "key_column_names" => '["api_auth_token","column2"]',
+              "included_columns" => "",
+              "included_columns_json" => "[]",
+              "index_method" => "btree",
+              "is_unique" => "f",
+              "is_primary" => "f",
+              "is_partial" => "f",
+              "predicate" => nil,
+            },
+            {
+              "schemaname" => "public",
+              "indexname" => "index_teams_on_slack_id",
+              "tablename" => "teams",
+              "columns" => "slack_id",
+              "columns_json" => '["slack_id"]',
+              "key_columns" => "slack_id",
+              "key_column_names" => '["slack_id"]',
+              "included_columns" => "external_id",
+              "included_columns_json" => '["external_id"]',
+              "index_method" => "btree",
+              "is_unique" => "t",
+              "is_primary" => "f",
+              "is_partial" => "t",
+              "predicate" => "external_id IS NOT NULL",
+            },
           ]
         }
 
@@ -43,6 +73,23 @@ describe RubyPgExtras::IndexInfo do
           RubyPgExtras::IndexInfoPrint.call(result)
         }.not_to raise_error
       end
+
+      it "returns structured index metadata" do
+        # The service keeps display columns and logical key columns as separate arrays.
+        expect(result).to include(
+          include(
+            index_name: "index_teams_on_slack_id",
+            columns: ["slack_id"],
+            key_columns: ["slack_id"],
+            included_columns: ["external_id"],
+            index_method: "btree",
+            unique: true,
+            primary: false,
+            partial: true,
+            predicate: "external_id IS NOT NULL",
+          )
+        )
+      end
     end
 
     context "real data" do
@@ -51,6 +98,68 @@ describe RubyPgExtras::IndexInfo do
           RubyPgExtras::IndexInfoPrint.call(result)
         }.not_to raise_error
       end
+
+      it "handles expression indexes without splitting on parentheses" do
+        index = result.find { |el| el.fetch(:index_name) == "index_users_on_lower_email" }
+
+        # Expression indexes can contain nested parentheses, so DDL string splitting is unsafe.
+        expect(index.fetch(:columns).first).to include("lower")
+      end
+
+      it "keeps partial index predicates separate from columns" do
+        index = result.find { |el| el.fetch(:index_name) == "index_users_on_email_partial" }
+
+        # Partial index predicates describe row coverage and should not be mixed into columns.
+        expect(index).to include(
+          columns: ["email"],
+          key_columns: ["email"],
+          partial: true,
+        )
+        expect(index.fetch(:predicate)).to include("customer_id IS NOT NULL")
+      end
+
+      it "keeps operator classes in display columns and clean key column names" do
+        index = result.find { |el| el.fetch(:index_name) == "index_users_on_email_pattern" }
+
+        # Opclasses affect index behavior, but FK checks still need the plain column name.
+        expect(index.fetch(:columns)).to eq(["email text_pattern_ops"])
+        expect(index.fetch(:key_columns)).to eq(["email"])
+      end
+
+      it "keeps sort order in display columns and clean key column names" do
+        index = result.find { |el| el.fetch(:index_name) == "index_posts_on_external_id_desc" }
+
+        # Sort/null options are display metadata, not part of the logical column name.
+        expect(index.fetch(:columns)).to eq(["external_id DESC NULLS LAST"])
+        expect(index.fetch(:key_columns)).to eq(["external_id"])
+      end
+
+      it "keeps per-position options on composite indexes" do
+        index = result.find { |el| el.fetch(:index_name) == "index_posts_on_user_id_desc_and_title_pattern" }
+
+        # Each position can have distinct options, so the query must pair metadata by position.
+        expect(index.fetch(:columns)).to eq(["user_id DESC NULLS FIRST", 'title COLLATE "C" text_pattern_ops'])
+        expect(index.fetch(:key_columns)).to eq(["user_id", "title"])
+      end
+
+      it "keeps collations in display columns and clean key column names" do
+        index = result.find { |el| el.fetch(:index_name) == "index_users_on_email_collate_c" }
+
+        # Explicit non-default collations should remain visible in index_info output.
+        expect(index.fetch(:columns).first).to include('COLLATE "C"')
+        expect(index.fetch(:key_columns)).to eq(["email"])
+      end
+
+      it "keeps included columns separate from key columns" do
+        index = result.find { |el| el.fetch(:index_name) == "index_users_on_email_include_customer_id" }
+
+        # INCLUDE columns can support index-only scans but are not search key columns.
+        expect(index).to include(
+          columns: ["email"],
+          key_columns: ["email"],
+          included_columns: ["customer_id"],
+        )
+      end
     end
   end
 end

data/spec/missing_fk_indexes_spec.rb

@@ -7,13 +7,18 @@ describe "missing_fk_indexes" do
   it "detects missing indexes for all tables" do
     result = RubyPgExtras.missing_fk_indexes(in_format: :hash)
     expect(result).to match_array([
-      { table: "users", column_name: "company_id" },
+      { table: "expression_not_null_partial_indexed_posts", column_name: "topic_id" },
+      { table: "expression_indexed_posts", column_name: "topic_id" },
+      { table: "null_partial_indexed_posts", column_name: "topic_id" },
+      { table: "partial_indexed_posts", column_name: "topic_id" },
       { table: "posts", column_name: "topic_id" },
     ])
   end
 
-  it "detects missing indexes for specific table" do
+  it "detects foreign keys that are only indexed after another column" do
     result = RubyPgExtras.missing_fk_indexes(args: { table_name: "posts" }, in_format: :hash)
+
+    # posts.topic_id exists in index_posts_on_user_id, but not as the leftmost key column.
     expect(result).to eq([
       { table: "posts", column_name: "topic_id" },
     ])
@@ -25,8 +30,11 @@ describe "missing_fk_indexes" do
       in_format: :hash
     )
 
-    expect(result).to eq([
-      { table: "users", column_name: "company_id" },
+    expect(result).to match_array([
+      { table: "expression_not_null_partial_indexed_posts", column_name: "topic_id" },
+      { table: "expression_indexed_posts", column_name: "topic_id" },
+      { table: "null_partial_indexed_posts", column_name: "topic_id" },
+      { table: "partial_indexed_posts", column_name: "topic_id" },
     ])
   end
 
@@ -36,8 +44,108 @@ describe "missing_fk_indexes" do
       in_format: :hash
     )
 
-    expect(result).to eq([
+    expect(result).to match_array([
+      { table: "expression_not_null_partial_indexed_posts", column_name: "topic_id" },
+      { table: "expression_indexed_posts", column_name: "topic_id" },
+      { table: "null_partial_indexed_posts", column_name: "topic_id" },
+      { table: "partial_indexed_posts", column_name: "topic_id" },
       { table: "posts", column_name: "topic_id" },
     ])
   end
+
+  it "does not flag foreign keys covered by sorted indexes" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "users" }, in_format: :hash)
+
+    # users.company_id is leftmost in a sorted index, so it still supports FK checks.
+    expect(result).to eq([])
+  end
+
+  it "detects foreign keys covered only by an expression index" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "expression_indexed_posts" }, in_format: :hash)
+
+    # Expression indexes do not support raw FK lookups such as WHERE topic_id = ?.
+    expect(result).to eq([
+      { table: "expression_indexed_posts", column_name: "topic_id" },
+    ])
+  end
+
+  it "detects foreign keys covered by an expression index with a not-null predicate" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "expression_not_null_partial_indexed_posts" }, in_format: :hash)
+
+    # The predicate is compatible, but the index key is topic_id::text rather than raw topic_id.
+    expect(result).to eq([
+      { table: "expression_not_null_partial_indexed_posts", column_name: "topic_id" },
+    ])
+  end
+
+  it "detects foreign keys covered only by a partial index with an unrelated predicate" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "partial_indexed_posts" }, in_format: :hash)
+
+    # WHERE id > 0 is unrelated to topic_id and does not guarantee coverage for every FK value.
+    expect(result).to eq([
+      { table: "partial_indexed_posts", column_name: "topic_id" },
+    ])
+  end
+
+  it "does not flag foreign keys covered by a not-null partial index" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "not_null_partial_indexed_posts" }, in_format: :hash)
+
+    # FK checks only need non-null values, so WHERE topic_id IS NOT NULL still covers them.
+    expect(result).to eq([])
+  end
+
+  it "normalizes nested parentheses around not-null predicates" do
+    allow(RubyPgExtras).to receive(:indexes).and_return([
+      {
+        "tablename" => "stubbed_posts",
+        "columns" => "topic_id",
+        "key_column_names" => '["topic_id"]',
+        "is_partial" => "t",
+        "predicate" => "((topic_id IS NOT NULL))",
+      },
+    ])
+    allow(RubyPgExtras).to receive(:foreign_keys).and_return([
+      { "table_name" => "stubbed_posts", "column_name" => "topic_id" },
+    ])
+
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "stubbed_posts" }, in_format: :hash)
+
+    expect(result).to eq([])
+  end
+
+  it "detects foreign keys covered only by a null partial index" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "null_partial_indexed_posts" }, in_format: :hash)
+
+    # WHERE topic_id IS NULL cannot support FK lookups for concrete topic_id values.
+    expect(result).to eq([
+      { table: "null_partial_indexed_posts", column_name: "topic_id" },
+    ])
+  end
+
+  it "does not flag foreign keys covered by indexes with included columns" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "included_indexed_posts" }, in_format: :hash)
+
+    # INCLUDE columns are ignored for key matching; topic_id is still the leftmost key column.
+    expect(result).to eq([])
+  end
+
+  it "does not flag foreign keys covered by indexes with operator classes" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "opclass_indexed_codes" }, in_format: :hash)
+
+    # The display column includes text_pattern_ops, but the logical key column remains code.
+    expect(result).to eq([])
+  end
+
+  it "does not flag foreign keys covered by indexes with collations" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "collated_indexed_codes" }, in_format: :hash)
+
+    # The display column includes COLLATE "C", but the logical key column remains code.
+    expect(result).to eq([])
+  end
+
+  it "does not flag foreign keys covered by sorted indexes on their own table" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "sorted_indexed_posts" }, in_format: :hash)
+
+    expect(result).to eq([])
+  end
 end

data/spec/spec_helper.rb

@@ -26,7 +26,17 @@ DROP TABLE IF EXISTS categories;
 DROP TABLE IF EXISTS customers;
 DROP TABLE IF EXISTS events;
 DROP TABLE IF EXISTS subjects;
+DROP TABLE IF EXISTS collated_indexed_codes;
+DROP TABLE IF EXISTS opclass_indexed_codes;
+DROP TABLE IF EXISTS included_indexed_posts;
+DROP TABLE IF EXISTS sorted_indexed_posts;
+DROP TABLE IF EXISTS null_partial_indexed_posts;
+DROP TABLE IF EXISTS not_null_partial_indexed_posts;
+DROP TABLE IF EXISTS partial_indexed_posts;
+DROP TABLE IF EXISTS expression_not_null_partial_indexed_posts;
+DROP TABLE IF EXISTS expression_indexed_posts;
 DROP TABLE IF EXISTS posts;
+DROP TABLE IF EXISTS codes;
 DROP TABLE IF EXISTS users;
 DROP TABLE IF EXISTS topics;
 DROP TABLE IF EXISTS companies;
@@ -49,6 +59,10 @@ CREATE TABLE topics (
     title VARCHAR(255)
 );
 
+CREATE TABLE codes (
+    code TEXT PRIMARY KEY
+);
+
 CREATE TABLE posts (
     id SERIAL PRIMARY KEY,
     user_id INTEGER NOT NULL,
@@ -60,6 +74,60 @@ CREATE TABLE posts (
     CONSTRAINT fk_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE CASCADE
 );
 
+CREATE TABLE expression_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_expression_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE expression_not_null_partial_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_expression_not_null_partial_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE partial_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_partial_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE sorted_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_sorted_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE not_null_partial_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_not_null_partial_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE null_partial_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_null_partial_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE included_indexed_posts (
+    id SERIAL PRIMARY KEY,
+    topic_id INTEGER,
+    CONSTRAINT fk_included_indexed_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id)
+);
+
+CREATE TABLE opclass_indexed_codes (
+    id SERIAL PRIMARY KEY,
+    code TEXT,
+    CONSTRAINT fk_opclass_indexed_codes_code FOREIGN KEY (code) REFERENCES codes(code)
+);
+
+CREATE TABLE collated_indexed_codes (
+    id SERIAL PRIMARY KEY,
+    code TEXT,
+    CONSTRAINT fk_collated_indexed_codes_code FOREIGN KEY (code) REFERENCES codes(code)
+);
+
 CREATE TABLE customers (
     id SERIAL PRIMARY KEY,
     name VARCHAR(255)
@@ -82,6 +150,25 @@ CREATE TABLE events (
 );
 
 CREATE INDEX index_posts_on_user_id ON posts(user_id, topic_id);
+CREATE INDEX index_expression_indexed_posts_on_topic_id_expression ON expression_indexed_posts((topic_id::text));
+CREATE INDEX index_expr_not_null_partial_posts_on_topic_id ON expression_not_null_partial_indexed_posts((topic_id::text)) WHERE topic_id IS NOT NULL;
+CREATE INDEX index_partial_indexed_posts_on_topic_id ON partial_indexed_posts(topic_id) WHERE id > 0;
+CREATE INDEX index_sorted_indexed_posts_on_topic_id ON sorted_indexed_posts(topic_id DESC NULLS LAST);
+CREATE INDEX index_not_null_partial_indexed_posts_on_topic_id ON not_null_partial_indexed_posts(topic_id) WHERE topic_id IS NOT NULL;
+CREATE INDEX index_null_partial_indexed_posts_on_topic_id ON null_partial_indexed_posts(topic_id) WHERE topic_id IS NULL;
+CREATE INDEX index_included_indexed_posts_on_topic_id ON included_indexed_posts(topic_id) INCLUDE (id);
+CREATE INDEX index_opclass_indexed_codes_on_code ON opclass_indexed_codes(code text_pattern_ops);
+CREATE INDEX index_collated_indexed_codes_on_code ON collated_indexed_codes(code COLLATE "C");
+
+-- Advanced index forms used to verify catalog-based index metadata parsing.
+CREATE INDEX index_users_on_company_id_desc ON users(company_id DESC NULLS LAST);
+CREATE INDEX index_users_on_lower_email ON users((lower(email)));
+CREATE INDEX index_users_on_email_partial ON users(email) WHERE customer_id IS NOT NULL;
+CREATE INDEX index_users_on_email_pattern ON users(email text_pattern_ops);
+CREATE INDEX index_posts_on_external_id_desc ON posts(external_id DESC NULLS LAST);
+CREATE INDEX index_posts_on_user_id_desc_and_title_pattern ON posts(user_id DESC, title COLLATE "C" text_pattern_ops);
+CREATE INDEX index_users_on_email_collate_c ON users(email COLLATE "C");
+CREATE INDEX index_users_on_email_include_customer_id ON users(email) INCLUDE (customer_id);
 SQL
 
     RubyPgExtras.connection.exec(DB_SCHEMA)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pg-extras
 version: !ruby/object:Gem::Version
-  version: 5.6.18
+  version: 5.7.0
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg