ruby-pg-extras 5.6.14 → 5.6.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76983587160dcdfb1e9cc45f5e42b1329d08f74977f5c7691c7fafeeefc61fe4
-  data.tar.gz: 4ed633c71a3b2f4c12be8911b73ea59b750f2e7c569c6ae9913d62cab68b45e3
+  metadata.gz: e20ed34b0677aa7e50c14ca2d5a511d4854f0eb34a1ad7e04a4f94fe2349895b
+  data.tar.gz: ef35f2a431195ba26a0271808315b54985254df379412ffb4eef9dc4ff81f7e8
 SHA512:
-  metadata.gz: 34423951a2e88e0c2e333e3cf2acc81aa8fd3b85eb76a410d2b6a5f195c22f584b475a9ee23585f012579c203496eee037d79889325f65b3b7d224a607fe98ac
-  data.tar.gz: cb3ff5a3d3ef075bd1cfe5c4604bf7dfcd821b9c11985868fa98d910213e1e767b765fe92c6acc6b1bb910d35cc12435402e97364cc26b1dacc2cd5d0212b55f
+  metadata.gz: 6145da151dc40da7d0f79a3a2c9ff3d059dd9b320e44b751f6d5a9d0b00d395a78aff3c8bd1bf51453aa65ccb7cf12953ec73e54b4a350d7ee34ec61b5f661a0
+  data.tar.gz: 72861cc4517a977e39266f2617094db82be77ba31f932831785540c3bc3ae078e1deccbc32b5b025343bbbe2e2c2d25529e24dad170ea9e8969795dfe3ee64de

data/.github/workflows/ci.yml

@@ -15,13 +15,6 @@ jobs:
         ruby-version: ['3.4', '3.3', '3.2', '3.1', '3.0', '2.7']
     steps:
       - uses: actions/checkout@v4
-      - name: Run PostgreSQL 12
-        run: |
-          docker run --env POSTGRES_USER=postgres \
-            --env POSTGRES_DB=ruby-pg-extras-test \
-            --env POSTGRES_PASSWORD=secret \
-            -d -p 5432:5432 postgres:12.20-alpine \
-            postgres -c shared_preload_libraries=pg_stat_statements
       - name: Run PostgreSQL 13
         run: |
           docker run --env POSTGRES_USER=postgres \
@@ -71,11 +64,6 @@ jobs:
           bundle config set --local path 'vendor/bundle'
           bundle install
           sleep 5
-      - name: Run tests for PG 12
-        env:
-          PG_VERSION: 12
-        run: |
-          bundle exec rspec spec/
       - name: Run tests for PG 13
         env:
           PG_VERSION: 13

data/README.md

@@ -647,17 +647,60 @@ This command displays an estimation of table "bloat" – space allocated to a re
 
 RubyPgExtras.vacuum_stats
 
- schema |         table         | last_vacuum | last_autovacuum  |    rowcount    | dead_rowcount  | autovacuum_threshold | expect_autovacuum
---------+-----------------------+-------------+------------------+----------------+----------------+----------------------+-------------------
- public | log_table             |             | 2013-04-26 17:37 |         18,030 |              0 |          3,656       |
- public | data_table            |             | 2013-04-26 13:09 |             79 |             28 |             66       |
- public | other_table           |             | 2013-04-26 11:41 |             41 |             47 |             58       |
- public | queue_table           |             | 2013-04-26 17:39 |             12 |          8,228 |             52       | yes
- public | picnic_table          |             |                  |             13 |              0 |             53       |
+ schema |         table         | last_manual_vacuum | manual_vacuum_count | last_autovacuum  | autovacuum_count |    rowcount    | dead_rowcount  | dead_tup_autovacuum_threshold | n_ins_since_vacuum | insert_autovacuum_threshold | expect_autovacuum
+--------+-----------------------+--------------------+---------------------+------------------+------------------+----------------+----------------+-------------------------------+--------------------+-----------------------------+-------------------
+ public | log_table             |                    |                   0 | 2013-04-26 17:37 |                5 |         18,030 |              0 |                       3,656   |                  0 |                         3,606 | 
+ public | data_table            |                    |                   0 | 2013-04-26 13:09 |                3 |             79 |             28 |                          66   |                 10 |                            16 | yes (dead_tuples)
+ public | other_table           |                    |                   0 | 2013-04-26 11:41 |                4 |             41 |             47 |                          58   |              2,000 |                           1,008 | yes (dead_tuples & inserts)
  (truncated results for brevity)
 ```
 
-This command displays statistics related to vacuum operations for each table, including an estimation of dead rows, last autovacuum and the current autovacuum threshold. This command can be useful when determining if current vacuum thresholds require adjustments, and to determine when the table was last vacuumed.
+This command displays statistics related to vacuum operations for each table, including last manual vacuum and autovacuum timestamps and counters, an estimation of dead rows, dead-tuple-based autovacuum threshold, number of rows inserted since the last VACUUM (`n_ins_since_vacuum`) and the insert-based autovacuum threshold introduced in PostgreSQL 13 ([PostgreSQL autovacuum configuration](https://www.postgresql.org/docs/current/runtime-config-vacuum.html#RUNTIME-CONFIG-AUTOVACUUM)). It helps determine if current autovacuum thresholds (both dead-tuple and insert-based) are appropriate, and whether an automatic vacuum is expected to be triggered soon.
+
+### `vacuum_progress`
+
+```ruby
+
+RubyPgExtras.vacuum_progress
+
+ database | schema |  table   |  pid  |        phase        | heap_blks_total | heap_blks_scanned | heap_blks_vacuumed | index_vacuum_count
+----------+--------+----------+-------+---------------------+-----------------+-------------------+--------------------+--------------------
+ app_db   | public | users    | 12345 | scanning heap       |          125000 |             32000 |                  0 |                  0
+ app_db   | public | orders   | 12346 | vacuuming indexes   |           80000 |             80000 |              75000 |                  3
+ (truncated results for brevity)
+```
+
+This command shows the current progress of `VACUUM` / autovacuum operations by reading `pg_stat_progress_vacuum` ([VACUUM progress reporting docs](https://www.postgresql.org/docs/current/progress-reporting.html#VACUUM-PROGRESS-REPORTING)). It can be used to see which tables are being vacuumed right now, how far each operation has progressed, and how many index vacuum cycles have been performed.
+
+### `analyze_progress`
+
+```ruby
+
+RubyPgExtras.analyze_progress
+
+ database | schema |  table   |  pid  |        phase         | sample_blks_total | sample_blks_scanned | ext_stats_total | ext_stats_computed
+----------+--------+----------+-------+----------------------+-------------------+---------------------+-----------------+--------------------
+ app_db   | public | users    | 22345 | acquiring sample rows|              5000 |                 1200 |               2 |                   0
+ app_db   | public | orders   | 22346 | computing statistics |              8000 |                 8000 |               1 |                   1
+ (truncated results for brevity)
+```
+
+This command displays the current progress of `ANALYZE` and auto-analyze operations using `pg_stat_progress_analyze` ([ANALYZE progress reporting docs](https://www.postgresql.org/docs/current/progress-reporting.html#ANALYZE-PROGRESS-REPORTING)). It helps understand how far statistics collection has progressed for each active analyze and whether extended statistics are being computed.
+
+### `vacuum_io_stats`
+
+```ruby
+
+RubyPgExtras.vacuum_io_stats
+
+    backend_type    | object   | context  |  reads  | writes  | writebacks | extends | evictions | reuses  | fsyncs |  stats_reset
+--------------------+----------+----------+---------+---------+-----------+---------+-----------+---------+--------+-------------------------------
+ autovacuum worker  | relation | vacuum   | 5824251 | 3028684 |         0 |       0 |      2588 | 5821460 |      0 | 2025-01-10 11:50:27.583875+00
+ autovacuum launcher| relation | autovacuum|   16306 |    2494 |         0 |    2915 |     17785 |       0 |      0 | 2025-01-10 11:50:27.583875+00
+ (truncated results for brevity)
+```
+
+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.
 
 ### `kill_all`
 

data/Rakefile

@@ -5,5 +5,5 @@ RSpec::Core::RakeTask.new(:spec)
 
 desc "Test all PG versions"
 task :test_all do
-  system("PG_VERSION=12 bundle exec rspec spec/ && PG_VERSION=13 bundle exec rspec spec/ && PG_VERSION=14 bundle exec rspec spec/ && PG_VERSION=15 bundle exec rspec spec/ && PG_VERSION=16 bundle exec rspec spec/ && PG_VERSION=17 bundle exec rspec spec/")
+  system("PG_VERSION=13 bundle exec rspec spec/ && PG_VERSION=14 bundle exec rspec spec/ && PG_VERSION=15 bundle exec rspec spec/ && PG_VERSION=16 bundle exec rspec spec/ && PG_VERSION=17 bundle exec rspec spec/")
 end

data/docker-compose.yml.sample

@@ -1,13 +1,4 @@
 services:
-  postgres12:
-    image: postgres:12.20-alpine
-    command: postgres -c shared_preload_libraries=pg_stat_statements
-    environment:
-      POSTGRES_USER: postgres
-      POSTGRES_DB: ruby-pg-extras-test
-      POSTGRES_PASSWORD: secret
-    ports:
-      - '5432:5432'
   postgres13:
     image: postgres:13.16-alpine
     command: postgres -c shared_preload_libraries=pg_stat_statements

data/lib/ruby-pg-extras.rb

@@ -7,6 +7,7 @@ require "ruby_pg_extras/size_parser"
 require "ruby_pg_extras/diagnose_data"
 require "ruby_pg_extras/diagnose_print"
 require "ruby_pg_extras/detect_fk_column"
+require "ruby_pg_extras/ignore_list"
 require "ruby_pg_extras/missing_fk_indexes"
 require "ruby_pg_extras/missing_fk_constraints"
 require "ruby_pg_extras/index_info"
@@ -26,7 +27,9 @@ module RubyPgExtras
     long_running_queries mandelbrot outliers
     records_rank seq_scans table_index_scans table_indexes_size
     table_size total_index_size total_table_size
-    unused_indexes duplicate_indexes vacuum_stats kill_all kill_pid
+    unused_indexes duplicate_indexes vacuum_stats vacuum_progress vacuum_io_stats
+    analyze_progress
+    kill_all kill_pid
     pg_stat_statements_reset buffercache_stats
     buffercache_usage ssl_used connections
     table_schema table_schemas
@@ -50,6 +53,11 @@ module RubyPgExtras
     outliers: { limit: 10 },
     outliers_legacy: { limit: 10 },
     outliers_17: { limit: 10 },
+    vacuum_progress: {},
+    vacuum_progress_17: {},
+    vacuum_io_stats: {},
+    vacuum_io_stats_legacy: {},
+    analyze_progress: {},
     buffercache_stats: { limit: 10 },
     buffercache_usage: { limit: 20 },
     unused_indexes: { max_scans: 50, schema: DEFAULT_SCHEMA },
@@ -92,6 +100,25 @@ module RubyPgExtras
       end
     end
 
+    # vacuum_progress uses pg_stat_progress_vacuum only and does not depend on pg_stat_statements,
+    # so we switch it based on the server_version_num instead of the pg_stat_statements version.
+    if query_name == :vacuum_progress
+      server_version_num = conn.send(exec_method, "SHOW server_version_num").to_a[0].values[0].to_i
+      if server_version_num >= 170000
+        query_name = :vacuum_progress_17
+      end
+    end
+
+    # vacuum_io_stats relies on pg_stat_io which is available starting from PostgreSQL 16.
+    # For older versions we fall back to vacuum_io_stats_legacy which just indicates
+    # that this feature is not available on the current server.
+    if query_name == :vacuum_io_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 = :vacuum_io_stats_legacy
+      end
+    end
+
     REQUIRED_ARGS.fetch(query_name) { [] }.each do |arg_name|
       if args[arg_name].nil?
         raise ArgumentError, "'#{arg_name}' is required"
@@ -169,7 +196,7 @@ module RubyPgExtras
   end
 
   def self.missing_fk_constraints(args: {}, in_format: :display_table)
-    RubyPgExtras::MissingFkConstraints.call(args[:table_name])
+    RubyPgExtras::MissingFkConstraints.call(args[:table_name], ignore_list: args[:ignore_list])
   end
 
   def self.display_result(result, title:, in_format:)

data/lib/ruby_pg_extras/detect_fk_column.rb

@@ -34,16 +34,25 @@ module RubyPgExtras
     end
 
     def call(column_name, tables)
-      return false unless column_name =~ /_id$/
-      table_name = column_name.split("_").first
-      table_name = pluralize(table_name)
-      tables.include?(table_name)
+      # Heuristic: Rails-style foreign keys are usually named `<table_singular>_id`.
+      # We accept underscores in the prefix (e.g. `account_user_id` -> `account_users`).
+      match = /\A(?<table_singular>.+)_id\z/i.match(column_name.to_s)
+      return false unless match
+
+      table_singular = match[:table_singular]
+      return false if table_singular.empty?
+
+      tables.include?(pluralize(table_singular))
     end
 
     def pluralize(word)
-      return word if UNCOUNTABLE.include?(word.downcase)
-      return IRREGULAR[word] if IRREGULAR.key?(word)
-      return IRREGULAR.invert[word] if IRREGULAR.value?(word)
+      # Table names from Postgres are typically lowercase. Normalize before applying rules.
+      word = word.to_s.downcase
+
+      return word if UNCOUNTABLE.include?(word)
+      return IRREGULAR.fetch(word) if IRREGULAR.key?(word)
+      # If the word is already an irregular plural (e.g. "people"), keep it as-is.
+      return word if IRREGULAR.value?(word)
 
       PLURAL_RULES.reverse.each do |(rule, replacement)|
         return word.gsub(rule, replacement) if word.match?(rule)

data/lib/ruby_pg_extras/ignore_list.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubyPgExtras
+  # Parses and matches ignore patterns like:
+  # - "*"              (ignore everything)
+  # - "posts.*"        (ignore all columns on a table)
+  # - "category_id"    (ignore this column name on all tables)
+  # - "posts.topic_id" (ignore a specific table+column)
+  class IgnoreList
+    def initialize(ignore_list)
+      @rules = normalize(ignore_list)
+    end
+
+    def ignored?(table:, column_name:)
+      @rules.any? do |rule|
+        next true if rule == "*"
+        next true if rule == "#{table}.*"
+        next true if rule == column_name
+        next true if rule == "#{table}.#{column_name}"
+        false
+      end
+    end
+
+    private
+
+    def normalize(ignore_list)
+      entries =
+        case ignore_list
+        when nil
+          []
+        when String
+          ignore_list.split(",")
+        when Array
+          ignore_list
+        else
+          raise ArgumentError, "ignore_list must be a String or Array"
+        end
+
+      entries
+        .map { |v| v.to_s.strip }
+        .reject(&:empty?)
+        .uniq
+    end
+  end
+end
+
+

data/lib/ruby_pg_extras/missing_fk_constraints.rb

@@ -2,42 +2,68 @@
 
 module RubyPgExtras
   class MissingFkConstraints
-    def self.call(table_name)
-      new.call(table_name)
+    # ignore_list: array (or comma-separated string) of 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)
+    def self.call(table_name, ignore_list: nil)
+      new.call(table_name, ignore_list: ignore_list)
     end
 
-    def call(table_name)
-      tables = if table_name
+    def call(table_name, ignore_list: nil)
+      ignore_list_matcher = IgnoreList.new(ignore_list)
+
+      tables =
+        if table_name
           [table_name]
         else
           all_tables
         end
 
-      schemas = query_module.table_schemas(in_format: :hash)
-      foreign_keys = query_module.foreign_keys(in_format: :hash)
+      schemas_by_table = query_module
+        .table_schemas(in_format: :hash)
+        .group_by { |row| row.fetch("table_name") }
 
-      tables.reduce([]) do |agg, table|
-        schema = schemas.select { |row| row.fetch("table_name") == table }
-        fk_columns = foreign_keys.select { |row| row.fetch("table_name") == table }
+      fk_columns_by_table = query_module
+        .foreign_keys(in_format: :hash)
+        .group_by { |row| row.fetch("table_name") }
+        .transform_values { |rows| rows.map { |row| row.fetch("column_name") } }
 
-        fk_columns = schema.filter_map do |row|
-          if DetectFkColumn.call(row.fetch("column_name"), all_tables)
-            row.fetch("column_name")
-          end
-        end
+      tables.each_with_object([]) do |table, agg|
+        schema = schemas_by_table.fetch(table, [])
+        fk_columns_for_table = fk_columns_by_table.fetch(table, [])
+        schema_column_names = schema.map { |row| row.fetch("column_name") }
+
+        candidate_fk_columns = schema.filter_map do |row|
+          column_name = row.fetch("column_name")
+
+          # Skip columns explicitly excluded via ignore list.
+          next if ignore_list_matcher.ignored?(table: table, column_name: column_name)
 
-        fk_columns.each do |column_name|
-          if foreign_keys.none? { |row| row.fetch("column_name") == column_name }
-            agg.push(
-              {
-                table: table,
-                column_name: column_name,
-              }
-            )
-          end
+          # Skip columns that already have a foreign key constraint on this table.
+          next if fk_columns_for_table.include?(column_name)
+
+          # Skip columns that don't look like an FK candidate based on naming conventions.
+          next unless DetectFkColumn.call(column_name, all_tables)
+
+          # Rails polymorphic associations use <name>_id + <name>_type and can't have FK constraints.
+          candidate_prefix = column_name.delete_suffix("_id")
+          polymorphic_type_column = "#{candidate_prefix}_type"
+          # Skip polymorphic associations (cannot be expressed as a real FK constraint).
+          next if schema_column_names.include?(polymorphic_type_column)
+
+          column_name
         end
 
-        agg
+        candidate_fk_columns.each do |column_name|
+          agg.push(
+            {
+              table: table,
+              column_name: column_name,
+            }
+          )
+        end
       end
     end
 

data/lib/ruby_pg_extras/missing_fk_indexes.rb

@@ -7,26 +7,22 @@ module RubyPgExtras
     end
 
     def call(table_name)
+      indexes_info = query_module.indexes(in_format: :hash)
+      foreign_keys = query_module.foreign_keys(in_format: :hash)
+
       tables = if table_name
           [table_name]
         else
-          all_tables
+          foreign_keys.map { |row| row.fetch("table_name") }.uniq
         end
 
-      indexes_info = query_module.indexes(in_format: :hash)
-      schemas = query_module.table_schemas(in_format: :hash)
-
       tables.reduce([]) do |agg, table|
         index_info = indexes_info.select { |row| row.fetch("tablename") == table }
-        schema = schemas.select { |row| row.fetch("table_name") == table }
+        table_fks = foreign_keys.select { |row| row.fetch("table_name") == table }
 
-        fk_columns = schema.filter_map do |row|
-          if DetectFkColumn.call(row.fetch("column_name"), all_tables)
-            row.fetch("column_name")
-          end
-        end
+        table_fks.each do |fk|
+          column_name = fk.fetch("column_name")
 
-        fk_columns.each do |column_name|
           if index_info.none? { |row| row.fetch("columns").split(",").first == column_name }
             agg.push(
               {
@@ -43,10 +39,6 @@ module RubyPgExtras
 
     private
 
-    def all_tables
-      @_all_tables ||= query_module.table_size(in_format: :hash).map { |row| row.fetch("name") }
-    end
-
     def query_module
       RubyPgExtras
     end

data/lib/ruby_pg_extras/queries/analyze_progress.sql

@@ -0,0 +1,27 @@
+/* Current ANALYZE progress as reported by pg_stat_progress_analyze */
+
+SELECT
+  a.datname AS database,
+  n.nspname AS schema,
+  c.relname AS table,
+  p.pid,
+  p.phase,
+  p.sample_blks_total,
+  p.sample_blks_scanned,
+  p.ext_stats_total,
+  p.ext_stats_computed,
+  p.child_tables_total,
+  p.child_tables_done,
+  p.current_child_table_relid
+FROM
+  pg_stat_progress_analyze p
+  LEFT JOIN pg_class c ON p.relid = c.oid
+  LEFT JOIN pg_namespace n ON c.relnamespace = n.oid
+  LEFT JOIN pg_stat_activity a ON p.pid = a.pid
+ORDER BY
+  a.datname,
+  n.nspname,
+  c.relname,
+  p.pid;
+
+

data/lib/ruby_pg_extras/queries/vacuum_io_stats.sql

@@ -0,0 +1,31 @@
+/* I/O statistics for autovacuum backends from pg_stat_io (PostgreSQL 16+) */
+
+SELECT
+  backend_type,
+  object,
+  context,
+  reads,
+  read_time,
+  writes,
+  write_time,
+  writebacks,
+  writeback_time,
+  extends,
+  extend_time,
+  fsyncs,
+  fsync_time,
+  reuses,
+  evictions,
+  stats_reset
+FROM
+  pg_stat_io
+WHERE
+  backend_type IN ('autovacuum worker', 'autovacuum launcher')
+  AND object = 'relation'
+  AND context IN ('vacuum', 'autovacuum')
+ORDER BY
+  backend_type,
+  context,
+  object;
+
+

data/lib/ruby_pg_extras/queries/vacuum_io_stats_legacy.sql

@@ -0,0 +1,5 @@
+/* I/O statistics for autovacuum backends are only available via pg_stat_io (PostgreSQL 16+). */
+
+SELECT 'Upgrade to PostgreSQL 16 or newer to use this feature' AS "feature not available";
+
+

data/lib/ruby_pg_extras/queries/vacuum_progress.sql

@@ -0,0 +1,26 @@
+/* Current VACUUM progress as reported by pg_stat_progress_vacuum */
+
+SELECT
+  a.datname AS database,
+  n.nspname AS schema,
+  c.relname AS table,
+  p.pid,
+  p.phase,
+  p.heap_blks_total,
+  p.heap_blks_scanned,
+  p.heap_blks_vacuumed,
+  p.index_vacuum_count,
+  p.max_dead_tuples,
+  p.num_dead_tuples
+FROM
+  pg_stat_progress_vacuum p
+  LEFT JOIN pg_class c ON p.relid = c.oid
+  LEFT JOIN pg_namespace n ON c.relnamespace = n.oid
+  LEFT JOIN pg_stat_activity a ON p.pid = a.pid
+ORDER BY
+  a.datname,
+  n.nspname,
+  c.relname,
+  p.pid;
+
+

data/lib/ruby_pg_extras/queries/vacuum_progress_17.sql

@@ -0,0 +1,29 @@
+/* Current VACUUM progress as reported by pg_stat_progress_vacuum */
+
+SELECT
+  a.datname AS database,
+  n.nspname AS schema,
+  c.relname AS table,
+  p.pid,
+  p.phase,
+  p.heap_blks_total,
+  p.heap_blks_scanned,
+  p.heap_blks_vacuumed,
+  p.index_vacuum_count,
+  p.indexes_total,
+  p.indexes_processed,
+  p.num_dead_item_ids,
+  p.dead_tuple_bytes,
+  p.max_dead_tuple_bytes
+FROM
+  pg_stat_progress_vacuum p
+  LEFT JOIN pg_class c ON p.relid = c.oid
+  LEFT JOIN pg_namespace n ON c.relnamespace = n.oid
+  LEFT JOIN pg_stat_activity a ON p.pid = a.pid
+ORDER BY
+  a.datname,
+  n.nspname,
+  c.relname,
+  p.pid;
+
+

data/lib/ruby_pg_extras/queries/vacuum_stats.sql

@@ -1,4 +1,4 @@
-/* Dead rows and whether an automatic vacuum is expected to be triggered */
+/* Dead rows, new inserts since last VACUUM and whether an automatic vacuum is expected to be triggered */
 
 WITH table_opts AS (
   SELECT
@@ -17,22 +17,52 @@ WITH table_opts AS (
       WHEN relopts LIKE '%autovacuum_vacuum_scale_factor%'
         THEN substring(relopts, '.*autovacuum_vacuum_scale_factor=([0-9.]+).*')::real
         ELSE current_setting('autovacuum_vacuum_scale_factor')::real
-      END AS autovacuum_vacuum_scale_factor
+      END AS autovacuum_vacuum_scale_factor,
+    CASE
+      WHEN relopts LIKE '%autovacuum_vacuum_insert_threshold%'
+        THEN substring(relopts, '.*autovacuum_vacuum_insert_threshold=([0-9.]+).*')::integer
+        ELSE current_setting('autovacuum_vacuum_insert_threshold')::integer
+      END AS autovacuum_vacuum_insert_threshold,
+    CASE
+      WHEN relopts LIKE '%autovacuum_vacuum_insert_scale_factor%'
+        THEN substring(relopts, '.*autovacuum_vacuum_insert_scale_factor=([0-9.]+).*')::real
+        ELSE current_setting('autovacuum_vacuum_insert_scale_factor')::real
+      END AS autovacuum_vacuum_insert_scale_factor
   FROM
     table_opts
 )
 SELECT
   vacuum_settings.nspname AS schema,
   vacuum_settings.relname AS table,
-  to_char(psut.last_vacuum, 'YYYY-MM-DD HH24:MI') AS last_vacuum,
+  to_char(psut.last_vacuum, 'YYYY-MM-DD HH24:MI') AS last_manual_vacuum,
+  to_char(psut.vacuum_count, '9G999G999G999') AS manual_vacuum_count,
   to_char(psut.last_autovacuum, 'YYYY-MM-DD HH24:MI') AS last_autovacuum,
+  to_char(psut.autovacuum_count, '9G999G999G999') AS autovacuum_count,
   to_char(pg_class.reltuples, '9G999G999G999') AS rowcount,
   to_char(psut.n_dead_tup, '9G999G999G999') AS dead_rowcount,
-  to_char(autovacuum_vacuum_threshold
-       + (autovacuum_vacuum_scale_factor::numeric * pg_class.reltuples), '9G999G999G999') AS autovacuum_threshold,
+  to_char(
+    autovacuum_vacuum_threshold
+    + (autovacuum_vacuum_scale_factor::numeric * pg_class.reltuples),
+    '9G999G999G999'
+  ) AS dead_tup_autovacuum_threshold,
+  to_char(psut.n_ins_since_vacuum, '9G999G999G999') AS n_ins_since_vacuum,
+  to_char(
+    autovacuum_vacuum_insert_threshold
+    + (autovacuum_vacuum_insert_scale_factor::numeric * pg_class.reltuples),
+    '9G999G999G999'
+  ) AS insert_autovacuum_threshold,
   CASE
-    WHEN autovacuum_vacuum_threshold + (autovacuum_vacuum_scale_factor::numeric * pg_class.reltuples) < psut.n_dead_tup
-    THEN 'yes'
+    WHEN psut.n_dead_tup >= autovacuum_vacuum_threshold
+         + (autovacuum_vacuum_scale_factor::numeric * pg_class.reltuples)
+      AND psut.n_ins_since_vacuum >= autovacuum_vacuum_insert_threshold
+         + (autovacuum_vacuum_insert_scale_factor::numeric * pg_class.reltuples)
+    THEN 'yes (dead_tuples & inserts)'
+    WHEN psut.n_dead_tup >= autovacuum_vacuum_threshold
+         + (autovacuum_vacuum_scale_factor::numeric * pg_class.reltuples)
+    THEN 'yes (dead_tuples)'
+    WHEN psut.n_ins_since_vacuum >= autovacuum_vacuum_insert_threshold
+         + (autovacuum_vacuum_insert_scale_factor::numeric * pg_class.reltuples)
+    THEN 'yes (inserts)'
   END AS expect_autovacuum
 FROM
   pg_stat_user_tables psut INNER JOIN pg_class ON psut.relid = pg_class.oid

data/lib/ruby_pg_extras/version.rb

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

data/spec/detect_fk_column_spec.rb

@@ -34,5 +34,41 @@ describe RubyPgExtras::DetectFkColumn do
         expect(result).to eq(true)
       end
     end
+
+    context "matching table with underscored prefix" do
+      let(:column_name) { "account_user_id" }
+      let(:tables) { ["account_users", "users"] }
+
+      it "returns true" do
+        expect(result).to eq(true)
+      end
+    end
+
+    context "matching table with uncountable noun" do
+      let(:column_name) { "fish_id" }
+      let(:tables) { ["fish", "users"] }
+
+      it "returns true" do
+        expect(result).to eq(true)
+      end
+    end
+
+    context "matching table with mixed-case column name" do
+      let(:column_name) { "User_id" }
+      let(:tables) { ["users", "posts"] }
+
+      it "returns true" do
+        expect(result).to eq(true)
+      end
+    end
+
+    context "matching table with irregular plural already pluralized" do
+      let(:column_name) { "people_id" }
+      let(:tables) { ["people", "users"] }
+
+      it "returns true" do
+        expect(result).to eq(true)
+      end
+    end
   end
 end

data/spec/ignore_list_spec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ruby-pg-extras"
+
+describe RubyPgExtras::IgnoreList do
+  describe "#ignored?" do
+    it "returns false when ignore_list is nil" do
+      list = described_class.new(nil)
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(false)
+    end
+
+    it "supports '*' to ignore everything" do
+      list = described_class.new(["*"])
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "customer_id")).to eq(true)
+    end
+
+    it "supports 'table.*' to ignore all columns for a table" do
+      list = described_class.new(["posts.*"])
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "posts", column_name: "user_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "topic_id")).to eq(false)
+    end
+
+    it "supports 'column' to ignore a column name globally" do
+      list = described_class.new(["topic_id"])
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "posts", column_name: "user_id")).to eq(false)
+    end
+
+    it "supports 'table.column' to ignore a specific table+column" do
+      list = described_class.new(["posts.topic_id"])
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "topic_id")).to eq(false)
+      expect(list.ignored?(table: "posts", column_name: "user_id")).to eq(false)
+    end
+
+    it "accepts ignore_list as a comma-separated string" do
+      list = described_class.new("posts.topic_id, customer_id")
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "customer_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "topic_id")).to eq(false)
+    end
+
+    it "strips whitespace, drops empty entries and de-duplicates" do
+      list = described_class.new([" posts.topic_id ", "", "posts.topic_id", "  "])
+      expect(list.ignored?(table: "posts", column_name: "topic_id")).to eq(true)
+      expect(list.ignored?(table: "users", column_name: "topic_id")).to eq(false)
+    end
+
+    it "raises ArgumentError for unsupported ignore_list types" do
+      expect { described_class.new(123) }.to raise_error(ArgumentError)
+      expect { described_class.new({}) }.to raise_error(ArgumentError)
+    end
+  end
+end
+
+

data/spec/missing_fk_constraints_spec.rb

@@ -6,21 +6,51 @@ require "ruby-pg-extras"
 describe "#missing_fk_constraints" do
   it "detects missing foreign keys for all tables" do
     result = RubyPgExtras.missing_fk_constraints(in_format: :hash)
-    expect(result.size).to eq(2)
-    expect(result[0]).to eq({
-                           table: "users", column_name: "company_id",
-                         })
-    expect(result[1]).to eq({
-                           table: "posts", column_name: "topic_id",
-                         })
+    expect(result).to match_array([
+      { table: "users", column_name: "customer_id" },
+      { table: "posts", column_name: "category_id" },
+    ])
   end
 
   it "detects missing foreign_keys for a specific table" do
     result = RubyPgExtras.missing_fk_constraints(args: { table_name: "posts" }, in_format: :hash)
 
-    expect(result.size).to eq(1)
-    expect(result[0]).to eq({
-      table: "posts", column_name: "topic_id",
-    })
+    expect(result).to eq([
+      { table: "posts", column_name: "category_id" },
+    ])
+  end
+
+  it "does not report columns that already have foreign key constraints" do
+    result = RubyPgExtras.missing_fk_constraints(args: { table_name: "users" }, in_format: :hash)
+    expect(result).to eq([
+      { table: "users", column_name: "customer_id" },
+    ])
+  end
+
+  it "does not report polymorphic associations (<name>_id with <name>_type)" do
+    result = RubyPgExtras.missing_fk_constraints(args: { table_name: "events" }, in_format: :hash)
+    expect(result).to eq([])
+  end
+
+  it "supports ignoring a specific table+column via args" do
+    result = RubyPgExtras.missing_fk_constraints(
+      args: { ignore_list: ["posts.category_id"] },
+      in_format: :hash
+    )
+
+    expect(result).to eq([
+      { table: "users", column_name: "customer_id" },
+    ])
+  end
+
+  it "supports ignoring a column name globally via args" do
+    result = RubyPgExtras.missing_fk_constraints(
+      args: { ignore_list: ["customer_id"] },
+      in_format: :hash
+    )
+
+    expect(result).to eq([
+      { table: "posts", column_name: "category_id" },
+    ])
   end
 end

data/spec/missing_fk_indexes_spec.rb

@@ -6,20 +6,16 @@ require "ruby-pg-extras"
 describe "missing_fk_indexes" do
   it "detects missing indexes for all tables" do
     result = RubyPgExtras.missing_fk_indexes(in_format: :hash)
-    expect(result.size).to eq(2)
-    expect(result[0]).to eq({
-      table: "users", column_name: "company_id",
-    })
-    expect(result[1]).to eq({
-      table: "posts", column_name: "topic_id",
-    })
+    expect(result).to match_array([
+      { table: "users", column_name: "company_id" },
+      { table: "posts", column_name: "topic_id" },
+    ])
   end
 
   it "detects missing indexes for specific table" do
     result = RubyPgExtras.missing_fk_indexes(args: { table_name: "posts" }, in_format: :hash)
-    expect(result.size).to eq(1)
-    expect(result[0]).to eq({
-      table: "posts", column_name: "topic_id",
-    })
+    expect(result).to eq([
+      { table: "posts", column_name: "topic_id" },
+    ])
   end
 end

data/spec/smoke_spec.rb

@@ -33,7 +33,7 @@ describe RubyPgExtras do
   describe "table_foreign_keys" do
     it "returns a correct fk info" do
       result = RubyPgExtras.table_foreign_keys(args: { table_name: :posts }, in_format: :hash)
-      expect(result.size).to eq(1)
+      expect(result.size).to eq(2)
       expect(result[0].keys).to eq(["table_name", "constraint_name", "column_name", "foreign_table_name", "foreign_column_name"])
     end
 
@@ -47,7 +47,7 @@ describe RubyPgExtras do
   describe "table_schema" do
     it "returns a correct schema" do
       result = RubyPgExtras.table_schema(args: { table_name: :users }, in_format: :hash)
-      expect(result.size).to eq(3)
+      expect(result.size).to eq(4)
       expect(result[0].keys).to eq(["column_name", "data_type", "is_nullable", "column_default"])
     end
 

data/spec/spec_helper.rb

@@ -7,7 +7,6 @@ require_relative "../lib/ruby-pg-extras"
 pg_version = ENV["PG_VERSION"]
 
 PG_PORTS = {
-  "12" => "5432",
   "13" => "5433",
   "14" => "5434",
   "15" => "5435",
@@ -22,36 +21,65 @@ ENV["DATABASE_URL"] ||= "postgresql://postgres:secret@localhost:#{port}/ruby-pg-
 RSpec.configure do |config|
   config.before(:suite) do
     DB_SCHEMA = <<-SQL
+DROP TABLE IF EXISTS categories;
+DROP TABLE IF EXISTS customers;
+DROP TABLE IF EXISTS events;
+DROP TABLE IF EXISTS subjects;
 DROP TABLE IF EXISTS posts;
 DROP TABLE IF EXISTS users;
 DROP TABLE IF EXISTS topics;
 DROP TABLE IF EXISTS companies;
 
+CREATE TABLE companies (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255)
+);
+
 CREATE TABLE users (
     id SERIAL PRIMARY KEY,
     email VARCHAR(255),
-    company_id INTEGER
+    company_id INTEGER,
+    customer_id INTEGER,
+    CONSTRAINT fk_users_company FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE CASCADE
+);
+
+CREATE TABLE topics (
+    id SERIAL PRIMARY KEY,
+    title VARCHAR(255)
 );
 
 CREATE TABLE posts (
     id SERIAL PRIMARY KEY,
     user_id INTEGER NOT NULL,
     topic_id INTEGER,
+    category_id INTEGER,
     external_id INTEGER,
     title VARCHAR(255),
-    CONSTRAINT fk_posts_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    CONSTRAINT fk_posts_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    CONSTRAINT fk_posts_topic FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE CASCADE
 );
 
-CREATE TABLE topics (
+CREATE TABLE customers (
     id SERIAL PRIMARY KEY,
-    title VARCHAR(255)
+    name VARCHAR(255)
 );
 
-CREATE TABLE companies (
+CREATE TABLE categories (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255)
+);
+
+CREATE TABLE subjects (
     id SERIAL PRIMARY KEY,
     name VARCHAR(255)
 );
 
+CREATE TABLE events (
+    id SERIAL PRIMARY KEY,
+    subject_id INTEGER,
+    subject_type VARCHAR(255)
+);
+
 CREATE INDEX index_posts_on_user_id ON posts(user_id, topic_id);
 SQL
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pg-extras
 version: !ruby/object:Gem::Version
-  version: 5.6.14
+  version: 5.6.15
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-26 00:00:00.000000000 Z
+date: 2025-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -114,12 +114,14 @@ files:
 - lib/ruby_pg_extras/detect_fk_column.rb
 - lib/ruby_pg_extras/diagnose_data.rb
 - lib/ruby_pg_extras/diagnose_print.rb
+- lib/ruby_pg_extras/ignore_list.rb
 - lib/ruby_pg_extras/index_info.rb
 - lib/ruby_pg_extras/index_info_print.rb
 - lib/ruby_pg_extras/missing_fk_constraints.rb
 - lib/ruby_pg_extras/missing_fk_indexes.rb
 - lib/ruby_pg_extras/queries/add_extensions.sql
 - lib/ruby_pg_extras/queries/all_locks.sql
+- lib/ruby_pg_extras/queries/analyze_progress.sql
 - lib/ruby_pg_extras/queries/bloat.sql
 - lib/ruby_pg_extras/queries/blocking.sql
 - lib/ruby_pg_extras/queries/buffercache_stats.sql
@@ -162,6 +164,10 @@ files:
 - lib/ruby_pg_extras/queries/total_index_size.sql
 - lib/ruby_pg_extras/queries/total_table_size.sql
 - lib/ruby_pg_extras/queries/unused_indexes.sql
+- lib/ruby_pg_extras/queries/vacuum_io_stats.sql
+- lib/ruby_pg_extras/queries/vacuum_io_stats_legacy.sql
+- lib/ruby_pg_extras/queries/vacuum_progress.sql
+- lib/ruby_pg_extras/queries/vacuum_progress_17.sql
 - lib/ruby_pg_extras/queries/vacuum_stats.sql
 - lib/ruby_pg_extras/size_parser.rb
 - lib/ruby_pg_extras/table_info.rb
@@ -172,6 +178,7 @@ files:
 - spec/detect_fk_column_spec.rb
 - spec/diagnose_data_spec.rb
 - spec/diagnose_print_spec.rb
+- spec/ignore_list_spec.rb
 - spec/index_info_spec.rb
 - spec/missing_fk_constraints_spec.rb
 - spec/missing_fk_indexes_spec.rb
@@ -207,6 +214,7 @@ test_files:
 - spec/detect_fk_column_spec.rb
 - spec/diagnose_data_spec.rb
 - spec/diagnose_print_spec.rb
+- spec/ignore_list_spec.rb
 - spec/index_info_spec.rb
 - spec/missing_fk_constraints_spec.rb
 - spec/missing_fk_indexes_spec.rb