pgbus 0.22.0 → 0.23.1

data/lib/pgbus/configuration.rb

@@ -52,6 +52,37 @@ module Pgbus
     # Batch::Sweep then cannot tell a deleted batch job from one whose message
     # vanished another way (a purged queue): both count as completed, silently.
     attr_reader :completed_jobs
+    # completion_synchronous_commit (issue #619, opt-in): false commits a job's
+    # completion (the executor's archive or delete, the completer's
+    # archive_batch or delete_batch) with `SET LOCAL synchronous_commit TO off`,
+    # in one libpq pipeline: BEGIN, the SET LOCAL, the prepared statement and
+    # COMMIT go out with one sync, so the job stops waiting for its WAL flush.
+    # A completion is then acknowledged before its WAL record reaches disk: a
+    # Postgres server crash (not a client crash, not a planned switchover), or a
+    # failover to a standby that has not yet received that WAL (it also stops
+    # waiting for a synchronous standby), within about three times
+    # wal_writer_delay can lose completions committed in that window, and each
+    # lost completion redelivers its job after visibility_timeout. Sends, retries, dead-letter moves, the EventBus
+    # consumer's archive and dashboard actions keep full durability, and a
+    # completion inside a caller's transaction is left to that transaction.
+    # Native statements on pgbus's own connections only: with
+    # native_statements = false, or on ActiveRecord's shared connection (a
+    # connection_params Proc), it has no effect (pgbus doctor warns). Needs
+    # libpq 14+ and pg 1.5+ (pipeline mode), checked by validate!. true
+    # (default) commits as before.
+    attr_reader :completion_synchronous_commit
+    # quiet_active_job_logs (issue #618): true makes each worker process
+    # unsubscribe ActiveJob's LogSubscriber from perform_start.active_job and
+    # perform.active_job (Pgbus::ActiveJob::QuietLogs), so the per-job
+    # "Performing …" / "Performed …" info lines stop, and with them ActiveJob's
+    # "Error performing …" line (the same perform listener writes it): an
+    # exception that escapes ActiveJob's handlers is still logged by
+    # ErrorReporter and recorded in pgbus_failed_events, one retry_on catches
+    # still logs ActiveJob's "Retrying …" line, and a job a before_perform
+    # callback halted logs nothing.
+    # Enqueued, Retrying, Stopped retrying and Discarded still log, and the web
+    # process is untouched. Without ActiveJob it does nothing.
+    attr_reader :quiet_active_job_logs
     # visibility_heartbeat / visibility_heartbeat_interval: while a job runs,
     # its message's visibility timeout is re-armed every interval seconds
     # (default: a third of visibility_timeout), so a job that outlives the
@@ -367,6 +398,8 @@ module Pgbus
       @completion_batching = false
       @completion_batch_size = 100
       @completed_jobs = :archive
+      @completion_synchronous_commit = true
+      @quiet_active_job_logs = false
       @execution_mode = :threads
 
       @max_jobs_per_worker = nil
@@ -564,12 +597,13 @@ module Pgbus
       @streams_idle_timeout = 3_600 # 1 hour
       # 250ms — this value plays two roles: (1) the TCP keepalive
       # interval for the streamer's PG LISTEN connection, and (2) the
-      # upper bound on how long Dispatcher#handle_connect waits for
-      # the Listener to acknowledge a synchronous ensure_listening
-      # call. 5s was unbounded enough to drop messages on a
-      # realistic subscribe burst; 250ms keeps the connect-path race
-      # window tight while still leaving headroom over a typical
-      # PG keepalive interval.
+      # budget (plus 1s) a stream's first connect waits for a stuck local
+      # Listener to acknowledge its ensure_listening (with
+      # streams_listen_scope :master, HubClient waits this cycle plus 2s
+      # before failing over). A live listener
+      # is woken through a pipe and acks within a thread hop, and a
+      # connect on a stream that already has a subscriber does not
+      # wait at all (issue #630), so connects no longer pay this cycle.
       @streams_listen_health_check_ms = 250
       @streams_write_deadline_ms = 5_000
       # Deadline (ms) for a socket write made INSIDE the dispatcher's
@@ -856,6 +890,22 @@ module Pgbus
       @completed_jobs = mode
     end
 
+    def completion_synchronous_commit=(value)
+      unless [true, false].include?(value)
+        raise Pgbus::ConfigurationError, "completion_synchronous_commit must be true or false (got #{value.inspect})"
+      end
+
+      @completion_synchronous_commit = value
+    end
+
+    def quiet_active_job_logs=(value)
+      unless [true, false].include?(value)
+        raise Pgbus::ConfigurationError, "quiet_active_job_logs must be true or false (got #{value.inspect})"
+      end
+
+      @quiet_active_job_logs = value
+    end
+
     def native_statements=(value)
       raise Pgbus::ConfigurationError, "native_statements must be true or false" unless [true, false].include?(value)
 
@@ -1052,6 +1102,7 @@ module Pgbus
 
       validate_read_ahead!
       validate_completion_batching!
+      validate_completion_synchronous_commit!
       validate_capsule_processes!
 
       if priority_levels && !(priority_levels.is_a?(Integer) && priority_levels >= 1 && priority_levels <= 10)
@@ -1843,6 +1894,20 @@ module Pgbus
             "execution_mode :async"
     end
 
+    # The asynchronous completion commit runs in libpq pipeline mode (issue
+    # #619): libpq 14+ and a pg gem that wraps it (1.5+). Checked here, once,
+    # rather than on every completion.
+    def validate_completion_synchronous_commit!
+      return if completion_synchronous_commit
+
+      require "pg" unless defined?(::PG::Connection)
+      return if ::PG::Connection.method_defined?(:enter_pipeline_mode) && ::PG.library_version >= 140_000
+
+      raise Pgbus::ConfigurationError,
+            "completion_synchronous_commit = false needs libpq 14+ and pg 1.5+ (pipeline mode); " \
+            "this process has libpq #{::PG.library_version} and pg #{::PG::VERSION}"
+    end
+
     # Shared resolver for a dedicated connection (streamer LISTEN / worker
     # NotifyListener) that can override the base `connection_options` to bypass a
     # pooler. Precedence: a full `url` wins outright; otherwise `host`/`port`

data/lib/pgbus/dead_letter_header.rb

@@ -20,6 +20,9 @@ module Pgbus
     ORIGINAL_KEY = "pgbus_original_headers"
     VERSION = 1
     REASON_MAX_RETRIES = "max_retries_exceeded"
+    # A :while_executing duplicate skipped on every read while another
+    # message held its key, until read_ct passed max_retries (issue #629).
+    REASON_UNIQUENESS_CONFLICT = "uniqueness_conflict"
     # The release that started writing the block: rows without it predate it.
     SINCE = "0.18.0"
     MESSAGE_LIMIT = 1_000

data/lib/pgbus/doctor.rb

@@ -5,7 +5,7 @@ require "pgbus/mcp/health_analyzer"
 
 module Pgbus
   # Preflight diagnostics for a pgbus deployment — the single command that
-  # answers "is this environment healthy enough to run?". Runs twelve checks and
+  # answers "is this environment healthy enough to run?". Runs fourteen checks and
   # returns a machine-readable result plus a human report, so `pgbus doctor`
   # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
   # 1 on any failure).
@@ -36,13 +36,15 @@ module Pgbus
       "Database" => :check_database,
       "PGMQ schema" => :check_pgmq_schema,
       "Queues" => :check_queues,
+      "Queue name case" => :check_queue_name_case,
       "LISTEN/NOTIFY" => :check_notify,
       "Process liveness" => :check_processes,
       "GlobalID allowlist" => :check_allowed_global_id_models,
       "Broadcast queue" => :check_broadcast_queue,
       "Primary affinity" => :check_primary,
       "Dedicated connections" => :check_dedicated_connections,
-      "Connection budget" => :check_connection_budget
+      "Connection budget" => :check_connection_budget,
+      "Completion commit" => :check_completion_commit
     }.freeze
 
     # Process liveness reads the pgbus_processes table (via HealthAnalyzer), so
@@ -128,6 +130,7 @@ module Pgbus
         resolved_pool_size: safe { @config.resolved_pool_size },
         listen_notify: @config.listen_notify,
         roles: @config.roles || "all",
+        completion_commit: @config.completion_synchronous_commit ? "sync" : "async",
         capsules: capsule_summary,
         database_url: redacted_database_url,
         connection_params: redacted_connection_params
@@ -252,6 +255,30 @@ module Pgbus
       Check.new(name: "Queues", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # How many mixed-case queue names the queue-name case check lists.
+    CASE_NAMES_SHOWN = 5
+    private_constant :CASE_NAMES_SHOWN
+
+    # 4b. Queue-name case (issue #633). PGMQ spells every queue table in lower
+    # case, and pgbus now spells every queue name that way; a pgmq.meta row an
+    # older pgbus created as "pgbus_Orders" shares pgmq.q_pgbus_orders with the
+    # current spelling. Its messages are reachable, so this warns rather than
+    # fails: the dashboard lists the queue twice until the fold migration runs.
+    def check_queue_name_case
+      names = @client.mixed_case_queue_names
+      return Check.new(name: "Queue name case", status: :ok, detail: "every queue is spelled in lower case") if names.empty?
+
+      shown = names.first(CASE_NAMES_SHOWN).join(", ")
+      shown += ", …" if names.size > CASE_NAMES_SHOWN
+      Check.new(name: "Queue name case", status: :warn,
+                detail: "#{names.size} queue(s) in pgmq.meta spelled in mixed case (#{shown}); their tables are " \
+                        "lower case and pgbus now uses that spelling — once every process runs this pgbus, run " \
+                        "`rails generate pgbus:fold_queue_name_case` and migrate " \
+                        "(`rake pgbus:queues:fold_case` once that migration has run)")
+    rescue StandardError => e
+      Check.new(name: "Queue name case", status: :warn, detail: "could not read pgmq.meta (#{e.class}: #{e.message})")
+    end
+
     # 5. LISTEN/NOTIFY — when configured on, every configured queue should carry
     # the insert-NOTIFY trigger. A missing trigger is a warning, not a failure:
     # pgbus still works (it falls back to polling), it just loses instant wakeup.
@@ -395,6 +422,32 @@ module Pgbus
       Check.new(name: "Dedicated connections", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # config.completion_synchronous_commit (issue #619): informational, except
+    # that false does nothing with native_statements off or on ActiveRecord's
+    # shared connection, which warns.
+    def check_completion_commit
+      return Check.new(name: "Completion commit", status: :ok, detail: "synchronous (default)") if
+        @config.completion_synchronous_commit
+
+      unless @config.native_statements
+        return Check.new(name: "Completion commit", status: :warn,
+                         detail: "completion_synchronous_commit = false has no effect: completions run through " \
+                                 "pgmq's functions (native_statements = false)")
+      end
+
+      if @client.respond_to?(:shared_connection?) && @client.shared_connection?
+        return Check.new(name: "Completion commit", status: :warn,
+                         detail: "completion_synchronous_commit = false has no effect: pgbus shares ActiveRecord's " \
+                                 "connection (connection_params Proc); give pgbus its own connections to use it")
+      end
+
+      Check.new(name: "Completion commit", status: :ok,
+                detail: "asynchronous: completions commit with synchronous_commit off; a Postgres server crash can " \
+                        "lose the last completions, whose jobs run again after visibility_timeout")
+    rescue StandardError => e
+      Check.new(name: "Completion commit", status: :warn, detail: "#{e.class}: #{e.message}")
+    end
+
     # How many direct LISTEN connections this config pins at steady state
     # (issue #381) — informational (always :ok) so operators can do capacity
     # math on the pooler's direct-connection budget from the doctor output.

data/lib/pgbus/failed_event_recorder.rb

@@ -85,11 +85,14 @@ module Pgbus
       # queue is dropped: PGMQ restarts msg_ids on recreate, so a surviving
       # row would aim the dashboard's retry/discard at an unrelated message.
       # Queue names are validated word characters, so the array literal is safe.
+      # Matched in any case (issue #633): the dropped queue's name is lower
+      # case, while a row may carry the executor's configured spelling
+      # ("Critical") or a physical name from before #633.
       def clear_queue!(queue_names)
         connection.exec_delete(
-          "DELETE FROM pgbus_failed_events WHERE queue_name = ANY($1::text[])",
+          "DELETE FROM pgbus_failed_events WHERE lower(queue_name) = ANY($1::text[])",
           "FailedEvent Clear Queue",
-          ["{#{queue_names.join(",")}}"]
+          ["{#{queue_names.map(&:downcase).join(",")}}"]
         )
       rescue StandardError => e
         Pgbus.logger.error do

data/lib/pgbus/generators/migration_detector.rb

@@ -102,7 +102,8 @@ module Pgbus
         add_batch_executions: "pgbus:add_batch_executions",
         add_batch_callback_jobs: "pgbus:add_batch_callback_jobs",
         tune_autovacuum: "pgbus:tune_autovacuum",
-        tune_fillfactor: "pgbus:tune_fillfactor"
+        tune_fillfactor: "pgbus:tune_fillfactor",
+        fold_queue_name_case: "pgbus:fold_queue_name_case"
       }.freeze
 
       # Human-friendly description of each migration for the generator
@@ -128,9 +129,15 @@ module Pgbus
         add_batch_executions: "batch execution-row tracking (self-healing completion, on_failure rename)",
         add_batch_callback_jobs: "batch callback-job columns (configured ActiveJob instances as batch callbacks)",
         tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
-        tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
+        tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)",
+        fold_queue_name_case: "lower-case spelling for queues created in mixed case (PGMQ's table names are lower case)"
       }.freeze
 
+      # A pgbus pgmq.meta row ($1: the lower-case "<queue_prefix>_") spelled
+      # with an upper-case letter (issue #633).
+      MIXED_CASE_QUEUE_SQL = "SELECT 1 FROM pgmq.meta WHERE queue_name <> lower(queue_name) " \
+                             "AND left(lower(queue_name), length($1)) = $1 LIMIT 1"
+
       def initialize(connection)
         @connection = connection
       end
@@ -143,6 +150,9 @@ module Pgbus
         return [FRESH_INSTALL] if fresh_install?
 
         [
+          # First: the tuning migrations below build table names from
+          # pgmq.meta, which a mixed-case row spells unlike its table.
+          *queue_name_case_migrations,
           *uniqueness_key_migrations,
           *job_stats_migrations,
           *stream_stats_migrations,
@@ -328,6 +338,23 @@ module Pgbus
         [:tune_autovacuum]
       end
 
+      # Issue #633: a queue an older pgbus created in mixed case shares its
+      # lower-case table with the spelling pgbus now uses. An unreadable
+      # pgmq.meta queues nothing: the doctor's "Queue name case" check says why.
+      def queue_name_case_migrations
+        return [] unless pgmq_schema_exists?
+        return [] unless mixed_case_queue?
+
+        [:fold_queue_name_case]
+      end
+
+      def mixed_case_queue?
+        prefix = "#{Pgbus.configuration.queue_prefix.to_s.downcase}_"
+        connection.select_value(MIXED_CASE_QUEUE_SQL.gsub("$1", connection.quote(prefix))).present?
+      rescue StandardError
+        false
+      end
+
       # Fillfactor tuning: check if any PGMQ queue table already has
       # fillfactor applied. If not, queue the migration.
       def fillfactor_migrations

data/lib/pgbus/instrumentation.rb

@@ -16,7 +16,22 @@ module Pgbus
   #   pgbus.job_completed          — job archived successfully
   #   pgbus.job_failed             — job raised; carries :exception_object
   #   pgbus.job_dead_lettered      — job exceeded max_retries and was DLQ-routed;
-  #                                  :error is the last recorded error class (or nil)
+  #                                  :error is the last recorded error class (or nil);
+  #                                  :reason is max_retries_exceeded, or uniqueness_conflict
+  #                                  for a :while_executing copy with no failed attempt whose
+  #                                  key's row is not its own (skipped while another message
+  #                                  held the key); also uniqueness_conflict when that row
+  #                                  lookup itself fails
+  #   pgbus.job_skipped            — a :while_executing copy was read while another
+  #                                  message held its key and left for a later delivery
+  #                                  (on_conflict :reject or :log)
+  #                                  payload: queue, job_class, job_id, provider_job_id,
+  #                                  msg_id, read_ct, on_conflict, vt (seconds until it
+  #                                  is delivered again)
+  #   pgbus.job_discarded          — a copy was completed without running
+  #                                  payload: queue, job_class, job_id, provider_job_id,
+  #                                  msg_id, reason ("uniqueness": a :while_executing copy
+  #                                  under on_conflict: :discard)
   #   pgbus.job_visibility_extended — heartbeat re-armed a running job's visibility timeout
   #                                  payload: queue, job_class, msg_id, vt, extensions
   #   pgbus.event_processed        — event handler succeeded

data/lib/pgbus/metrics/subscriber.rb

@@ -60,6 +60,8 @@ module Pgbus
             subscribe("pgbus.job_completed") { |event| on_job_completed(event) },
             subscribe("pgbus.job_failed") { |event| on_job_failed(event) },
             subscribe("pgbus.job_dead_lettered") { |event| on_job_dead_lettered(event) },
+            subscribe("pgbus.job_skipped") { |event| on_job_skipped(event) },
+            subscribe("pgbus.job_discarded") { |event| on_job_discarded(event) },
             subscribe("pgbus.job_visibility_extended") { |event| on_job_visibility_extended(event) },
             subscribe("pgbus.event_processed") { |event| on_event_processed(event) },
             subscribe("pgbus.event_failed") { |event| on_event_failed(event) },
@@ -121,11 +123,35 @@ module Pgbus
           )
         end
 
+        # reason: max_retries_exceeded, or uniqueness_conflict for a
+        # :while_executing duplicate skipped until it ran out of reads (#629).
         def on_job_dead_lettered(event)
           payload = event.payload
           backend.increment(
             "#{METRIC_PREFIX}queue_job_count", 1,
-            compact(queue: payload[:queue], job_class: payload[:job_class], status: "dead_lettered")
+            compact(queue: payload[:queue], job_class: payload[:job_class], status: "dead_lettered",
+                    reason: payload[:reason])
+          )
+        end
+
+        # A :while_executing duplicate left for a later delivery because
+        # another message held its key (issue #629): counted per skip, so one
+        # copy waiting out a long holder counts several times.
+        def on_job_skipped(event)
+          payload = event.payload
+          backend.increment(
+            "#{METRIC_PREFIX}queue_job_count", 1,
+            compact(queue: payload[:queue], job_class: payload[:job_class], status: "skipped", reason: "uniqueness")
+          )
+        end
+
+        # A :while_executing duplicate dropped under on_conflict: :discard.
+        def on_job_discarded(event)
+          payload = event.payload
+          backend.increment(
+            "#{METRIC_PREFIX}queue_job_count", 1,
+            compact(queue: payload[:queue], job_class: payload[:job_class], status: "discarded",
+                    reason: payload[:reason])
           )
         end
 

data/lib/pgbus/process/completer.rb

@@ -94,7 +94,8 @@ module Pgbus
         return waiter.value if waiter
 
         # Stopped: complete on the caller's thread, with the same results.
-        @client.public_send(@batch_op, queue, [msg_id], prefixed: false).empty? ? :already_archived : :archived
+        done = @client.public_send(@batch_op, queue, [msg_id], prefixed: false, job_completion: true)
+        done.empty? ? :already_archived : :archived
       end
 
       # Flushes whatever is pending, then joins the flusher. Past timeout the
@@ -157,7 +158,8 @@ module Pgbus
       # is absent. A duplicated id (the same message held by two threads after
       # a redelivery) is archived once, so only its first waiter gets :archived.
       def flush_slice(queue, slice)
-        archived = @client.public_send(@batch_op, queue, slice.map(&:first).uniq, prefixed: false).to_set(&:to_i)
+        archived = @client.public_send(@batch_op, queue, slice.map(&:first).uniq, prefixed: false, job_completion: true)
+                          .to_set(&:to_i)
         slice.each { |msg_id, waiter| waiter.resolve(archived.delete?(msg_id) ? :archived : :already_archived) }
       rescue Exception => e # rubocop:disable Lint/RescueException -- delivered to the waiters, never swallowed
         log_flush_failure(queue, slice, e) unless e.is_a?(StandardError)

data/lib/pgbus/process/worker.rb

@@ -194,6 +194,7 @@ module Pgbus
       POOL_TERMINATION_WAIT = 5
 
       def run
+        quiet_active_job_logs
         setup_signals
         start_heartbeat
         resolve_wildcard_queues
@@ -282,6 +283,18 @@ module Pgbus
 
       private
 
+      # config.quiet_active_job_logs (issue #618): only worker processes perform
+      # jobs, so only they drop the per-job "Performing …" / "Performed …"
+      # lines. ActiveJob::LogSubscriber attaches when active_job/base loads,
+      # which an app with no job class to eager-load has not done yet, so load
+      # it first (defined? does not trigger ActiveJob's autoload of Base).
+      def quiet_active_job_logs
+        return unless config.quiet_active_job_logs && defined?(::ActiveJob::Base)
+
+        require "active_job/base"
+        Pgbus::ActiveJob::QuietLogs.apply!
+      end
+
       # One loop step (issue #486): feed buffered claims to free slots, read
       # the deficit (free slots + read_ahead - buffered, capped by
       # prefetch_limit), feed again. With read_ahead 0 the buffer never
@@ -510,11 +523,18 @@ module Pgbus
       def process_message(message, queue_name, source_queue: nil)
         result = @executor.execute(message, queue_name, source_queue: source_queue)
         @jobs_processed.increment
-        @rate_counter.increment(:processed)
-        if result == :failed
+        # A skipped uniqueness duplicate comes back later: counting it now
+        # would count one job twice (issue #629).
+        @rate_counter.increment(:processed) unless result == :skipped
+        case result
+        when :failed
           @jobs_failed.increment
           @rate_counter.increment(:failed)
           @circuit_breaker.record_failure(queue_name)
+        when :skipped, :discarded
+          # No job ran: neither a failure nor a success that would wipe the
+          # failure streak of a queue whose real jobs keep failing.
+          nil
         else
           @circuit_breaker.record_success(queue_name)
         end
@@ -569,7 +589,12 @@ module Pgbus
         prefix = "#{config.queue_prefix}_"
         if (match = MISSING_QUEUE_REGEX.match(error.message))
           physical_name = match[1]
-          logical_name = physical_name.delete_prefix(prefix)
+          # Postgres names the table as PGMQ spells it (lower case, issue #633;
+          # separators normalized), so find the queue as configured.
+          # A priority sub-queue (_pN) belongs to its base queue.
+          logical_name = @queues.find { |q| config.priority_queue_names(q).include?(physical_name) } ||
+                         @queues.find { |q| config.queue_name(q) == physical_name } ||
+                         physical_name.delete_prefix(prefix)
           if @queues.delete(logical_name)
             Pgbus.logger.warn { "[Pgbus] Evicted deleted queue '#{logical_name}' (#{physical_name}) from worker" }
           end

data/lib/pgbus/queue_name_fold.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Issue #633 upgrade path. PGMQ lower-cases its table names
+  # (pgmq.format_table_name), so a queue an older pgbus created as
+  # "pgbus_Orders" lives in pgmq.q_pgbus_orders while pgmq.meta records
+  # "pgbus_Orders". pgbus now spells every queue in lower case; this renames
+  # the old rows to match their tables.
+  #
+  # Only rows change. The queue tables are shared by both spellings, so nothing
+  # here drops, renames or copies a table: dropping either spelling's queue
+  # through PGMQ would remove the shared table.
+  #
+  # Run by the pgbus:fold_queue_name_case migration and by
+  # `rake pgbus:queues:fold_case` (for a row an older process recreated after
+  # the migration ran). Idempotent. Takes an ActiveRecord connection and
+  # folds pgbus's queues only (those named "<prefix>_…" in any case), so
+  # another PGMQ user of the same schema keeps its spelling and its NOTIFY
+  # channel.
+  module QueueNameFold
+    module_function
+
+    def run!(connection, prefix: Pgbus.configuration.queue_prefix)
+      fold_pgmq_meta(connection, "#{prefix.to_s.downcase}_")
+      fold_unique_column(connection, :pgbus_stream_queues, prefer: "")
+      fold_unique_column(connection, :pgbus_queue_states, prefer: "paused DESC,")
+      fold_column(connection, :pgbus_uniqueness_keys, :queue_name)
+      fold_failed_event_source_queues(connection)
+    end
+
+    # One mixed-case pgmq.meta row at a time: add the lower-case row, move its
+    # topic bindings, delete the old row (and its throttle and binding rows),
+    # then re-arm the insert-NOTIFY trigger under the new name. PGMQ 1.13.1's
+    # trigger NOTIFYs on the channel of the name it was armed with, which
+    # listeners now spell in lower case. Where both spellings exist, the
+    # lower-case row's throttle wins.
+    def fold_pgmq_meta(connection, own_prefix)
+      prefix = connection.quote(own_prefix)
+      connection.execute(<<~SQL)
+        DO $$
+        DECLARE
+          q RECORD;
+          folded TEXT;
+          throttle INTEGER;
+          has_throttle BOOLEAN := to_regclass('pgmq.notify_insert_throttle') IS NOT NULL;
+          has_bindings BOOLEAN := to_regclass('pgmq.topic_bindings') IS NOT NULL;
+        BEGIN
+          FOR q IN
+            SELECT queue_name, is_partitioned, is_unlogged, created_at
+            FROM pgmq.meta
+            WHERE queue_name <> lower(queue_name)
+              AND left(lower(queue_name), length(#{prefix})) = #{prefix}
+            ORDER BY queue_name
+          LOOP
+            folded := lower(q.queue_name);
+
+            INSERT INTO pgmq.meta (queue_name, is_partitioned, is_unlogged, created_at)
+            VALUES (folded, q.is_partitioned, q.is_unlogged, q.created_at)
+            ON CONFLICT DO NOTHING;
+
+            throttle := NULL;
+            IF has_throttle THEN
+              SELECT COALESCE(
+                (SELECT throttle_interval_ms FROM pgmq.notify_insert_throttle WHERE queue_name = folded),
+                (SELECT throttle_interval_ms FROM pgmq.notify_insert_throttle WHERE queue_name = q.queue_name)
+              ) INTO throttle;
+              DELETE FROM pgmq.notify_insert_throttle WHERE queue_name = q.queue_name;
+            END IF;
+
+            IF has_bindings THEN
+              INSERT INTO pgmq.topic_bindings (pattern, queue_name, bound_at)
+              SELECT pattern, folded, bound_at FROM pgmq.topic_bindings WHERE queue_name = q.queue_name
+              ON CONFLICT DO NOTHING;
+              DELETE FROM pgmq.topic_bindings WHERE queue_name = q.queue_name;
+            END IF;
+
+            DELETE FROM pgmq.meta WHERE queue_name = q.queue_name;
+
+            IF throttle IS NOT NULL THEN
+              PERFORM pgmq.enable_notify_insert(folded, throttle);
+            END IF;
+          END LOOP;
+        END $$;
+      SQL
+    end
+
+    # A column with a unique index: keep one row per lower-case name (the
+    # `prefer` order first, then the row already in lower case, then the
+    # oldest), delete the rest, then lower-case what is left.
+    def fold_unique_column(connection, table, prefer:)
+      return unless connection.table_exists?(table)
+
+      connection.execute(<<~SQL)
+        DELETE FROM #{table} WHERE id IN (
+          SELECT id FROM (
+            SELECT id, row_number() OVER (
+              PARTITION BY lower(queue_name)
+              ORDER BY #{prefer} (queue_name = lower(queue_name)) DESC, id
+            ) AS rank
+            FROM #{table}
+            WHERE lower(queue_name) IN (SELECT lower(queue_name) FROM #{table} WHERE queue_name <> lower(queue_name))
+          ) ranked
+          WHERE rank > 1
+        )
+      SQL
+      fold_column(connection, table, :queue_name)
+    end
+
+    def fold_column(connection, table, column)
+      return unless connection.table_exists?(table) && connection.column_exists?(table, column)
+
+      connection.execute("UPDATE #{table} SET #{column} = lower(#{column}) WHERE #{column} <> lower(#{column})")
+    end
+
+    # source_queue is the physical queue a failure was read from, now spelled in
+    # lower case. queue_name is the executor's logical name, as configured, and
+    # stays. A message that failed under both spellings (before and after the
+    # deploy) has two rows: one per (queue_name, msg_id, folded source) stays,
+    # the lower-case one if there is one (written after the deploy), else the
+    # newest, so the (queue_name, msg_id, source_queue) unique index holds.
+    def fold_failed_event_source_queues(connection)
+      return unless connection.table_exists?(:pgbus_failed_events) && connection.column_exists?(:pgbus_failed_events, :source_queue)
+
+      connection.execute(<<~SQL)
+        DELETE FROM pgbus_failed_events WHERE id IN (
+          SELECT id FROM (
+            SELECT id, row_number() OVER (
+              PARTITION BY queue_name, msg_id, lower(source_queue)
+              ORDER BY (source_queue = lower(source_queue)) DESC, id DESC
+            ) AS rank
+            FROM pgbus_failed_events
+            WHERE (queue_name, msg_id, lower(source_queue)) IN (
+              SELECT queue_name, msg_id, lower(source_queue) FROM pgbus_failed_events
+              WHERE source_queue <> lower(source_queue)
+            )
+          ) ranked
+          WHERE rank > 1
+        )
+      SQL
+      fold_column(connection, :pgbus_failed_events, :source_queue)
+    end
+
+    private_class_method :fold_pgmq_meta, :fold_unique_column, :fold_column, :fold_failed_event_source_queues
+  end
+end

data/lib/pgbus/queue_name_validator.rb

@@ -9,7 +9,9 @@ module Pgbus
   module QueueNameValidator
     # PostgreSQL's NAMEDATALEN caps identifiers at 63 bytes, but the
     # effective limit is tighter: pgmq-ruby (our transport gem) rejects
-    # any queue name with `length >= 48` in `PGMQ::Client#validate_queue_name!`.
+    # any queue name with `length >= PGMQ::QueueName::MAX_LENGTH` (48) in
+    # `PGMQ::QueueName.validate!`, whose error has said "maximum length of
+    # 47 characters" since pgmq-ruby 0.8.2 (48 before).
     # That leaves an actual usable ceiling of 47 characters for the
     # fully-prefixed name (`<queue_prefix>_<logical_name>`), which is what
     # this constant expresses. pgmq-ruby picked 48 to leave headroom for
@@ -26,6 +28,10 @@ module Pgbus
     # Only alphanumeric characters and underscores are allowed.
     VALID_QUEUE_NAME_PATTERN = /\A[a-zA-Z0-9_]+\z/
 
+    # A valid name already in lower case: what normalize returns.
+    CANONICAL_QUEUE_NAME = /\A[a-z0-9_]+\z/
+    private_constant :CANONICAL_QUEUE_NAME
+
     module_function
 
     # Validates a queue name for safe SQL identifier use.
@@ -58,14 +64,26 @@ module Pgbus
     # (`Pgbus.stream([user, :notifications])` → `"user_gid:notifications"`),
     # so they must map to a safe character rather than be stripped —
     # otherwise `"a:b"` and `"ab"` would collide on the same queue.
+    #
+    # The result is lower case (issue #633): PGMQ lower-cases its table
+    # names (`pgmq.format_table_name`), so "Orders" and "orders" share
+    # `pgmq.q_orders` while `pgmq.meta` records each spelling as its own
+    # queue. Spelling every name the way its table is gives one name per
+    # table. `validate!` and `sanitize!` keep case: they also run on names
+    # read back from `pgmq.meta`, which an install from before #633 may
+    # still hold in mixed case (`rails generate pgbus:fold_queue_name_case`).
     def normalize(name)
       name = name.to_s
-      return validate!(name) if VALID_QUEUE_NAME_PATTERN.match?(name)
+      # Every enqueue and read names its queue through here: a name already
+      # spelled as its table costs one scan and no allocation.
+      return name if name.length <= MAX_QUEUE_NAME_LENGTH && CANONICAL_QUEUE_NAME.match?(name)
+      return validate!(name).downcase if VALID_QUEUE_NAME_PATTERN.match?(name)
 
       normalized = name.gsub(/[-.:]/, "_")          # hyphens/dots/colons → underscores
                        .gsub(/[^a-zA-Z0-9_]/, "")   # strip remaining invalid chars
                        .gsub(/_+/, "_")              # collapse consecutive underscores
                        .gsub(/\A_|_\z/, "")          # strip leading/trailing underscores
+      normalized.downcase!
       validate!(normalized)
       normalized
     end