pgbus 0.7.4 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c1610b9a423eb2d8cc6797176ec23ce9ddadab1b313f8c1ee985327a6af0c42
-  data.tar.gz: b7369612f3ac54bc3bef2e9fbec4afcc8c31a632edd667ab91d03d750f1c3e4c
+  metadata.gz: a28025e2b7af463cb6ff57d12e516d461b9b968ed7bb4eb4568be18d77ff2678
+  data.tar.gz: fd39f5774df158b0cf06e85a6ef52f0114d649008f56b4736a782ce895baae0b
 SHA512:
-  metadata.gz: 906567f5015468dad875c7d4948979fb78b095e1433838cbb3761eff02d54b3186a251a44e8d52508a3fd6b8cb540648d79eded23301561346f4d97878c63b11
-  data.tar.gz: 24cdb2845692e0172681fa899f5b8dac743ef00d214b0e09f4f9a0836f042026f0cceda1fab76851a52028b8b50101df9158907d487752dd301f4b28aed9466c
+  metadata.gz: 19ced25de78f93ccbf307e2bdd72a5dbc46050657c6e394bc9e6a16d8665fa19bc2a29cebf2fcbda8c31eb07e07d94545322eec80c5d61915ddd6bfc924de105
+  data.tar.gz: 9d8e2a9255ce011edf6bc2647fbd4d604db65b8fb2470c17735149599072f2824e510db4e97c4d241cdd4d6a9fef2ff7c23638738cd40de581ee56a07b783f6b

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/ensure_stream_queue.rb

@@ -19,17 +19,20 @@ module Pgbus
     # stream and from the streamer on first subscription per stream.
     module EnsureStreamQueue
       def ensure_stream_queue(stream_name)
-        ensure_queue(stream_name)
         full_name = config.queue_name(stream_name)
 
-        # PGMQ's default NOTIFY throttle is 250ms — meant to coalesce
-        # high-frequency worker queue inserts. Streams are latency-
-        # sensitive and need every broadcast to fire a NOTIFY, even
-        # when several are batched within a single millisecond.
-        # Override the throttle to 0 specifically for stream queues.
-        # Use the idempotent path to avoid deadlocks when multiple
-        # processes race to set up the same stream queue.
-        synchronized { enable_notify_if_needed(full_name, 0) }
+        with_stale_connection_retry do
+          ensure_queue(stream_name)
+
+          # PGMQ's default NOTIFY throttle is 250ms — meant to coalesce
+          # high-frequency worker queue inserts. Streams are latency-
+          # sensitive and need every broadcast to fire a NOTIFY, even
+          # when several are batched within a single millisecond.
+          # Override the throttle to 0 specifically for stream queues.
+          # Use the idempotent path to avoid deadlocks when multiple
+          # processes race to set up the same stream queue.
+          synchronized { enable_notify_if_needed(full_name, 0) }
+        end
 
         # CREATE INDEX IF NOT EXISTS is idempotent in Postgres but still
         # requires a roundtrip and a brief ACCESS SHARE lock on the archive

data/lib/pgbus/client.rb

@@ -85,32 +85,40 @@ module Pgbus
 
     def send_message(queue_name, payload, headers: nil, delay: 0, priority: nil)
       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
+          ensure_queue(queue_name)
+          synchronized { @pgmq.produce(target, serialize(payload), headers: headers && serialize(headers), delay: delay) }
+        end
       end
     end
 
     def send_batch(queue_name, payloads, headers: nil, delay: 0)
       full_name = config.queue_name(queue_name)
-      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
+          ensure_queue(queue_name)
+          synchronized { @pgmq.produce_batch(full_name, serialized, headers: serialized_headers, delay: delay) }
+        end
       end
     end
 
     def read_message(queue_name, vt: nil)
       full_name = config.queue_name(queue_name)
       Instrumentation.instrument("pgbus.client.read_message", queue: full_name) do
-        synchronized { @pgmq.read(full_name, vt: vt || config.visibility_timeout) }
+        with_stale_connection_retry do
+          synchronized { @pgmq.read(full_name, vt: vt || config.visibility_timeout) }
+        end
       end
     end
 
     def read_batch(queue_name, qty:, vt: nil)
       full_name = config.queue_name(queue_name)
       Instrumentation.instrument("pgbus.client.read_batch", queue: full_name, qty: qty) do
-        synchronized { @pgmq.read_batch(full_name, vt: vt || config.visibility_timeout, qty: qty) }
+        with_stale_connection_retry do
+          synchronized { @pgmq.read_batch(full_name, vt: vt || config.visibility_timeout, qty: qty) }
+        end
       end
     end
 
@@ -130,7 +138,9 @@ module Pgbus
         break if remaining <= 0
 
         msgs = Instrumentation.instrument("pgbus.client.read_batch", queue: pq_name, qty: remaining) do
-          synchronized { @pgmq.read_batch(pq_name, vt: vt || config.visibility_timeout, qty: remaining) }
+          with_stale_connection_retry do
+            synchronized { @pgmq.read_batch(pq_name, vt: vt || config.visibility_timeout, qty: remaining) }
+          end
         end || []
 
         msgs.each { |m| results << [pq_name, m] }
@@ -142,14 +152,16 @@ module Pgbus
 
     def read_with_poll(queue_name, qty:, vt: nil, max_poll_seconds: 5, poll_interval_ms: 100)
       full_name = config.queue_name(queue_name)
-      synchronized do
-        @pgmq.read_with_poll(
-          full_name,
-          vt: vt || config.visibility_timeout,
-          qty: qty,
-          max_poll_seconds: max_poll_seconds,
-          poll_interval_ms: poll_interval_ms
-        )
+      with_stale_connection_retry do
+        synchronized do
+          @pgmq.read_with_poll(
+            full_name,
+            vt: vt || config.visibility_timeout,
+            qty: qty,
+            max_poll_seconds: max_poll_seconds,
+            poll_interval_ms: poll_interval_ms
+          )
+        end
       end
     end
 
@@ -164,8 +176,10 @@ module Pgbus
     def read_multi(queue_names, qty:, vt: nil, limit: nil)
       full_names = queue_names.map { |q| config.queue_name(q) }
       Instrumentation.instrument("pgbus.client.read_multi", queues: full_names, qty: qty, limit: limit) do
-        synchronized do
-          @pgmq.read_multi(full_names, vt: vt || config.visibility_timeout, qty: qty, limit: limit)
+        with_stale_connection_retry do
+          synchronized do
+            @pgmq.read_multi(full_names, vt: vt || config.visibility_timeout, qty: qty, limit: limit)
+          end
         end
       end
     end
@@ -174,74 +188,99 @@ module Pgbus
     # the full PGMQ queue name (e.g. from priority sub-queues or dashboard).
     def delete_message(queue_name, msg_id, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      synchronized { @pgmq.delete(name, msg_id) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.delete(name, msg_id) }
+      end
     end
 
     # Archive a message. Pass prefixed: false when queue_name is already
     # the full PGMQ queue name.
     def archive_message(queue_name, msg_id, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      synchronized { @pgmq.archive(name, msg_id) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.archive(name, msg_id) }
+      end
     end
 
     # Batch archive — moves multiple messages to the archive table in one call.
     def archive_batch(queue_name, msg_ids, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      synchronized { @pgmq.archive_batch(name, msg_ids) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.archive_batch(name, msg_ids) }
+      end
     end
 
     # Batch delete — permanently removes multiple messages in one call.
     def delete_batch(queue_name, msg_ids, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      synchronized { @pgmq.delete_batch(name, msg_ids) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.delete_batch(name, msg_ids) }
+      end
     end
 
     # Set visibility timeout. Pass prefixed: false when queue_name is already
     # the full PGMQ queue name.
     def set_visibility_timeout(queue_name, msg_id, vt:, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      synchronized { @pgmq.set_vt(name, msg_id, vt: vt) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.set_vt(name, msg_id, vt: vt) }
+      end
     end
 
+    # Open a PGMQ transaction. The caller block may run twice if the first
+    # attempt hits a pre-flight stale-connection error — safe because no SQL
+    # was sent on the first attempt (the connection was dead before the BEGIN).
     def transaction(&block)
-      synchronized { @pgmq.transaction(&block) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.transaction(&block) }
+      end
     end
 
     def move_to_dead_letter(queue_name, message)
-      ensure_dead_letter_queue(queue_name)
       dlq_name = config.dead_letter_queue_name(queue_name)
       full_queue = config.queue_name(queue_name)
 
-      synchronized do
-        @pgmq.transaction do |txn|
-          txn.produce(dlq_name, message.message, headers: message.headers)
-          txn.delete(full_queue, message.msg_id.to_i)
+      with_stale_connection_retry do
+        ensure_dead_letter_queue(queue_name)
+        synchronized do
+          @pgmq.transaction do |txn|
+            txn.produce(dlq_name, message.message, headers: message.headers)
+            txn.delete(full_queue, message.msg_id.to_i)
+          end
         end
       end
     end
 
     def metrics(queue_name = nil)
-      synchronized do
-        if queue_name
-          @pgmq.metrics(config.queue_name(queue_name))
-        else
-          @pgmq.metrics_all
+      with_stale_connection_retry do
+        synchronized do
+          if queue_name
+            @pgmq.metrics(config.queue_name(queue_name))
+          else
+            @pgmq.metrics_all
+          end
         end
       end
     end
 
     def list_queues
-      synchronized { @pgmq.list_queues }
+      with_stale_connection_retry do
+        synchronized { @pgmq.list_queues }
+      end
     end
 
     def purge_queue(queue_name, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      synchronized { @pgmq.purge_queue(name) }
+      with_stale_connection_retry do
+        synchronized { @pgmq.purge_queue(name) }
+      end
     end
 
     def drop_queue(queue_name, prefixed: true)
       name = prefixed ? config.queue_name(queue_name) : queue_name
-      result = synchronized { @pgmq.drop_queue(name) }
+      result = with_stale_connection_retry do
+        synchronized { @pgmq.drop_queue(name) }
+      end
       @queues_created.delete(name)
       result
     end
@@ -313,18 +352,22 @@ module Pgbus
     # Topic routing
     def bind_topic(pattern, queue_name)
       full_name = config.queue_name(queue_name)
-      ensure_queue(queue_name)
-      synchronized { @pgmq.bind_topic(pattern, full_name) }
+      with_stale_connection_retry do
+        ensure_queue(queue_name)
+        synchronized { @pgmq.bind_topic(pattern, full_name) }
+      end
     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 +545,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 +562,60 @@ 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",
+      "ssl error: unexpected eof",
+      "ssl syscall error"
+    ].freeze
+    private_constant :STALE_CONNECTION_PATTERNS
+
+    # 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.
+    #
+    # Wraps every @pgmq.* call site. Pattern matching is intentionally narrow
+    # (pre-flight / idle-socket signals only), so retry is safe even for
+    # non-idempotent ops like delete/archive — a matched error means the
+    # connection was dead *before* pgmq-ruby tried to use it, so no SQL was
+    # ever sent. Mid-flight errors like "server closed the connection" are
+    # excluded from the pattern list for this reason.
+    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 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.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.6
 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