pgbus 0.21.4 → 0.23.0

data/app/models/pgbus/queue_state.rb

@@ -4,6 +4,12 @@ module Pgbus
   class QueueState < BusRecord
     self.table_name = "pgbus_queue_states"
 
+    # One row per queue whatever the spelling (issue #633): the dashboard
+    # names a queue from its pgmq.meta row, which PGMQ's lower-case table
+    # names make lower case, while a worker names it as configured
+    # ("Critical"). Applies to writes and to find_by/where.
+    normalizes :queue_name, with: ->(name) { name.to_s.downcase }
+
     scope :paused, -> { where(paused: true) }
 
     def self.paused?(queue_name)

data/app/models/pgbus/uniqueness_key.rb

@@ -191,6 +191,17 @@ module Pgbus
       )
     end
 
+    # True when the key's row is bound to this message (queue + msg_id): its
+    # own attempt holds it, as a crashed attempt leaves it. The executor asks
+    # this when it dead-letters a :while_executing message that never failed
+    # (issue #629): a crash loop, not a uniqueness conflict.
+    def self.bound_to?(lock_key, queue_name:, msg_id:)
+      !connection.select_value(
+        "SELECT 1 FROM #{table_name} WHERE lock_key = $1 AND queue_name = $2 AND msg_id = $3 LIMIT 1",
+        "UniquenessKey Bound To", [lock_key, queue_name.to_s, msg_id.to_i]
+      ).nil?
+    end
+
     # Check if a key is currently locked.
     def self.locked?(lock_key)
       result = connection.select_value(

data/config/locales/da.yml

@@ -224,6 +224,7 @@ da:
         retried_before:
           one: Genforsøgt fra DLQ én gang før.
           other: Genforsøgt fra DLQ %{count} gange før.
+        uniqueness_conflict_html: Sprunget over ved alle %{attempts} læsninger (maks. %{max}), mens en anden kopi af jobbet holdt dets unikhedsnøgle — intet forsøg kørte
       show:
         back: Tilbage til DLQ
         context: Kontekst

data/config/locales/de.yml

@@ -224,6 +224,7 @@ de:
         retried_before:
           one: Schon einmal aus der DLQ wiederholt.
           other: Schon %{count}-mal aus der DLQ wiederholt.
+        uniqueness_conflict_html: Bei allen %{attempts} Lesevorgängen übersprungen (max. %{max}), weil eine andere Kopie des Jobs seinen Eindeutigkeitsschlüssel hielt — kein Versuch lief
       show:
         back: Zurück zur DLQ
         context: Kontext

data/config/locales/en.yml

@@ -224,6 +224,7 @@ en:
         retried_before:
           one: Retried from the DLQ once before.
           other: Retried from the DLQ %{count} times before.
+        uniqueness_conflict_html: Skipped on all %{attempts} reads (max %{max}) while another copy of the job held its uniqueness key — no attempt ran
       show:
         back: Back to DLQ
         context: Context

data/config/locales/es.yml

@@ -224,6 +224,7 @@ es:
         retried_before:
           one: Reintentado desde la DLQ una vez antes.
           other: Reintentado desde la DLQ %{count} veces antes.
+        uniqueness_conflict_html: Omitido en las %{attempts} lecturas (máx. %{max}) mientras otra copia del job tenía su clave de unicidad — no se ejecutó ningún intento
       show:
         back: Volver a DLQ
         context: Contexto

data/config/locales/fi.yml

@@ -224,6 +224,7 @@ fi:
         retried_before:
           one: Yritetty uudelleen DLQ:sta kerran aiemmin.
           other: Yritetty uudelleen DLQ:sta %{count} kertaa aiemmin.
+        uniqueness_conflict_html: Ohitettu kaikilla %{attempts} lukukerralla (enint. %{max}), koska työn toinen kopio piti sen yksilöllisyysavainta — yhtään yritystä ei ajettu
       show:
         back: Takaisin DLQ:hon
         context: Konteksti

data/config/locales/fr.yml

@@ -224,6 +224,7 @@ fr:
         retried_before:
           one: Déjà relancé depuis la DLQ une fois.
           other: Déjà relancé depuis la DLQ %{count} fois.
+        uniqueness_conflict_html: Ignoré à chacune des %{attempts} lectures (max %{max}) car une autre copie du job détenait sa clé d’unicité — aucune tentative n’a été exécutée
       show:
         back: Retour à la DLQ
         context: Contexte

data/config/locales/it.yml

@@ -224,6 +224,7 @@ it:
         retried_before:
           one: Già riprovato dalla DLQ una volta.
           other: Già riprovato dalla DLQ %{count} volte.
+        uniqueness_conflict_html: Saltato in tutte le %{attempts} letture (max %{max}) mentre un’altra copia del job deteneva la sua chiave di unicità — nessun tentativo eseguito
       show:
         back: Torna a DLQ
         context: Contesto

data/config/locales/ja.yml

@@ -224,6 +224,7 @@ ja:
         retried_before:
           one: 以前に DLQ から 1 回リトライされました。
           other: 以前に DLQ から %{count} 回リトライされました。
+        uniqueness_conflict_html: 別のコピーが一意性キーを保持していたため、%{attempts} 回の読み取りすべてでスキップされました(上限 %{max} 回) — 試行は一度も実行されていません
       show:
         back: DLQに戻る
         context: コンテキスト

data/config/locales/nb.yml

@@ -224,6 +224,7 @@ nb:
         retried_before:
           one: Forsøkt på nytt fra DLQ én gang før.
           other: Forsøkt på nytt fra DLQ %{count} ganger før.
+        uniqueness_conflict_html: Hoppet over ved alle %{attempts} lesinger (maks. %{max}) mens en annen kopi av jobben holdt unikhetsnøkkelen — ingen forsøk kjørte
       show:
         back: Tilbake til DLQ
         context: Kontekst

data/config/locales/nl.yml

@@ -224,6 +224,7 @@ nl:
         retried_before:
           one: Al eens eerder vanuit de DLQ opnieuw geprobeerd.
           other: Al %{count} keer eerder vanuit de DLQ opnieuw geprobeerd.
+        uniqueness_conflict_html: Bij alle %{attempts} keer lezen overgeslagen (max %{max}) omdat een andere kopie van de job de uniciteitssleutel had — geen poging uitgevoerd
       show:
         back: Terug naar DLQ
         context: Context

data/config/locales/pt.yml

@@ -224,6 +224,7 @@ pt:
         retried_before:
           one: Já reenviado da DLQ uma vez.
           other: Já reenviado da DLQ %{count} vezes.
+        uniqueness_conflict_html: Ignorado em todas as %{attempts} leituras (máx. %{max}) enquanto outra cópia do job detinha sua chave de unicidade — nenhuma tentativa foi executada
       show:
         back: Voltar para DLQ
         context: Contexto

data/config/locales/sv.yml

@@ -224,6 +224,7 @@ sv:
         retried_before:
           one: Omförsökt från DLQ en gång tidigare.
           other: Omförsökt från DLQ %{count} gånger tidigare.
+        uniqueness_conflict_html: Hoppades över vid alla %{attempts} läsningar (max %{max}) medan en annan kopia av jobbet höll dess unikhetsnyckel — inget försök kördes
       show:
         back: Tillbaka till DLQ
         context: Kontext

data/lib/generators/pgbus/fold_queue_name_case_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "migration_path"
+
+module Pgbus
+  module Generators
+    # Issue #633: PGMQ lower-cases its table names, so a queue pgbus created
+    # as "pgbus_Orders" before 0.23.0 lives in pgmq.q_pgbus_orders while
+    # pgmq.meta records the mixed-case spelling. pgbus now spells every queue
+    # in lower case; this migration brings an install's existing rows to that
+    # spelling. No table is dropped, renamed or copied.
+    class FoldQueueNameCaseGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationPath
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Spell existing PGMQ queues (pgmq.meta, NOTIFY triggers, pgbus's queue-name columns) in lower case, " \
+           "the way their tables are"
+
+      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 "fold_queue_name_case.rb.erb",
+                           File.join(pgbus_migrate_path, "fold_pgbus_queue_name_case.rb")
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus queue-name fold migration created!", :green
+        say ""
+        say "PGMQ spells every queue table in lower case. This migration renames the"
+        say "pgmq.meta rows (and NOTIFY triggers) of queues created with upper-case"
+        say "letters to the lower-case spelling their tables already use. Messages stay"
+        say "where they are."
+        say ""
+        say "Next steps:"
+        say "  1. Deploy pgbus 0.23.0+ everywhere first: an older process recreates its mixed-case row"
+        say "  2. Run: rails db:migrate#{migrate_command_suffix}"
+        say "  3. Check: rake pgbus:doctor (\"Queue name case\" is ok); if it still names a queue,"
+        say "     run: rake pgbus:queues:fold_case"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+class FoldPgbusQueueNameCase < ActiveRecord::Migration<%= migration_version %>
+  # Issue #633. PGMQ lower-cases its table names, so a queue created as
+  # "pgbus_Orders" lives in pgmq.q_pgbus_orders while pgmq.meta records
+  # "pgbus_Orders". Pgbus::QueueNameFold renames the old rows to the lower-case
+  # spelling pgbus now uses; it changes rows only, never a table.
+  def up
+    Pgbus::QueueNameFold.run!(connection)
+  end
+
+  # The original spellings are not kept: PGMQ never used them for a table.
+  def down; end
+end

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

@@ -25,8 +25,8 @@ class TunePgbusAutovacuum < ActiveRecord::Migration<%= migration_version %>
         q RECORD;
       BEGIN
         FOR q IN SELECT queue_name FROM pgmq.meta LOOP
-          EXECUTE format('ALTER TABLE pgmq.q_%I RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)', q.queue_name);
-          EXECUTE format('ALTER TABLE pgmq.a_%I RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)', q.queue_name);
+          EXECUTE format('ALTER TABLE pgmq.%I RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)', 'q_' || lower(q.queue_name));
+          EXECUTE format('ALTER TABLE pgmq.%I RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)', 'a_' || lower(q.queue_name));
         END LOOP;
       END $$;
     SQL

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

@@ -22,7 +22,7 @@ class TunePgbusFillfactor < ActiveRecord::Migration<%= migration_version %>
         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);
+          EXECUTE format('ALTER TABLE pgmq.%I RESET (fillfactor)', 'q_' || lower(q.queue_name));
         END LOOP;
       END $$;
     SQL

data/lib/pgbus/active_job/adapter.rb

@@ -215,7 +215,7 @@ module Pgbus
           return true
         when :discard
           Pgbus.logger.info { "[Pgbus] Discarding job #{active_job.class.name}: concurrency limit for #{key}" }
-          # The job will never run: roll back an :until_executed uniqueness lock
+          # The job will never run: roll back an enqueue-time uniqueness lock
           # acquired earlier in this enqueue (no executor will release it), and
           # uncount it from its batch so completion is not waited on forever.
           rollback_acquired_uniqueness_lock
@@ -226,7 +226,8 @@ module Pgbus
         false
       end
 
-      # Releases an :until_executed lock this enqueue acquired, if any.
+      # Releases an enqueue-time lock (:until_executed, :until_executing) this
+      # enqueue acquired, if any.
       # Used when the job is dropped before a message is sent (concurrency
       # :discard, or send_message raising) — otherwise the lock is orphaned
       # because no executor will ever release it.

data/lib/pgbus/active_job/executor.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
-require "time"
-
 module Pgbus
   module ActiveJob
     class Executor
       attr_reader :client, :config
 
-      def initialize(client: Pgbus.client, config: Pgbus.configuration, stat_buffer: nil)
+      # completer: the worker's Process::Completer when config.completion_batching
+      # is on (issue #606): complete_from goes through it instead of one
+      # archive_message per job. config.completed_jobs (issue #607) is read
+      # once here: :delete finishes a successful job with delete_message.
+      def initialize(client: Pgbus.client, config: Pgbus.configuration, stat_buffer: nil, completer: nil)
         @client = client
         @config = config
         @stat_buffer = stat_buffer
+        @completer = completer
+        @delete_completed = config.completed_jobs == :delete
+        @completed_word = @delete_completed ? "deleted" : "archived"
       end
 
       # Exceptions we never want to swallow — let the process die/signal propagate.
@@ -30,12 +35,16 @@ module Pgbus
           # it: the DLQ copy carries it in its headers (issue #495).
           last_error = FailedEventRecorder.last_error(queue_name: queue_name, msg_id: message.msg_id.to_i,
                                                       source_queue: physical_queue(queue_name, source_queue))
-          handle_dead_letter(message, queue_name, payload, source_queue: source_queue, last_error: last_error)
+          # Before the release below: the lookup asks whether the key's row is
+          # still this message's own (a crashed attempt's), see dead_letter_reason.
+          reason = dead_letter_reason(message, queue_name, payload, last_error)
+          handle_dead_letter(message, queue_name, payload, source_queue: source_queue, last_error: last_error,
+                                                           reason: reason)
           FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i,
                                      source_queue: physical_queue(queue_name, source_queue))
           signal_concurrency(payload)
           signal_batch_discarded(payload)
-          release_uniqueness_lock(Uniqueness.extract_key(payload), queue_name, message)
+          release_uniqueness_lock(Uniqueness.extract_key(payload), queue_name, message) if holds_uniqueness_row?(payload)
           record_stat(payload, queue_name, "dead_lettered", execution_start, message: message)
           instrument(
             "pgbus.job_dead_lettered",
@@ -45,7 +54,8 @@ module Pgbus
             provider_job_id: payload["provider_job_id"],
             read_ct: read_count,
             msg_id: message.msg_id.to_i,
-            error: last_error&.dig(:error_class)
+            error: last_error&.dig(:error_class),
+            reason: reason
           )
           Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{log_tag(message, queue_name)} job_class=#{job_class}" }
           return :dead_lettered
@@ -61,17 +71,23 @@ module Pgbus
             # released on completion or DLQ.
             nil
           when :while_executing
-            # Acquire the lock now, bound to this message. If another worker is
-            # already executing this job, skip it — VT will expire and it'll be
-            # retried. A row left by a crashed attempt of THIS message is
+            # Acquire the lock now, bound to this message. If another message
+            # holds it, the job's on_conflict decides (issue #629): :discard
+            # drops this copy, :reject and :log leave it for a backed-off
+            # redelivery. A row left by a crashed attempt of THIS message is
             # re-acquired, not treated as a duplicate.
             acquired = Uniqueness.acquire_execution_lock(
               uniqueness_key, payload, msg_id: message.msg_id.to_i, queue_name: queue_name
             )
-            unless acquired
-              Pgbus.logger.info { "[Pgbus] Skipping duplicate execution for #{job_class}" }
-              return :skipped
-            end
+            return handle_uniqueness_conflict(message, queue_name, payload, uniqueness_key, source_queue) unless acquired
+          when :until_executing
+            # A debounce (issue #628): the row guarded the queued copy, and
+            # goes before perform so an enqueue that arrives while this runs
+            # is accepted. release_held_by! takes only the row this message
+            # holds, never a newer copy's (a dashboard re-send holds its own,
+            # #631). A redelivery (row already gone) matches nothing and runs; a failed release is logged and the
+            # job runs anyway — the reaper or the DLQ release takes the row.
+            release_uniqueness_lock(uniqueness_key, queue_name, message) if holds_uniqueness_row?(payload)
           end
         end
 
@@ -117,16 +133,19 @@ module Pgbus
           # heartbeat lapsed and it was redelivered): that worker owns the
           # completion signals, and signalling again here would release the
           # concurrency slot a second time (rails/solid_queue#761).
-          if archive_from(queue_name, msg_id, source_queue: source_queue) == :already_archived
+          if complete_from(queue_name, msg_id, source_queue: source_queue) == :already_archived
             Pgbus.logger.warn do
-              "[Pgbus::Executor] already archived elsewhere, skipping signals #{log_tag(message, queue_name)} job_class=#{job_class}"
+              "[Pgbus::Executor] already #{@completed_word} elsewhere, skipping signals " \
+                "#{log_tag(message, queue_name)} job_class=#{job_class}"
             end
             release_duplicate_execution_lock(uniqueness_key, uniqueness_strategy, queue_name, msg_id)
             return :duplicate
           end
-          Pgbus.logger.debug { "[Pgbus::Executor] archived #{log_tag(message, queue_name)} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] #{@completed_word} #{log_tag(message, queue_name)} job_class=#{job_class}" }
           job_succeeded = true
-          release_uniqueness_lock(uniqueness_key, queue_name, message)
+          # :until_executing released its row before perform; a newer copy's
+          # row is not this message's to take.
+          release_uniqueness_lock(uniqueness_key, queue_name, message) unless uniqueness_strategy == :until_executing
           # Only FailedEventRecorder.record! writes this table, and only after a
           # failed attempt, so a first delivery has no row: skip the per-job
           # DELETE round trip (issue #484). A stale row from a dropped-and-
@@ -147,7 +166,7 @@ module Pgbus
       rescue Exception => e # rubocop:disable Lint/RescueException
         # Widened from StandardError to catch Async::Stop / Async::Cancel
         # (both inherit from Exception, not StandardError) under execution_mode: :async.
-        # Before this, a fiber interruption between perform_now and archive_from
+        # Before this, a fiber interruption between perform_now and complete_from
         # silently lost control flow — no failed event row, no job_failed
         # notification, uniqueness lock held until VT expired. See issue #126.
         handle_failure(message, queue_name, e, payload: payload, source_queue: source_queue)
@@ -196,7 +215,8 @@ module Pgbus
       # The table the message was read from: the _pN sub-queue under priority
       # routing, else the logical queue's own. Each table numbers its messages
       # from its own sequence, so a failed-event row is keyed on it (issue
-      # #583). Built only on the failure and redelivery paths.
+      # #583). Built only on the failure and redelivery paths, and for the
+      # completer (issue #606), which groups by physical queue.
       def physical_queue(queue_name, source_queue)
         source_queue || config.queue_name(queue_name)
       end
@@ -221,6 +241,15 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Uniqueness release failed: #{e.message}" }
       end
 
+      # False for an :until_executing retry_on re-enqueue (executions > 0): it
+      # went out through the free key without acquiring a row (the attempt's
+      # was released at its start), so the unbound clause of release_held_by!
+      # could only match a newer copy's row — one parked behind its
+      # concurrency limit before this retry was sent (issue #628).
+      def holds_uniqueness_row?(payload)
+        Uniqueness.extract_strategy(payload) != :until_executing || payload["executions"].to_i.zero?
+      end
+
       # Keep the message invisible while perform runs (see VisibilityHeartbeat).
       # Wraps only the perform: the heartbeat must be gone before archive or
       # the retry backoff touches the same message's VT.
@@ -282,33 +311,43 @@ module Pgbus
         Pgbus.logger.debug { "[Pgbus] Stat recording failed: #{e.message}" }
       end
 
+      # pgmq-ruby sets no result type map, so enqueued_at is the TIMESTAMPTZ
+      # text PostgreSQL sends ("2026-10-29 10:11:12.123456+00", any offset).
+      # Time.new reads it in C at ~0.3 µs; Time.parse took ~7 µs a job and
+      # pg's TimestampWithTimeZone decoder ~3 µs (issue #604). Unreadable text
+      # raises ArgumentError: the stat is recorded without latency.
       def compute_enqueue_latency(message)
         return unless message
 
         enqueued_at = message.enqueued_at
         return unless enqueued_at
 
-        # Fast path: numeric epoch (float seconds) avoids Time.parse entirely.
-        # PGMQ returns enqueued_at as a Time or string depending on the driver.
-        case enqueued_at
-        when Numeric
-          [((Time.now.to_f - enqueued_at) * 1000).round, 0].max
-        when Time
-          [((Time.now.utc - enqueued_at.utc) * 1000).round, 0].max
-        else
-          parse_enqueue_latency_from_string(enqueued_at.to_s)
-        end
+        epoch = case enqueued_at
+                when Numeric then enqueued_at
+                when Time then enqueued_at.to_f
+                else enqueued_at_epoch(enqueued_at.to_s)
+                end
+        return unless epoch
+
+        [((::Process.clock_gettime(::Process::CLOCK_REALTIME) - epoch) * 1000).round, 0].max
       rescue ArgumentError, TypeError
         nil
       end
 
-      def parse_enqueue_latency_from_string(str)
-        # PGMQ enqueued_at is TIMESTAMPTZ (always UTC internally).
-        # If the string lacks an explicit offset, assume UTC to avoid
-        # misinterpretation when the system timezone is non-UTC.
-        str = "#{str} UTC" unless str.match?(/[+-]\d{2}:?\d{2}\s*$|Z\s*$/i)
-        enqueued_at = Time.parse(str)
-        [((Time.now.utc - enqueued_at) * 1000).round, 0].max
+      # A trailing "+00", "-03", "+05:30", "+0530" or "Z".
+      UTC_OFFSET_SUFFIX = /(?:[+-]\d\d(?::?\d\d)?|Z)\z/
+      private_constant :UTC_OFFSET_SUFFIX
+
+      # Time.new reads a string without an offset in the host's zone, but
+      # TIMESTAMPTZ is UTC inside, so such a string gets a "Z". Checked here
+      # rather than with `in: "UTC"`: that keyword costs a Hash per job.
+      # Time.new also takes a bare year ("2026") as a time; a string without a
+      # time of day is not a timestamp, so it has no latency.
+      def enqueued_at_epoch(str)
+        return unless str.include?(":")
+
+        str = "#{str}Z" unless str.match?(UTC_OFFSET_SUFFIX)
+        Time.new(str).to_f
       end
 
       def handle_failure(message, queue_name, error, payload: nil, source_queue: nil)
@@ -351,13 +390,88 @@ module Pgbus
                   RetryBackoff.compute_delay(attempt: attempt)
                 end
 
+        set_message_visibility(message, queue_name, delay, source_queue)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Retry backoff VT update failed: #{e.message}" }
+      end
+
+      def set_message_visibility(message, queue_name, delay, source_queue)
         if source_queue
           client.set_visibility_timeout(source_queue, message.msg_id.to_i, vt: delay, prefixed: false)
         else
           client.set_visibility_timeout(queue_name, message.msg_id.to_i, vt: delay)
         end
-      rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus] Retry backoff VT update failed: #{e.message}" }
+      end
+
+      # A :while_executing message whose key another message holds (issue
+      # #629). The duplicate holds no uniqueness row, so nothing is released.
+      def handle_uniqueness_conflict(message, queue_name, payload, key, source_queue)
+        policy = Uniqueness.extract_on_conflict(payload)
+        if policy == :discard
+          discard_duplicate(message, queue_name, payload, key, source_queue)
+        else
+          skip_duplicate(message, queue_name, payload, key, source_queue, policy)
+        end
+      end
+
+      # :discard — the duplicate will never run: complete it, then the
+      # bookkeeping the dead-letter path does for such a message. Lost to
+      # another worker that completed it first: that worker owns the signals.
+      def discard_duplicate(message, queue_name, payload, key, source_queue)
+        msg_id = message.msg_id.to_i
+        if complete_from(queue_name, msg_id, source_queue: source_queue) == :already_archived
+          Pgbus.logger.warn do
+            "[Pgbus::Executor] already #{@completed_word} elsewhere, skipping signals " \
+              "#{log_tag(message, queue_name)} job_class=#{payload["job_class"]}"
+          end
+          return :duplicate
+        end
+        if message.read_ct.to_i > 1
+          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id,
+                                     source_queue: physical_queue(queue_name, source_queue))
+        end
+        signal_concurrency(payload)
+        signal_batch_discarded(payload)
+        instrument("pgbus.job_discarded", queue: queue_name, job_class: payload["job_class"], job_id: payload["job_id"],
+                                          provider_job_id: payload["provider_job_id"], msg_id: msg_id, reason: "uniqueness")
+        Pgbus.logger.info do
+          "[Pgbus] Discarded duplicate #{payload["job_class"]}: uniqueness key #{key} is held by another message " \
+            "(#{log_tag(message, queue_name)})"
+        end
+        :discarded
+      end
+
+      # :reject / :log — the copy still runs once the holder is done, but each
+      # skip backs its redelivery off so the skips stretch over the holder's
+      # run. read_ct cannot be decremented, so a skip still counts toward
+      # max_retries; the dead-letter reason says when that is why it died.
+      def skip_duplicate(message, queue_name, payload, key, source_queue, policy)
+        delay = skip_delay(message, payload)
+        begin
+          set_message_visibility(message, queue_name, delay, source_queue)
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus] Skip backoff VT update failed: #{e.message}" }
+        end
+        text = "[Pgbus] Skipping duplicate execution for #{payload["job_class"]}: uniqueness key #{key} is held by " \
+               "another message (#{log_tag(message, queue_name)}); next delivery in #{delay}s"
+        policy == :log ? Pgbus.logger.warn { text } : Pgbus.logger.info { text }
+        instrument("pgbus.job_skipped", queue: queue_name, job_class: payload["job_class"], job_id: payload["job_id"],
+                                        provider_job_id: payload["provider_job_id"], msg_id: message.msg_id.to_i,
+                                        read_ct: message.read_ct.to_i, on_conflict: policy, vt: delay)
+        :skipped
+      end
+
+      # visibility_timeout * 2^(read_ct - 1), jittered and capped at the job's
+      # (or the global) retry_backoff_max, and never below visibility_timeout:
+      # a skip never comes back sooner than the read's own timeout would.
+      def skip_delay(message, payload)
+        vt = config.visibility_timeout
+        job_class = resolve_job_class(payload)
+        overrides = (job_class.respond_to?(:pgbus_retry_backoff_config) && job_class.pgbus_retry_backoff_config) || {}
+        max = [overrides[:max] || config.retry_backoff_max, vt].max
+        delay = RetryBackoff.compute_delay(attempt: message.read_ct.to_i, base: vt, max: max,
+                                           jitter: overrides[:jitter] || config.retry_backoff_jitter)
+        [delay, vt].max
       end
 
       def resolve_job_class(payload)
@@ -412,7 +526,13 @@ module Pgbus
       # that succeeded but failed to archive redelivers after VT expiry and
       # runs twice. If the retry also fails, fall through to the normal
       # failure path (recorded failure + VT-based redelivery).
-      # Returns :archived, :already_archived, or :ambiguous.
+      # Returns :archived, :already_archived, or :ambiguous. Under
+      # config.completed_jobs = :delete it deletes the message instead
+      # (delete_message, or the completer's delete_batch): pgmq.delete is as
+      # idempotent and returns false the same way, so the symbols keep their
+      # names and "archived" means "completed". job_completion: true lets
+      # config.completion_synchronous_commit = false commit it with
+      # synchronous_commit off (issue #619).
       #
       # A `false` reported after our OWN retry is ambiguous, not a duplicate:
       # the first archive may well have committed with only its reply lost to
@@ -421,13 +541,21 @@ module Pgbus
       # batch and uniqueness state on every such blip, whereas a genuine
       # duplicate would additionally require another worker to have taken and
       # finished the same message inside the retry window.
-      def archive_from(queue_name, msg_id, source_queue: nil)
+      def complete_from(queue_name, msg_id, source_queue: nil)
         attempts = 0
         begin
-          archived = if source_queue
-                       client.archive_message(source_queue, msg_id, prefixed: false)
+          archived = if @completer
+                       @completer.complete(physical_queue(queue_name, source_queue), msg_id) == :archived
+                     # Spelled out, no `**` forward: on Ruby 3.3 that
+                     # allocates per job even without keywords (#484 budget).
+                     elsif @delete_completed && source_queue
+                       client.delete_message(source_queue, msg_id, prefixed: false, job_completion: true)
+                     elsif @delete_completed
+                       client.delete_message(queue_name, msg_id, job_completion: true)
+                     elsif source_queue
+                       client.archive_message(source_queue, msg_id, prefixed: false, job_completion: true)
                      else
-                       client.archive_message(queue_name, msg_id)
+                       client.archive_message(queue_name, msg_id, job_completion: true)
                      end
           return :archived unless archived == false
 
@@ -437,7 +565,7 @@ module Pgbus
           raise unless attempts == 1 && connection_error?(e)
 
           Pgbus.logger.warn do
-            "[Pgbus::Executor] Archive failed on connection error, retrying once: #{e.message}"
+            "[Pgbus::Executor] #{@delete_completed ? "Delete" : "Archive"} failed on connection error, retrying once: #{e.message}"
           end
           retry
         end
@@ -463,14 +591,37 @@ module Pgbus
         defined?(PGMQ::Errors::ConnectionError) && error.is_a?(PGMQ::Errors::ConnectionError)
       end
 
-      def handle_dead_letter(message, queue_name, payload, source_queue: nil, last_error: nil)
+      # uniqueness_conflict for a :while_executing message no attempt of
+      # which failed: it was skipped on every read until read_ct passed
+      # max_retries (issue #629). Not whether the key is held at this read:
+      # the backed-off skips span minutes and the holder may have finished
+      # inside the last one. The one other way to die without a failed-event
+      # row is a crash loop, and a crashed attempt leaves the key's row bound
+      # to this message: that keeps max_retries_exceeded. A failed lookup
+      # keeps the stronger signal, the missing failed-event row.
+      def dead_letter_reason(message, queue_name, payload, last_error)
+        return DeadLetterHeader::REASON_MAX_RETRIES if last_error
+
+        key = Uniqueness.extract_key(payload)
+        return DeadLetterHeader::REASON_MAX_RETRIES unless key && Uniqueness.extract_strategy(payload) == :while_executing
+
+        own = UniquenessKey.bound_to?(key, queue_name: Uniqueness.lock_queue_name(queue_name, config: config),
+                                           msg_id: message.msg_id.to_i)
+        own ? DeadLetterHeader::REASON_MAX_RETRIES : DeadLetterHeader::REASON_UNIQUENESS_CONFLICT
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness row lookup failed, dead-lettering as uniqueness_conflict: #{e.message}" }
+        DeadLetterHeader::REASON_UNIQUENESS_CONFLICT
+      end
+
+      def handle_dead_letter(message, queue_name, payload, source_queue: nil, last_error: nil,
+                             reason: DeadLetterHeader::REASON_MAX_RETRIES)
         Pgbus.logger.warn do
           job_class = payload["job_class"] || "unknown"
           error = last_error ? " (last error: #{last_error[:error_class]})" : ""
           "[Pgbus] Moving job #{job_class} to dead letter queue after #{message.read_ct} attempts#{error}"
         end
         headers = DeadLetterHeader.build(
-          existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "worker",
+          existing: message.headers, reason: reason, source: "worker",
           source_queue: source_queue || config.queue_name(queue_name), source_msg_id: message.msg_id.to_i,
           source_enqueued_at: message.enqueued_at, attempts: message.read_ct.to_i,
           max_retries: config.max_retries, error: last_error