pgbus 0.7.4 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c1610b9a423eb2d8cc6797176ec23ce9ddadab1b313f8c1ee985327a6af0c42
-  data.tar.gz: b7369612f3ac54bc3bef2e9fbec4afcc8c31a632edd667ab91d03d750f1c3e4c
+  metadata.gz: 8d2034c37f18f53d3a55df8381e7d37581905b622487f9ae4beb0c1e0f35c964
+  data.tar.gz: 419c3c7c6b62276903579ca53e39baf06ed1c0e818817e6139ceb004ad6026b3
 SHA512:
-  metadata.gz: 906567f5015468dad875c7d4948979fb78b095e1433838cbb3761eff02d54b3186a251a44e8d52508a3fd6b8cb540648d79eded23301561346f4d97878c63b11
-  data.tar.gz: 24cdb2845692e0172681fa899f5b8dac743ef00d214b0e09f4f9a0836f042026f0cceda1fab76851a52028b8b50101df9158907d487752dd301f4b28aed9466c
+  metadata.gz: 40bf9610792cef84a8792035b513c660312ff91d0642432a088f544b84846996856d7bd318b7c06d530b8cd573a2dbb78f20ee132f53540a937a075625a54afc
+  data.tar.gz: 50ddee092a20af26d348c13ae61f48a8566ec0e46687a958012dbdb508e35e2fde217ee277ddaf47333c9c5b20ad51197c0b7950c358b519c8590573433206aa

data/CHANGELOG.md

@@ -1,18 +1,3 @@
-## [0.5.1] - 2026-04-08
-
-### Fixed
-
-- **Capsule DSL: anonymous duplicate capsules are now allowed.** Configurations like `c.workers = "*: 3; *: 3; *: 3; *: 3; *: 3"` (the legacy YAML pattern of 5 forks × 3 threads, all reading every queue) were rejected at boot in 0.5.0 with `Pgbus::Configuration::CapsuleDSL::ParseError: wildcard '*' appears in two capsules`. PGMQ tolerates multiple processes reading the same queue natively (`FOR UPDATE SKIP LOCKED`), and this is the canonical way to scale CPU parallelism across forks, so the rejection was wrong.
-
-  The fix introduces a "named vs anonymous" distinction:
-
-  - The string DSL parser is now purely syntactic — it no longer enforces overlap rules.
-  - `Pgbus::Configuration#workers=` auto-assigns `:name` only to capsules whose first queue would yield a *unique* name AND is not the bare wildcard. Wildcards stay anonymous; collision-prone first-queues stay anonymous.
-  - `Pgbus::Configuration#validate_no_queue_overlap!` (called by `c.capsule :name, ...`) now only checks against existing **named** capsules. Anonymous capsules can overlap freely with each other and with named capsules.
-  - Net result: `"*: 3; *: 3; *: 3"` produces 3 anonymous capsules (3 forks), `"critical: 5; default: 10"` produces 2 named capsules (CLI `--capsule critical` still works), and named-vs-named overlap is still rejected as before.
-
-  No changes required to user configuration — legacy YAML patterns and the modern DSL both work as documented.
-
 ## [Unreleased]
 
 ### Breaking Changes
@@ -28,6 +13,25 @@
 - Warn when dashboard `web_auth` is unconfigured
 - Add `globalid` as an explicit runtime dependency (was used but only transitively available via activejob)
 
+### Fixed
+
+- **Defensive retry on stale pooled pgmq connections in the enqueue path.** `Pgbus::Client#send_message`, `#send_batch`, and `#publish_to_topic` now retry once when `@pgmq.produce*` raises `PGMQ::Errors::ConnectionError` with a message indicating the pooled `PG::Connection` was killed beneath pgmq-ruby — typically by PgBouncer hitting `server_idle_timeout` / `client_idle_timeout`, an admin disconnect, or a TCP RST. Observed in production as `PQsocket() can't get socket descriptor` on the first produce following an idle window. pgmq-ruby's `auto_reconnect` recovers on the *next* pool checkout, so a single retry is sufficient; non-stale errors (pool timeout, misconfiguration, unreachable database) still propagate unchanged. Upstream pgmq-ruby fix for the underlying misclassification is in-flight at mensfeld/pgmq-ruby#94.
+
+## [0.5.1] - 2026-04-08
+
+### Fixed
+
+- **Capsule DSL: anonymous duplicate capsules are now allowed.** Configurations like `c.workers = "*: 3; *: 3; *: 3; *: 3; *: 3"` (the legacy YAML pattern of 5 forks × 3 threads, all reading every queue) were rejected at boot in 0.5.0 with `Pgbus::Configuration::CapsuleDSL::ParseError: wildcard '*' appears in two capsules`. PGMQ tolerates multiple processes reading the same queue natively (`FOR UPDATE SKIP LOCKED`), and this is the canonical way to scale CPU parallelism across forks, so the rejection was wrong.
+
+  The fix introduces a "named vs anonymous" distinction:
+
+  - The string DSL parser is now purely syntactic — it no longer enforces overlap rules.
+  - `Pgbus::Configuration#workers=` auto-assigns `:name` only to capsules whose first queue would yield a *unique* name AND is not the bare wildcard. Wildcards stay anonymous; collision-prone first-queues stay anonymous.
+  - `Pgbus::Configuration#validate_no_queue_overlap!` (called by `c.capsule :name, ...`) now only checks against existing **named** capsules. Anonymous capsules can overlap freely with each other and with named capsules.
+  - Net result: `"*: 3; *: 3; *: 3"` produces 3 anonymous capsules (3 forks), `"critical: 5; default: 10"` produces 2 named capsules (CLI `--capsule critical` still works), and named-vs-named overlap is still rejected as before.
+
+  No changes required to user configuration — legacy YAML patterns and the modern DSL both work as documented.
+
 ## [0.1.0] - 2026-03-30
 
 - Initial release

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -156,6 +156,11 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     # queue processing and concurrency lock management.
     execute Pgbus::AutovacuumTuning.sql_for_all_queues
     execute Pgbus::AutovacuumTuning.sql_for_high_churn_tables
+
+    # Set fillfactor on queue tables to reduce bloat from PGMQ's read
+    # UPDATE operations (vt, read_ct, last_read_at). Lower fillfactor
+    # reserves page space, reducing page density during heavy update churn.
+    execute Pgbus::TableMaintenance.fillfactor_sql_for_all_queues
   end
 
   def down

data/lib/generators/pgbus/templates/tune_fillfactor.rb.erb

@@ -0,0 +1,30 @@
+class TunePgbusFillfactor < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # Set fillfactor on queue tables to reduce bloat from PGMQ's read
+    # UPDATE operations. PGMQ updates vt, read_ct, and last_read_at on
+    # every read — with fillfactor=100 (default), pages fill completely
+    # between vacuum passes. Lowering fillfactor reserves page space,
+    # reducing page density during heavy update churn. Note: because vt
+    # is indexed, these updates are not HOT-eligible.
+    #
+    # Archive tables are append-only (INSERT from queue, DELETE on
+    # retention) and don't benefit from fillfactor tuning.
+    #
+    # New queues created after this migration automatically receive
+    # this setting via Pgbus::Client at queue creation time.
+    execute Pgbus::TableMaintenance.fillfactor_sql_for_all_queues
+  end
+
+  def down
+    execute <<~SQL
+      DO $$
+      DECLARE
+        q RECORD;
+      BEGIN
+        FOR q IN SELECT queue_name FROM pgmq.meta LOOP
+          EXECUTE format('ALTER TABLE pgmq.q_%I RESET (fillfactor)', q.queue_name);
+        END LOOP;
+      END $$;
+    SQL
+  end
+end

data/lib/generators/pgbus/tune_fillfactor_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "migration_path"
+
+module Pgbus
+  module Generators
+    class TuneFillfactorGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationPath
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Set fillfactor on PGMQ queue tables to reduce page density and bloat"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        migration_template "tune_fillfactor.rb.erb",
+                           File.join(pgbus_migrate_path, "tune_pgbus_fillfactor.rb")
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus fillfactor tuning migration created!", :green
+        say ""
+        say "This migration sets fillfactor=#{Pgbus::TableMaintenance::FILLFACTOR} on all existing"
+        say "PGMQ queue tables. This reserves #{100 - Pgbus::TableMaintenance::FILLFACTOR}% of each page to"
+        say "reduce page density during PGMQ's heavy read UPDATE churn."
+        say ""
+        say "New queues created at runtime will automatically receive"
+        say "this setting."
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Restart pgbus: bin/pgbus start"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -87,7 +87,9 @@ module Pgbus
       target = @queue_strategy.target_queue(queue_name, priority)
       ensure_queue(queue_name)
       Instrumentation.instrument("pgbus.client.send_message", queue: target) do
-        synchronized { @pgmq.produce(target, serialize(payload), headers: headers && serialize(headers), delay: delay) }
+        with_stale_connection_retry do
+          synchronized { @pgmq.produce(target, serialize(payload), headers: headers && serialize(headers), delay: delay) }
+        end
       end
     end
 
@@ -96,7 +98,9 @@ module Pgbus
       ensure_queue(queue_name)
       serialized, serialized_headers = serialize_batch(payloads, headers)
       Instrumentation.instrument("pgbus.client.send_batch", queue: full_name, size: payloads.size) do
-        synchronized { @pgmq.produce_batch(full_name, serialized, headers: serialized_headers, delay: delay) }
+        with_stale_connection_retry do
+          synchronized { @pgmq.produce_batch(full_name, serialized, headers: serialized_headers, delay: delay) }
+        end
       end
     end
 
@@ -318,13 +322,15 @@ module Pgbus
     end
 
     def publish_to_topic(routing_key, payload, headers: nil, delay: 0)
-      synchronized do
-        @pgmq.produce_topic(
-          routing_key,
-          serialize(payload),
-          headers: headers && serialize(headers),
-          delay: delay
-        )
+      with_stale_connection_retry do
+        synchronized do
+          @pgmq.produce_topic(
+            routing_key,
+            serialize(payload),
+            headers: headers && serialize(headers),
+            delay: delay
+          )
+        end
       end
     end
 
@@ -502,6 +508,7 @@ module Pgbus
     def tune_autovacuum(queue_name)
       with_raw_connection do |conn|
         conn.exec(AutovacuumTuning.sql_for_queue(queue_name))
+        conn.exec(TableMaintenance.fillfactor_sql_for_queue(queue_name))
       end
     rescue StandardError => e
       Pgbus.logger.debug { "[Pgbus::Client] Autovacuum tuning failed for #{queue_name}: #{e.message}" }
@@ -518,6 +525,51 @@ module Pgbus
       end
     end
 
+    # Substrings that indicate the pooled PG::Connection was already dead
+    # *before* pgmq-ruby tried to use it — typically killed by a connection
+    # pooler (PgBouncer server_idle_timeout / client_idle_timeout), an admin
+    # disconnect, or a TCP RST while the slot was idle.
+    #
+    # Only pre-checkout / pre-flight errors belong here. Mid-flight errors
+    # like "server closed the connection" or "connection to server was lost"
+    # are excluded because PG may have already committed the INSERT before
+    # the socket died, and retrying would duplicate the message.
+    #
+    # See mensfeld/pgmq-ruby#94.
+    STALE_CONNECTION_PATTERNS = [
+      "pqsocket() can't get socket descriptor",
+      "connection is closed",
+      "connection has been closed",
+      "connection not open",
+      "no connection to the server"
+    ].freeze
+    private_constant :STALE_CONNECTION_PATTERNS
+
+    # Enqueue path guard: rescue PGMQ::Errors::ConnectionError once if its
+    # message matches a known stale-socket pattern. pgmq-ruby's
+    # auto_reconnect + verify_connection! already recovers on the *next*
+    # checkout, so a single retry is sufficient. Other connection errors
+    # (pool timeout, misconfiguration, truly unreachable DB) propagate.
+    def with_stale_connection_retry
+      attempts = 0
+      begin
+        yield
+      rescue PGMQ::Errors::ConnectionError => e
+        attempts += 1
+        raise unless attempts == 1 && stale_connection_error?(e)
+
+        Pgbus.logger.warn do
+          "[Pgbus::Client] Retrying produce after stale pgmq connection: #{e.message}"
+        end
+        retry
+      end
+    end
+
+    def stale_connection_error?(error)
+      message = error.message.to_s.downcase
+      STALE_CONNECTION_PATTERNS.any? { |pattern| message.include?(pattern) }
+    end
+
     def serialize(data)
       case data
       when String

data/lib/pgbus/configuration.rb

@@ -78,6 +78,7 @@ module Pgbus
 
     # Recurring jobs
     attr_accessor :recurring_tasks, :recurring_schedule_interval, :recurring_tasks_file, :skip_recurring
+    attr_writer :recurring_tasks_files
     attr_reader :recurring_execution_retention # rubocop:disable Style/AccessorGrouping
 
     # Multi-database support (optional separate database for pgbus tables)
@@ -161,6 +162,7 @@ module Pgbus
       @recurring_tasks = nil
       @recurring_schedule_interval = 1.0
       @recurring_tasks_file = nil
+      @recurring_tasks_files = nil
       @skip_recurring = false
       @recurring_execution_retention = 7 * 24 * 3600 # 7 days
 
@@ -492,6 +494,12 @@ module Pgbus
       @recurring_execution_retention = coerce_duration!(value, :recurring_execution_retention)
     end
 
+    def recurring_tasks_files
+      return @recurring_tasks_files if @recurring_tasks_files
+
+      recurring_tasks_file ? [recurring_tasks_file] : nil
+    end
+
     # Returns the connection pool size to use for the PGMQ client.
     #
     # If +pool_size+ was explicitly set, returns that value unchanged. Otherwise

data/lib/pgbus/engine.rb

@@ -18,10 +18,22 @@ module Pgbus
     end
 
     initializer "pgbus.recurring" do |app|
-      recurring_path = app.root.join("config", "recurring.yml")
-      if recurring_path.exist? && !Pgbus.configuration.recurring_tasks
-        Pgbus.configuration.recurring_tasks = Pgbus::Recurring::ConfigLoader.load(recurring_path)
-        Pgbus.configuration.recurring_tasks_file ||= recurring_path.to_s
+      next if Pgbus.configuration.recurring_tasks
+
+      config = Pgbus.configuration
+      files = config.recurring_tasks_files
+      default_path = app.root.join("config", "recurring.yml")
+
+      if files
+        tasks = Pgbus::Recurring::ConfigLoader.load_all(files)
+        if tasks.empty? && default_path.exist? && files.none? { |f| File.expand_path(f.to_s) == File.expand_path(default_path.to_s) }
+          tasks = Pgbus::Recurring::ConfigLoader.load(default_path)
+          config.recurring_tasks_file ||= default_path.to_s
+        end
+        config.recurring_tasks = tasks unless tasks.empty?
+      elsif default_path.exist?
+        config.recurring_tasks = Pgbus::Recurring::ConfigLoader.load(default_path)
+        config.recurring_tasks_file ||= default_path.to_s
       end
     end
 

data/lib/pgbus/generators/migration_detector.rb

@@ -74,7 +74,8 @@ module Pgbus
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
         add_failed_events_index: "pgbus:add_failed_events_index",
-        tune_autovacuum: "pgbus:tune_autovacuum"
+        tune_autovacuum: "pgbus:tune_autovacuum",
+        tune_fillfactor: "pgbus:tune_fillfactor"
       }.freeze
 
       # Human-friendly description of each migration for the generator
@@ -90,7 +91,8 @@ module Pgbus
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
-        tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables"
+        tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
+        tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
       }.freeze
 
       def initialize(connection)
@@ -113,7 +115,8 @@ module Pgbus
           *outbox_migrations,
           *recurring_migrations,
           *failed_events_index_migrations,
-          *autovacuum_migrations
+          *autovacuum_migrations,
+          *fillfactor_migrations
         ]
       end
 
@@ -205,6 +208,15 @@ module Pgbus
         [:tune_autovacuum]
       end
 
+      # Fillfactor tuning: check if any PGMQ queue table already has
+      # fillfactor applied. If not, queue the migration.
+      def fillfactor_migrations
+        return [] unless pgmq_schema_exists?
+        return [] if fillfactor_already_tuned?
+
+        [:tune_fillfactor]
+      end
+
       # --- schema probes -------------------------------------------------
 
       def table_exists?(name)
@@ -247,6 +259,22 @@ module Pgbus
       rescue StandardError
         true # if we can't tell, assume already tuned (safe default)
       end
+
+      def fillfactor_already_tuned?
+        queue_name = connection.select_value("SELECT queue_name FROM pgmq.meta ORDER BY queue_name LIMIT 1")
+        return true unless queue_name # no queues = nothing to tune, skip
+
+        result = connection.select_value(<<~SQL)
+          SELECT reloptions::text LIKE '%fillfactor%'
+          FROM pg_class
+          WHERE relname = 'q_#{queue_name}'
+            AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'pgmq')
+        SQL
+
+        [true, "t"].include?(result)
+      rescue StandardError
+        true # if we can't tell, assume already tuned (safe default)
+      end
     end
   end
 end

data/lib/pgbus/process/dispatcher.rb

@@ -15,6 +15,7 @@ module Pgbus
       OUTBOX_CLEANUP_INTERVAL = 3600 # Run outbox cleanup every hour
       JOB_LOCK_CLEANUP_INTERVAL = 300 # Run job lock cleanup every 5 minutes
       STATS_CLEANUP_INTERVAL = 3600 # Run stats cleanup every hour
+      TABLE_MAINTENANCE_INTERVAL = Pgbus::TableMaintenance::MAINTENANCE_INTERVAL
 
       # Page size for archive compaction. Each cycle deletes up to this
       # many archived rows per queue. Tuned via constant rather than
@@ -37,6 +38,7 @@ module Pgbus
         @last_outbox_cleanup_at = monotonic_now
         @last_job_lock_cleanup_at = monotonic_now
         @last_stats_cleanup_at = monotonic_now
+        @last_table_maintenance_at = monotonic_now
       end
 
       def run
@@ -84,6 +86,7 @@ module Pgbus
         run_if_due(now, :@last_outbox_cleanup_at, OUTBOX_CLEANUP_INTERVAL) { cleanup_outbox }
         run_if_due(now, :@last_job_lock_cleanup_at, JOB_LOCK_CLEANUP_INTERVAL) { cleanup_job_locks }
         run_if_due(now, :@last_stats_cleanup_at, STATS_CLEANUP_INTERVAL) { cleanup_stats }
+        run_if_due(now, :@last_table_maintenance_at, TABLE_MAINTENANCE_INTERVAL) { run_table_maintenance }
       end
 
       # Only update the timestamp when the block succeeds.
@@ -158,6 +161,19 @@ module Pgbus
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old stream stats" } if deleted.positive?
       end
 
+      def run_table_maintenance
+        conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
+        raw_conn = conn.raw_connection
+        maintained = TableMaintenance.run_maintenance(
+          raw_conn,
+          threshold: TableMaintenance::BLOAT_THRESHOLD,
+          reindex: true
+        )
+        Pgbus.logger.info { "[Pgbus] Table maintenance completed: #{maintained} table(s) vacuumed" } if maintained.positive?
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Table maintenance failed: #{e.message}" }
+      end
+
       def cleanup_job_locks
         # Clean up truly orphaned uniqueness keys: rows whose referenced
         # message no longer exists in the PGMQ queue. This handles crashes

data/lib/pgbus/process/supervisor.rb

@@ -145,9 +145,12 @@ module Pgbus
 
       def recurring_tasks_configured?
         return true if config.recurring_tasks&.any?
+
+        files = config.recurring_tasks_files
+        return true if files&.any? { |f| File.exist?(f.to_s) }
+
         return true if config.recurring_tasks_file && File.exist?(config.recurring_tasks_file.to_s)
 
-        # Check default location
         if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
           default_path = Rails.root.join("config", "recurring.yml")
           return File.exist?(default_path.to_s)
@@ -159,6 +162,13 @@ module Pgbus
       def load_recurring_config
         return if config.recurring_tasks&.any?
 
+        files = config.recurring_tasks_files
+        if files
+          tasks = Recurring::ConfigLoader.load_all(files)
+          config.recurring_tasks = tasks unless tasks.empty?
+          return if tasks.any?
+        end
+
         path = config.recurring_tasks_file
         path ||= defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.join("config", "recurring.yml") : nil
         return unless path && File.exist?(path.to_s)

data/lib/pgbus/recurring/config_loader.rb

@@ -23,6 +23,30 @@ module Pgbus
         {}
       end
 
+      def load_all(paths, env: nil)
+        normalized = Array(paths).compact.map { |p| p.respond_to?(:to_path) ? p.to_path : p.to_s }.reject(&:empty?)
+        return {} if normalized.empty?
+
+        env ||= detect_env
+
+        normalized.each_with_object({}) do |path, acc|
+          unless File.exist?(path.to_s)
+            Pgbus.logger.warn { "[Pgbus] Recurring file not found, skipping: #{path}" }
+            next
+          end
+
+          parsed = load(path, env: env)
+          unless parsed.is_a?(Hash)
+            Pgbus.logger.error { "[Pgbus] Invalid recurring config in #{path}: expected Hash, got #{parsed.class}" }
+            next
+          end
+          parsed.each_key do |key|
+            Pgbus.logger.debug { "[Pgbus] Recurring task '#{key}' overridden by #{path}" } if acc.key?(key)
+          end
+          acc.merge!(parsed)
+        end
+      end
+
       def detect_env
         if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
           Rails.env.to_s

data/lib/pgbus/table_maintenance.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Proactive table maintenance to reduce bloat on PGMQ queue tables.
+  #
+  # PGMQ's read operation UPDATEs three columns (vt, read_ct, last_read_at)
+  # on every message read. With the default fillfactor of 100, every UPDATE
+  # creates a new heap tuple AND a new index entry — the dead tuple and its
+  # old index pointer remain until VACUUM. Under sustained load, autovacuum
+  # can't keep up and B-tree indexes bloat.
+  #
+  # Setting fillfactor=70 on queue tables reserves 30% of each page for
+  # update churn. Because `vt` is indexed and changes on every read, these
+  # writes are not HOT updates, but leaving headroom on heap pages still
+  # reduces page density for a table that is updated heavily between vacuum
+  # passes.
+  #
+  # More importantly, this module provides targeted VACUUM: instead of
+  # relying solely on autovacuum's global heuristics, the dispatcher
+  # periodically checks pg_stat_user_tables for tables with high dead tuple
+  # ratios and vacuums them explicitly. This is inspired by pgque's
+  # philosophy of measuring bloat before acting.
+  module TableMaintenance
+    FILLFACTOR = 70
+    BLOAT_THRESHOLD = 0.1
+    MAINTENANCE_INTERVAL = 6 * 3600 # 6 hours
+
+    class << self
+      def fillfactor_sql_for_queue(queue_name)
+        "ALTER TABLE pgmq.q_#{queue_name} SET (fillfactor = #{FILLFACTOR});"
+      end
+
+      def fillfactor_sql_for_all_queues
+        <<~SQL
+          DO $$
+          DECLARE
+            q RECORD;
+          BEGIN
+            FOR q IN SELECT queue_name FROM pgmq.meta LOOP
+              EXECUTE format('ALTER TABLE pgmq.q_%I SET (fillfactor = #{FILLFACTOR})', q.queue_name);
+            END LOOP;
+          END $$;
+        SQL
+      end
+
+      def vacuum_candidates(conn, threshold: BLOAT_THRESHOLD)
+        rows = conn.exec(<<~SQL)
+          SELECT schemaname, relname, n_dead_tup, n_live_tup
+          FROM pg_stat_user_tables
+          WHERE schemaname = 'pgmq'
+            AND relname LIKE 'q_%'
+          ORDER BY n_dead_tup DESC
+        SQL
+
+        rows.each_with_object([]) do |row, candidates|
+          dead = row["n_dead_tup"].to_i
+          live = row["n_live_tup"].to_i
+          total = dead + live
+          next if total.zero?
+
+          ratio = dead.to_f / total
+          next unless ratio > threshold
+
+          candidates << {
+            table: "#{row["schemaname"]}.#{row["relname"]}",
+            dead_tuples: dead,
+            live_tuples: live,
+            dead_ratio: ratio.round(4)
+          }
+        end
+      end
+
+      def vacuum_sql(table)
+        schema, relname = table.split(".", 2)
+        "VACUUM \"#{schema}\".\"#{relname}\""
+      end
+
+      def reindex_sql(table)
+        schema, relname = table.split(".", 2)
+        "REINDEX TABLE CONCURRENTLY \"#{schema}\".\"#{relname}\""
+      end
+
+      def run_maintenance(conn, threshold: BLOAT_THRESHOLD, reindex: true)
+        candidates = vacuum_candidates(conn, threshold: threshold)
+        return 0 if candidates.empty?
+
+        maintained = 0
+        candidates.each do |candidate|
+          table = candidate[:table]
+          Pgbus.logger.info do
+            "[Pgbus::TableMaintenance] Vacuuming #{table} " \
+              "(dead_ratio=#{candidate[:dead_ratio]}, dead=#{candidate[:dead_tuples]})"
+          end
+          conn.exec(vacuum_sql(table))
+
+          if reindex
+            Pgbus.logger.info { "[Pgbus::TableMaintenance] Reindexing #{table}" }
+            conn.exec(reindex_sql(table))
+          end
+
+          maintained += 1
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::TableMaintenance] Failed to maintain #{table}: #{e.message}" }
+        end
+
+        maintained
+      end
+    end
+  end
+end

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.7.4"
+  VERSION = "0.7.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.5
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -234,8 +234,10 @@ files:
 - lib/generators/pgbus/templates/pgbus_binstub.erb
 - lib/generators/pgbus/templates/recurring.yml.erb
 - lib/generators/pgbus/templates/tune_autovacuum.rb.erb
+- lib/generators/pgbus/templates/tune_fillfactor.rb.erb
 - lib/generators/pgbus/templates/upgrade_pgmq.rb.erb
 - lib/generators/pgbus/tune_autovacuum_generator.rb
+- lib/generators/pgbus/tune_fillfactor_generator.rb
 - lib/generators/pgbus/update_generator.rb
 - lib/generators/pgbus/upgrade_pgmq_generator.rb
 - lib/pgbus.rb
@@ -309,6 +311,7 @@ files:
 - lib/pgbus/streams/turbo_broadcastable.rb
 - lib/pgbus/streams/turbo_stream_override.rb
 - lib/pgbus/streams/watermark_cache_middleware.rb
+- lib/pgbus/table_maintenance.rb
 - lib/pgbus/testing.rb
 - lib/pgbus/testing/assertions.rb
 - lib/pgbus/testing/minitest.rb