pgbus 0.21.4 → 0.23.0

data/lib/pgbus/event_bus/handler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Pgbus
   module EventBus
     class Handler

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Batched completion (issue #606, `config.completion_batching`): one per
+    # worker, it archives the messages of jobs that finish close together with
+    # one `archive_batch` per physical queue instead of one `pgmq.archive` each.
+    #
+    # There is no timer. An idle completer flushes a lone id at once; ids that
+    # arrive while a flush is in flight wait for the next one, so under load a
+    # batch is "what arrived during the previous round trip".
+    # `batch_size` only caps the ids per statement.
+    #
+    # The job thread waits for its own result (`complete` blocks), so the
+    # executor's post-archive sequence runs on it as before. Threads only: a
+    # blocking wait would stall an Async reactor (Configuration#validate!).
+    #
+    # completed_jobs: :delete (the config setting, issue #607) flushes with
+    # `delete_batch` instead; the results keep their names, so :archived
+    # means "completed" and :already_archived "already gone".
+    class Completer
+      # Raised on a waiting job thread whose flush can no longer happen: the
+      # flusher was stopped past its join budget, or died.
+      class Stopped < Pgbus::Error; end
+
+      # One job thread's wait for its id's result.
+      class Waiter
+        def initialize
+          @mutex = Mutex.new
+          @done = ConditionVariable.new
+          @state = nil
+          @value = nil
+        end
+
+        def resolve(value) = settle(:value, value)
+
+        def fail(error) = settle(:error, error)
+
+        def value
+          @mutex.synchronize do
+            @done.wait(@mutex) until @state
+            raise @value if @state == :error
+
+            @value
+          end
+        end
+
+        private
+
+        # First settle wins: a waiter already served is not failed again by
+        # the flusher's last-resort cleanup.
+        def settle(state, value)
+          @mutex.synchronize do
+            next if @state
+
+            @state = state
+            @value = value
+            @done.broadcast
+          end
+        end
+      end
+
+      BATCH_OPS = { archive: :archive_batch, delete: :delete_batch }.freeze
+
+      def initialize(client:, batch_size:, completed_jobs: :archive)
+        @batch_op = BATCH_OPS.fetch(completed_jobs) do
+          raise ArgumentError, "completed_jobs must be :archive or :delete (got #{completed_jobs.inspect})"
+        end
+        @client = client
+        @batch_size = batch_size
+        @mutex = Mutex.new
+        @wake = ConditionVariable.new
+        @pending = {}
+        @taken = nil
+        @stopping = false
+        # Owned by this completer: one per worker, built with it. #stop asks
+        # it to drain and exit, then joins it (Worker#shutdown, #immediate_shutdown).
+        @thread = Thread.new { run } # rubocop:disable ThreadSafety/NewThread
+        @thread.name = "pgbus-completer"
+      end
+
+      # Archives msg_id from the physical (already prefixed) queue and returns
+      # :archived, or :already_archived when the message was gone (another
+      # worker archived it). Raises the flush's exception on this thread.
+      def complete(queue, msg_id)
+        waiter = @mutex.synchronize do
+          next if @stopping
+
+          entry = Waiter.new
+          (@pending[queue] ||= []) << [msg_id, entry]
+          @wake.signal
+          entry
+        end
+        return waiter.value if waiter
+
+        # Stopped: complete on the caller's thread, with the same results.
+        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
+      # flusher is killed and every waiter it had not served raises Stopped.
+      # Later `complete` calls archive on their own thread. Idempotent.
+      def stop(timeout: nil)
+        @mutex.synchronize do
+          @stopping = true
+          @wake.signal
+        end
+        return if @thread.join(timeout)
+
+        @thread.kill
+        @thread.join
+      end
+
+      def alive? = @thread.alive?
+
+      # Ids waiting for the next flush (test and introspection seam).
+      def pending_count
+        @mutex.synchronize { @pending.sum { |_queue, entries| entries.size } }
+      end
+
+      # True while a flush is running (test and introspection seam).
+      def flushing?
+        @mutex.synchronize { !@taken.nil? }
+      end
+
+      private
+
+      def run
+        while (batch = take)
+          flush(batch)
+          @mutex.synchronize { @taken = nil }
+        end
+      ensure
+        fail_unserved
+      end
+
+      # Waits for pending ids and takes all of them; nil once stopping with
+      # nothing left.
+      def take
+        @mutex.synchronize do
+          @wake.wait(@mutex) while @pending.empty? && !@stopping
+          next if @pending.empty?
+
+          @taken = @pending
+          @pending = {}
+          @taken
+        end
+      end
+
+      def flush(batch)
+        batch.each do |queue, entries|
+          entries.each_slice(@batch_size) { |slice| flush_slice(queue, slice) }
+        end
+      end
+
+      # pgmq returns one row per archived id (as a String); an id already gone
+      # 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, 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)
+        slice.map(&:last).each { |waiter| waiter.fail(e) }
+      end
+
+      def log_flush_failure(queue, slice, error)
+        Pgbus.logger.error do
+          "[Pgbus::Completer] #{@batch_op} on #{queue} (#{slice.size} ids) raised #{error.class}: #{error.message}"
+        end
+      end
+
+      # The flusher is exiting: nothing may be left waiting on it.
+      def fail_unserved
+        leftovers = @mutex.synchronize do
+          entries = [@taken, @pending].compact.flat_map(&:values).flatten(1)
+          @taken = nil
+          @pending = {}
+          @stopping = true
+          entries
+        end
+        error = Stopped.new("the completer stopped before archiving this message")
+        leftovers.map(&:last).each { |waiter| waiter.fail(error) }
+      end
+    end
+  end
+end

data/lib/pgbus/process/consumer.rb

@@ -264,7 +264,7 @@ module Pgbus
           dispatch(handlers, message, queue_name)
         end
 
-        Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
+        archive_handled(queue_name, message)
         # A redelivery that succeeds leaves no stale failure behind. First
         # deliveries never had one: no query on the hot path (#484's gate).
         if message.read_ct.to_i > 1
@@ -367,6 +367,20 @@ module Pgbus
       # as retrying with its error. No ErrorReporter call: Handler#process!
       # already instruments pgbus.event_failed, which feeds the reporters.
       # A handler queue has no priority sub-queues: its one table is the source.
+      # The handlers ran. An archive whose reply was lost after it may have
+      # committed, and whose re-run found the message gone (issue #607
+      # review), leaves nothing to retry: the message is handled.
+      def archive_handled(queue_name, message)
+        Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
+      rescue StandardError => e # pgmq loads lazily: completion_lost? checks the class
+        raise unless Client::NativeStatements.completion_lost?(e)
+
+        Pgbus.logger.warn do
+          "[Pgbus] Consumer archive of #{message.msg_id} on #{queue_name} lost its reply and the message is gone: " \
+            "counted as handled (#{e.message})"
+        end
+      end
+
       def record_failed_event(message, queue_name, error)
         FailedEventRecorder.record!(
           queue_name: queue_name, msg_id: message.msg_id.to_i, source_queue: config.queue_name(queue_name),

data/lib/pgbus/process/worker.rb

@@ -62,6 +62,12 @@ module Pgbus
                 "fair_share and group_mode are mutually exclusive — this worker has group_mode " \
                 "#{(@group_mode || config.group_mode).inspect} while config.fair_share is set"
         end
+        # The completer blocks a job thread on its flush, which would stall an
+        # Async reactor (issue #606); the mode can arrive here without validate!.
+        if config.completion_batching && @execution_mode == :async
+          raise Pgbus::ConfigurationError,
+                "completion_batching supports execution_mode :threads only; this worker runs :async"
+        end
         @single_active_consumer = single_active_consumer
         @consumer_priority = consumer_priority
         @lifecycle = Lifecycle.new
@@ -94,7 +100,16 @@ module Pgbus
           else
             stat_buffer
           end
-        @executor = Pgbus::ActiveJob::Executor.new(stat_buffer: @stat_buffer)
+        # One per worker when config.completion_batching (issue #606): archives
+        # the jobs that finish close together in one archive_batch, or deletes
+        # them with delete_batch under config.completed_jobs = :delete (#607).
+        @completer = if config.completion_batching
+                       Completer.new(client: Pgbus.client, batch_size: config.completion_batch_size,
+                                     completed_jobs: config.completed_jobs)
+                     end
+        # The worker's config, so the executor and the completer read one
+        # completed_jobs (issue #607).
+        @executor = Pgbus::ActiveJob::Executor.new(config: config, stat_buffer: @stat_buffer, completer: @completer)
         @wake_signal = wake_signal || WakeSignal.new
         @pool = ExecutionPools.build(
           mode: @execution_mode,
@@ -179,6 +194,7 @@ module Pgbus
       POOL_TERMINATION_WAIT = 5
 
       def run
+        quiet_active_job_logs
         setup_signals
         start_heartbeat
         resolve_wildcard_queues
@@ -239,6 +255,13 @@ module Pgbus
         Pgbus.stopping = true
         @lifecycle.transition_to!(:stopped)
         @wake_signal.notify!
+        # Before the pool: a job thread killed while it waits on a flush would
+        # skip its signals while the flush still commits (archived, never
+        # signalled). Stopping first resolves every waiter; a job that finishes
+        # inside the grace then archives on its own thread. Bounded by the same
+        # grace: a flush wedged on a hung Postgres is abandoned, and its jobs
+        # fail with Completer::Stopped and re-run after visibility_timeout.
+        @completer&.stop(timeout: config.immediate_shutdown_grace)
         ExecutionPools.terminate(@pool, grace: config.immediate_shutdown_grace)
       end
 
@@ -260,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
@@ -488,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
@@ -547,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
@@ -927,7 +974,13 @@ module Pgbus
         # config.drain_timeout for in-flight jobs. A job still running here has
         # proven it won't finish; waiting another full window would push the
         # worker past the supervisor's shutdown_timeout deadline (issue #386).
+        residual_deadline = monotonic_now + POOL_TERMINATION_WAIT
         @pool.wait_for_termination(POOL_TERMINATION_WAIT)
+        # After the pool: every waiter is a job thread, so the drain already
+        # flushed theirs; this flushes any left and joins the flusher. It shares
+        # the pool's residual budget rather than adding its own, so shutdown
+        # stays inside the supervisor's drain_timeout + 5 default deadline.
+        @completer&.stop(timeout: [residual_deadline - monotonic_now, 0].max)
         VisibilityHeartbeat.stop
         @stat_buffer&.stop
         @queue_lock&.unlock_all

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