ruby-pg-extras 5.6.18 → 5.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0de82c2381f728d09ea04bad7af74d9fce31ab7f73c5ffa6fa1b52741d0e25bf
-  data.tar.gz: a24730c633b7a9747b074d574d701aa5fa4f2cc1f764c7ce684c5934d3ab29d4
+  metadata.gz: 7c63e61eb15277c5b3c2d600c39e64c205188b8f8b8c9db2e3fb85fbdc09ce85
+  data.tar.gz: dc3478e08ef5da953a82486bf2a360788a60ba0d647ad7017ac3d147583b37b2
 SHA512:
-  metadata.gz: 275eee2d2e060752bbde7bc2be03d3cbb1a9af878b1fcc909016613eaa5ad7ccd00a24b59e0238f7e981f692bf984971a1813004109ad31cbd98a6329da93962
-  data.tar.gz: 70b3e1d3b5123bf7e472c1122b1471742aae4693193854f4825ed10c3fae519b4c2313d889fcaded7e50c7b9db7d387f72af26d46404027cccde62f2a41bde15
+  metadata.gz: 3677747e0122ec0ef9b22a1cebcb5e30ac4165d8fcc44b7a000eb6490442f5f666c1ced6c393389d66dc83dfb00c2c6dda305618f11cfdbf04c4d23f1d7ece4c
+  data.tar.gz: ecfebfcdf855846eabe00a3b04cede4ac267465a7735511776b4621000ecfe0ccebd1eccec7f08150d47a459650b2806ff275bd7ee7e4204de12f7ea69c635eb

data/README.md

@@ -114,12 +114,44 @@ RubyPgExtras.diagnose
 
 Keep reading to learn about methods that `diagnose` uses under the hood.
 
+### `new_page_updates`
+
+This is a `diagnose` check, not a standalone query method. On PostgreSQL 16 and newer, it uses the [`update_stats`](#update_stats) breakdown to flag tables where a significant share of updates placed the new row version on another heap page instead of staying on the original page. Those tables are worth reviewing for page-space pressure, row growth, and whether a lower table `fillfactor` would help.
+
+By default, a table is reported when it has at least 10,000 cumulative updates and 20% or more of its updates are new-page updates. The report includes each table's new-page ratio, current `fillfactor`, and the percentage of same-page updates that were HOT. A low HOT-among-same-page value suggests indexed-column changes are also preventing HOT, so lowering `fillfactor` alone may not be enough.
+
+You can override the default thresholds with environment variables:
+
+```ruby
+ENV["PG_EXTRAS_NEW_PAGE_UPDATES_MIN_SAMPLE"] = "5000"
+ENV["PG_EXTRAS_NEW_PAGE_UPDATES_MAX_PERCENT"] = "15"
+```
+
+The underlying counters are cumulative, so compare their values over time rather than treating a single snapshot as definitive.
+
+### `low_hot_same_page`
+
+This is a `diagnose` check, not a standalone query method. On PostgreSQL 16 and newer, it uses the [`update_stats`](#update_stats) breakdown to flag tables where updates that stayed on the original heap page were almost never HOT. That usually means those updates modified indexed columns, so lowering `fillfactor` alone will not help.
+
+By default, a table is reported when it has at least 10,000 cumulative updates and fewer than 10% of its same-page updates were HOT. The report includes each table's HOT-among-same-page ratio, same-page and new-page ratios, and current `fillfactor`. Review which columns your application updates and which indexes cover them; removing or adjusting indexes on frequently updated columns (or avoiding updating those columns) can restore HOT updates.
+
+You can override the default thresholds with environment variables:
+
+```ruby
+ENV["PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_SAMPLE"] = "5000"
+ENV["PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_PERCENT"] = "5"
+```
+
+The underlying counters are cumulative, so compare their values over time rather than treating a single snapshot as definitive.
+
 ## Available methods
 
 ### `missing_fk_indexes`
 
 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 +257,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%   |
 
 ```
 
@@ -722,6 +755,21 @@ RubyPgExtras.vacuum_io_stats
 
 This command surfaces cumulative I/O statistics for autovacuum-related VACUUM activity, based on the `pg_stat_io` view introduced in PostgreSQL 16 ([pg_stat_io documentation](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-IO-VIEW)). It shows how many blocks autovacuum workers have read and written, how many buffer evictions and ring-buffer reuses occurred, and when the statistics were last reset; this is useful for determining whether autovacuum is responsible for I/O spikes, as described in the pganalyze article on `pg_stat_io` ([Tracking cumulative I/O activity by autovacuum and manual VACUUMs](https://pganalyze.com/blog/pg-stat-io#tracking-cumulative-io-activity-by-autovacuum-and-manual-vacuums)). On PostgreSQL versions below 16 this method returns a single informational row indicating that the feature is unavailable.
 
+### `update_stats`
+
+```ruby
+
+RubyPgExtras.update_stats
+
+ table  | fillfactor | estimated_heap_bytes_per_live_row | total_updates | hot_updates | hot_pct | same_page_non_hot_updates | same_page_non_hot_pct | new_page_updates | new_page_pct | same_page_pct | hot_given_same_page_pct
+--------+------------+-----------------------------------+---------------+-------------+---------+---------------------------+-----------------------+------------------+--------------+---------------+-------------------------
+ users  |        100 |                               256 |       1250000 |      980000 |   78.40 |                     45000 |                  3.60 |           225000 |        18.00 |         82.00 |                   95.61
+ orders |         80 |                               128 |        450000 |      410000 |   91.11 |                     12000 |                  2.67 |            28000 |         6.22 |         93.78 |                   97.16
+ (truncated results for brevity)
+```
+
+This command breaks down table updates into HOT, same-page non-HOT, and new-page updates using `pg_stat_user_tables` columns including `n_tup_newpage_upd` ([pg_stat_all_tables documentation](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ALL-TABLES-VIEW)). HOT updates require that changed columns are not indexed and that the new row version fits on the same page ([HOT updates in PostgreSQL for better performance](https://www.cybertec-postgresql.com/en/hot-updates-in-postgresql-for-better-performance/), [Heap-Only Tuples](https://www.postgresql.org/docs/current/storage-hot.html)). High `same_page_non_hot_pct` usually points to updates of indexed columns, while high `new_page_pct` often means pages are too full and lowering `fillfactor` (then rewriting the table with `VACUUM FULL` or `CLUSTER`) may help. `estimated_heap_bytes_per_live_row` divides main-fork heap size by `pg_class.reltuples` when that estimate is positive; it reflects physical storage per estimated live row (including page overhead, fillfactor free space, and bloat) rather than logical tuple width, and is NULL until the table has been analyzed or vacuumed. Larger values often call for a lower `fillfactor`. These counters are cumulative and can be reset with PostgreSQL statistics-reset functions. On PostgreSQL versions below 16, where `n_tup_newpage_upd` is unavailable, the method returns a reduced breakdown of total, HOT, and non-HOT updates.
+
 ### `kill_all`
 
 ```ruby

data/lib/ruby-pg-extras.rb

@@ -28,7 +28,7 @@ module RubyPgExtras
     records_rank seq_scans table_index_scans table_indexes_size
     table_size total_index_size total_table_size
     unused_indexes duplicate_indexes vacuum_stats vacuum_progress vacuum_io_stats
-    analyze_progress
+    analyze_progress update_stats
     kill_all kill_pid
     pg_stat_statements_reset buffercache_stats
     buffercache_usage ssl_used connections
@@ -58,6 +58,8 @@ module RubyPgExtras
     vacuum_io_stats: {},
     vacuum_io_stats_legacy: {},
     analyze_progress: {},
+    update_stats: { schema: DEFAULT_SCHEMA },
+    update_stats_legacy: { schema: DEFAULT_SCHEMA },
     buffercache_stats: { limit: 10 },
     buffercache_usage: { limit: 20 },
     unused_indexes: { max_scans: 50, schema: DEFAULT_SCHEMA },
@@ -119,6 +121,15 @@ module RubyPgExtras
       end
     end
 
+    # The detailed update breakdown relies on n_tup_newpage_upd, available from PostgreSQL 16.
+    # Older versions fall back to the HOT/non-HOT breakdown in update_stats_legacy.
+    if query_name == :update_stats
+      server_version_num = conn.send(exec_method, "SHOW server_version_num").to_a[0].values[0].to_i
+      if server_version_num < 160000
+        query_name = :update_stats_legacy
+      end
+    end
+
     REQUIRED_ARGS.fetch(query_name) { [] }.each do |arg_name|
       if args[arg_name].nil?
         raise ArgumentError, "'#{arg_name}' is required"

data/lib/ruby_pg_extras/diagnose_data.rb

@@ -10,6 +10,10 @@ module RubyPgExtras
     PG_EXTRAS_NULL_MIN_NULL_FRAC_PERCENT = 50 # 50%
     PG_EXTRAS_BLOAT_MIN_VALUE = 10
     PG_EXTRAS_OUTLIERS_MIN_EXEC_RATIO = 33 # 33%
+    PG_EXTRAS_NEW_PAGE_UPDATES_MAX_PERCENT = 20 # 20%
+    PG_EXTRAS_NEW_PAGE_UPDATES_MIN_SAMPLE = 10_000
+    PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_PERCENT = 10 # 10%
+    PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_SAMPLE = 10_000
 
     def self.call
       new.call
@@ -26,6 +30,8 @@ module RubyPgExtras
         :unused_indexes,
         :null_indexes,
         :bloat,
+        :new_page_updates,
+        :low_hot_same_page,
         :duplicate_indexes,
       ].yield_self do |checks|
         extensions_data = query_module.extensions(in_format: :hash)
@@ -292,6 +298,120 @@ module RubyPgExtras
       end
     end
 
+    def new_page_updates
+      max_percent = ENV.fetch(
+        "PG_EXTRAS_NEW_PAGE_UPDATES_MAX_PERCENT",
+        PG_EXTRAS_NEW_PAGE_UPDATES_MAX_PERCENT,
+      ).to_f
+      min_sample = ENV.fetch(
+        "PG_EXTRAS_NEW_PAGE_UPDATES_MIN_SAMPLE",
+        PG_EXTRAS_NEW_PAGE_UPDATES_MIN_SAMPLE,
+      ).to_i
+
+      tables = query_module.update_stats(in_format: :hash)
+
+      if tables.any? && !tables.first.key?("new_page_pct")
+        return {
+          ok: true,
+          message: "New-page update analysis requires PostgreSQL 16 or newer.",
+        }
+      end
+
+      tables = tables.select do |table|
+        table.fetch("total_updates").to_i >= min_sample &&
+          table.fetch("new_page_pct").to_f >= max_percent
+      end
+
+      if tables.empty?
+        {
+          ok: true,
+          message: "No tables with a high new-page update ratio detected.",
+        }
+      else
+        table_details = tables.map do |table|
+          <<~DETAIL.strip
+            '#{table.fetch("table")}':
+              new-page updates: #{table.fetch("new_page_pct")}% (#{table.fetch("new_page_updates")} of #{table.fetch("total_updates")})
+              HOT among same-page updates: #{table.fetch("hot_given_same_page_pct")}%
+              fillfactor: #{table.fetch("fillfactor")}
+          DETAIL
+        end.join("\n\n")
+
+        {
+          ok: false,
+          message: <<~MESSAGE.strip,
+            High new-page update ratios detected:
+
+            #{table_details}
+
+            A high new-page ratio means many successor tuple versions were placed on another heap page and therefore could not be HOT. This commonly indicates insufficient reusable space on the original page. `n_tup_newpage_upd` records that placement directly; it does not identify the underlying reason or whether the update would otherwise have been HOT-eligible. Investigate page-space pressure, row growth, long-lived transactions, large update batches, and whether a lower table fillfactor is appropriate.
+
+            The HOT-among-same-page percentage provides additional context: a low value suggests indexed-column changes are preventing HOT on updates that did stay on the same page, so changing fillfactor alone may not resolve the issue.
+
+            These counters are cumulative; compare their deltas before and after a change.
+          MESSAGE
+        }
+      end
+    end
+
+    def low_hot_same_page
+      min_percent = ENV.fetch(
+        "PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_PERCENT",
+        PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_PERCENT,
+      ).to_f
+      min_sample = ENV.fetch(
+        "PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_SAMPLE",
+        PG_EXTRAS_LOW_HOT_SAME_PAGE_MIN_SAMPLE,
+      ).to_i
+
+      tables = query_module.update_stats(in_format: :hash)
+
+      if tables.any? && !tables.first.key?("hot_given_same_page_pct")
+        return {
+          ok: true,
+          message: "HOT-among-same-page update analysis requires PostgreSQL 16 or newer.",
+        }
+      end
+
+      tables = tables.select do |table|
+        hot_given_same_page_pct = table["hot_given_same_page_pct"]
+        next false if hot_given_same_page_pct.nil?
+
+        table.fetch("total_updates").to_i >= min_sample &&
+          hot_given_same_page_pct.to_f < min_percent
+      end
+
+      if tables.empty?
+        {
+          ok: true,
+          message: "No tables with a low HOT-among-same-page update ratio detected.",
+        }
+      else
+        table_details = tables.map do |table|
+          <<~DETAIL.strip
+            '#{table.fetch("table")}':
+              HOT among same-page updates: #{table.fetch("hot_given_same_page_pct")}%
+              same-page updates: #{table.fetch("same_page_pct")}%
+              new-page updates: #{table.fetch("new_page_pct")}%
+              fillfactor: #{table.fetch("fillfactor")}
+          DETAIL
+        end.join("\n\n")
+
+        {
+          ok: false,
+          message: <<~MESSAGE.strip,
+            Low HOT-among-same-page update ratios detected:
+
+            #{table_details}
+
+            A low HOT-among-same-page ratio means updates that stayed on the original heap page still could not be HOT. That usually means those updates modified indexed columns. Review which columns your application updates and which indexes cover them; removing or adjusting indexes on frequently updated columns (or avoiding updating those columns) can restore HOT updates and reduce index and vacuum overhead.
+
+            These counters are cumulative; compare their deltas before and after a change.
+          MESSAGE
+        }
+      end
+    end
+
     def outliers
       queries = query_module.outliers(in_format: :hash).select do |q|
         q.fetch("prop_exec_time").gsub("%", "").to_f >= PG_EXTRAS_OUTLIERS_MIN_EXEC_RATIO

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/queries/update_stats.sql

@@ -0,0 +1,71 @@
+/* HOT, same-page non-HOT, and new-page update statistics (PostgreSQL 16+) */
+
+WITH table_stats AS (
+  SELECT
+    s.relid,
+    s.schemaname,
+    s.relname,
+    s.n_tup_upd,
+    s.n_tup_hot_upd,
+    s.n_tup_newpage_upd,
+    c.reltuples,
+    COALESCE(
+      (
+        SELECT option_value::integer
+        FROM pg_options_to_table(c.reloptions)
+        WHERE option_name = 'fillfactor'
+      ),
+      100
+    ) AS fillfactor
+  FROM pg_stat_user_tables s
+  INNER JOIN pg_class c ON c.oid = s.relid
+  WHERE s.schemaname = '%{schema}'
+)
+SELECT
+  relname AS table,
+  fillfactor,
+  CASE
+    WHEN reltuples > 0 THEN
+      ROUND(
+        pg_relation_size(relid)::numeric / reltuples
+      )::bigint
+  END AS estimated_heap_bytes_per_live_row,
+  n_tup_upd AS total_updates,
+  n_tup_hot_upd AS hot_updates,
+  ROUND(
+    100.0 * n_tup_hot_upd
+    / NULLIF(n_tup_upd, 0),
+    2
+  ) AS hot_pct,
+  n_tup_upd
+    - n_tup_hot_upd
+    - n_tup_newpage_upd
+    AS same_page_non_hot_updates,
+  ROUND(
+    100.0 * (
+      n_tup_upd
+      - n_tup_hot_upd
+      - n_tup_newpage_upd
+    )
+    / NULLIF(n_tup_upd, 0),
+    2
+  ) AS same_page_non_hot_pct,
+  n_tup_newpage_upd AS new_page_updates,
+  ROUND(
+    100.0 * n_tup_newpage_upd
+    / NULLIF(n_tup_upd, 0),
+    2
+  ) AS new_page_pct,
+  ROUND(
+    100.0 * (n_tup_upd - n_tup_newpage_upd)
+    / NULLIF(n_tup_upd, 0),
+    2
+  ) AS same_page_pct,
+  ROUND(
+    100.0 * n_tup_hot_upd
+    / NULLIF(n_tup_upd - n_tup_newpage_upd, 0),
+    2
+  ) AS hot_given_same_page_pct
+FROM table_stats
+WHERE n_tup_upd > 0
+ORDER BY n_tup_upd DESC;

data/lib/ruby_pg_extras/queries/update_stats_legacy.sql

@@ -0,0 +1,46 @@
+/* HOT and non-HOT update statistics (PostgreSQL 15 and older) */
+
+WITH table_stats AS (
+  SELECT
+    s.relid,
+    s.relname,
+    s.n_tup_upd,
+    s.n_tup_hot_upd,
+    c.reltuples,
+    COALESCE(
+      (
+        SELECT option_value::integer
+        FROM pg_options_to_table(c.reloptions)
+        WHERE option_name = 'fillfactor'
+      ),
+      100
+    ) AS fillfactor
+  FROM pg_stat_user_tables s
+  INNER JOIN pg_class c ON c.oid = s.relid
+  WHERE s.schemaname = '%{schema}'
+)
+SELECT
+  relname AS table,
+  fillfactor,
+  CASE
+    WHEN reltuples > 0 THEN
+      ROUND(
+        pg_relation_size(relid)::numeric / reltuples
+      )::bigint
+  END AS estimated_heap_bytes_per_live_row,
+  n_tup_upd AS total_updates,
+  n_tup_hot_upd AS hot_updates,
+  ROUND(
+    100.0 * n_tup_hot_upd
+    / NULLIF(n_tup_upd, 0),
+    2
+  ) AS hot_pct,
+  n_tup_upd - n_tup_hot_upd AS non_hot_updates,
+  ROUND(
+    100.0 * (n_tup_upd - n_tup_hot_upd)
+    / NULLIF(n_tup_upd, 0),
+    2
+  ) AS non_hot_pct
+FROM table_stats
+WHERE n_tup_upd > 0
+ORDER BY n_tup_upd DESC;

data/lib/ruby_pg_extras/version.rb

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