pgbus 0.19.4 → 0.20.1

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

@@ -0,0 +1,150 @@
+class AddPgbusWorkflows < ActiveRecord::Migration<%= migration_version %>
+  # if_not_exists throughout: pgbus:update queues this migration when any of
+  # the three core tables is missing, so a half-present schema must not fail
+  # it. The waiting-step columns and pgbus_workflow_signals (issue #541) are
+  # here too, so a fresh install needs no pgbus:add_workflow_signals.
+  # up/down rather than change: Rails 7.1 cannot reverse an add_foreign_key
+  # that names its primary_key, and dropping the tables drops the keys.
+  def up
+    # One row per workflow run (Pgbus::WorkflowEntry).
+    create_table :pgbus_workflows, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :subject_type
+      t.string :subject_id
+      t.string :subject_gid
+      t.jsonb :arguments, null: false, default: {}
+      t.string :status, null: false, default: "ready"
+      t.string :current_step
+      t.jsonb :step_job_options, null: false, default: {}
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.datetime :paused_at
+      t.datetime :finished_at
+      t.datetime :cancelled_at
+      t.string :idempotency_key
+      t.string :definition_digest, null: false
+      t.string :rerun_of_workflow_id
+      t.datetime :created_at, null: false
+      t.datetime :updated_at, null: false
+    end
+
+    add_index :pgbus_workflows, :workflow_id,
+      unique: true, name: "idx_pgbus_workflows_workflow_id", if_not_exists: true
+    add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id],
+      unique: true, where: "status IN ('ready','performing','waiting','paused')",
+      name: "idx_pgbus_workflows_one_ongoing", if_not_exists: true
+    add_index :pgbus_workflows, [:workflow_class, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflows_idempotency", if_not_exists: true
+    add_index :pgbus_workflows, [:status, :updated_at],
+      name: "idx_pgbus_workflows_status", if_not_exists: true
+    add_index :pgbus_workflows, [:workflow_class, :status, :created_at],
+      name: "idx_pgbus_workflows_class_status", if_not_exists: true
+    add_index :pgbus_workflows, [:subject_type, :subject_id],
+      name: "idx_pgbus_workflows_subject", if_not_exists: true
+
+    # One row per step attempt (Pgbus::WorkflowStep).
+    create_table :pgbus_workflow_steps, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :step_name, null: false
+      t.integer :attempt, null: false, default: 1
+      t.string :status, null: false, default: "scheduled"
+      t.string :job_id
+      t.bigint :msg_id
+      t.datetime :scheduled_at, null: false
+      t.datetime :enqueued_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.datetime :stall_at
+      t.string :outcome
+      t.jsonb :output
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.jsonb :error_causes
+      t.string :worker
+      t.string :app_revision
+      # Waiting steps (fan_out, wait_for:): also added by pgbus:add_workflow_signals.
+      t.string :batch_id
+      t.string :wait_for
+      t.bigint :signal_id
+      t.datetime :waiting_since
+      t.datetime :timeout_at
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_steps, [:workflow_id, :step_name, :attempt],
+      unique: true, name: "idx_pgbus_workflow_steps_attempt", if_not_exists: true
+    add_index :pgbus_workflow_steps, [:status, :scheduled_at],
+      name: "idx_pgbus_workflow_steps_scheduled", if_not_exists: true
+    add_index :pgbus_workflow_steps, [:status, :stall_at],
+      name: "idx_pgbus_workflow_steps_stall", if_not_exists: true
+    add_index :pgbus_workflow_steps, [:workflow_class, :step_name, :finished_at],
+      name: "idx_pgbus_workflow_steps_insights", if_not_exists: true
+    # A steps table that predates waiting steps lacks these columns (the
+    # queued pgbus:add_workflow_signals adds them and their indexes).
+    if column_exists?(:pgbus_workflow_steps, :batch_id)
+      add_index :pgbus_workflow_steps, :batch_id,
+        name: "idx_pgbus_workflow_steps_batch", if_not_exists: true
+    end
+    if column_exists?(:pgbus_workflow_steps, :timeout_at)
+      add_index :pgbus_workflow_steps, [:status, :timeout_at],
+        name: "idx_pgbus_workflow_steps_timeout", if_not_exists: true
+    end
+    add_foreign_key :pgbus_workflow_steps, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade, if_not_exists: true
+
+    # Append-only audit trail: one row per transition or operator action
+    # (Pgbus::WorkflowEvent).
+    create_table :pgbus_workflow_events, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.bigint :step_id
+      t.string :step_name
+      t.integer :attempt
+      t.string :event, null: false
+      t.string :actor, null: false
+      t.text :reason
+      t.jsonb :details, null: false, default: {}
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_events, [:workflow_id, :id],
+      name: "idx_pgbus_workflow_events_workflow", if_not_exists: true
+    add_foreign_key :pgbus_workflow_events, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade, if_not_exists: true
+
+    # One row per signal delivered to a run (Pgbus::WorkflowSignal):
+    # pending → claimed → consumed.
+    create_table :pgbus_workflow_signals, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.string :name, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.string :idempotency_key
+      t.string :status, null: false, default: "pending"
+      t.bigint :claimed_by_step_id
+      t.datetime :created_at, null: false
+      t.datetime :claimed_at
+      t.datetime :consumed_at
+    end
+
+    add_index :pgbus_workflow_signals, [:workflow_id, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflow_signals_idempotency", if_not_exists: true
+    add_index :pgbus_workflow_signals, [:workflow_id, :name, :status],
+      name: "idx_pgbus_workflow_signals_pending", if_not_exists: true
+    add_index :pgbus_workflow_signals, [:workflow_id, :status, :claimed_by_step_id],
+      name: "idx_pgbus_workflow_signals_claimed", if_not_exists: true
+    add_foreign_key :pgbus_workflow_signals, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade, if_not_exists: true
+  end
+
+  def down
+    drop_table :pgbus_workflow_signals, if_exists: true
+    drop_table :pgbus_workflow_events, if_exists: true
+    drop_table :pgbus_workflow_steps, if_exists: true
+    drop_table :pgbus_workflows, if_exists: true
+  end
+end

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

@@ -211,6 +211,129 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     add_index :pgbus_deploy_task_runs, :run_at,
       name: "idx_pgbus_deploy_task_runs_cleanup"
 
+    # Workflows (Pgbus::Workflow): one row per run, one per step attempt, and
+    # the append-only audit trail. At most one ongoing run per (class, subject).
+    create_table :pgbus_workflows do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :subject_type
+      t.string :subject_id
+      t.string :subject_gid
+      t.jsonb :arguments, null: false, default: {}
+      t.string :status, null: false, default: "ready"
+      t.string :current_step
+      t.jsonb :step_job_options, null: false, default: {}
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.datetime :paused_at
+      t.datetime :finished_at
+      t.datetime :cancelled_at
+      t.string :idempotency_key
+      t.string :definition_digest, null: false
+      t.string :rerun_of_workflow_id
+      t.datetime :created_at, null: false
+      t.datetime :updated_at, null: false
+    end
+
+    add_index :pgbus_workflows, :workflow_id,
+      unique: true, name: "idx_pgbus_workflows_workflow_id"
+    add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id],
+      unique: true, where: "status IN ('ready','performing','waiting','paused')",
+      name: "idx_pgbus_workflows_one_ongoing"
+    add_index :pgbus_workflows, [:workflow_class, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflows_idempotency"
+    add_index :pgbus_workflows, [:status, :updated_at],
+      name: "idx_pgbus_workflows_status"
+    add_index :pgbus_workflows, [:workflow_class, :status, :created_at],
+      name: "idx_pgbus_workflows_class_status"
+    add_index :pgbus_workflows, [:subject_type, :subject_id],
+      name: "idx_pgbus_workflows_subject"
+
+    create_table :pgbus_workflow_steps do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :step_name, null: false
+      t.integer :attempt, null: false, default: 1
+      t.string :status, null: false, default: "scheduled"
+      t.string :job_id
+      t.bigint :msg_id
+      t.datetime :scheduled_at, null: false
+      t.datetime :enqueued_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.datetime :stall_at
+      t.string :outcome
+      t.jsonb :output
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.jsonb :error_causes
+      t.string :worker
+      t.string :app_revision
+      t.string :batch_id
+      t.string :wait_for
+      t.bigint :signal_id
+      t.datetime :waiting_since
+      t.datetime :timeout_at
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_steps, [:workflow_id, :step_name, :attempt],
+      unique: true, name: "idx_pgbus_workflow_steps_attempt"
+    add_index :pgbus_workflow_steps, [:status, :scheduled_at],
+      name: "idx_pgbus_workflow_steps_scheduled"
+    add_index :pgbus_workflow_steps, [:status, :stall_at],
+      name: "idx_pgbus_workflow_steps_stall"
+    add_index :pgbus_workflow_steps, [:workflow_class, :step_name, :finished_at],
+      name: "idx_pgbus_workflow_steps_insights"
+    add_index :pgbus_workflow_steps, :batch_id,
+      name: "idx_pgbus_workflow_steps_batch"
+    add_index :pgbus_workflow_steps, [:status, :timeout_at],
+      name: "idx_pgbus_workflow_steps_timeout"
+    add_foreign_key :pgbus_workflow_steps, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade
+
+    create_table :pgbus_workflow_events do |t|
+      t.string :workflow_id, null: false
+      t.bigint :step_id
+      t.string :step_name
+      t.integer :attempt
+      t.string :event, null: false
+      t.string :actor, null: false
+      t.text :reason
+      t.jsonb :details, null: false, default: {}
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_events, [:workflow_id, :id],
+      name: "idx_pgbus_workflow_events_workflow"
+    add_foreign_key :pgbus_workflow_events, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade
+
+    create_table :pgbus_workflow_signals do |t|
+      t.string :workflow_id, null: false
+      t.string :name, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.string :idempotency_key
+      t.string :status, null: false, default: "pending"
+      t.bigint :claimed_by_step_id
+      t.datetime :created_at, null: false
+      t.datetime :claimed_at
+      t.datetime :consumed_at
+    end
+
+    add_index :pgbus_workflow_signals, [:workflow_id, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflow_signals_idempotency"
+    add_index :pgbus_workflow_signals, [:workflow_id, :name, :status],
+      name: "idx_pgbus_workflow_signals_pending"
+    add_index :pgbus_workflow_signals, [:workflow_id, :status, :claimed_by_step_id],
+      name: "idx_pgbus_workflow_signals_claimed"
+    add_foreign_key :pgbus_workflow_signals, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade
+
     # Stream queue registry — records which PGMQ queues back streams (vs jobs).
     # Stream and job queues share the pgbus_ namespace, so maintenance
     # (per-stream retention, orphan sweep) and wildcard workers rely on this
@@ -245,6 +368,10 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     execute "SELECT pgmq.drop_queue('pgbus_default')"
 
     drop_table :pgbus_stream_queues
+    drop_table :pgbus_workflow_signals
+    drop_table :pgbus_workflow_events
+    drop_table :pgbus_workflow_steps
+    drop_table :pgbus_workflows
     drop_table :pgbus_deploy_task_runs
     drop_table :pgbus_deploy_tasks
     drop_table :pgbus_recurring_executions

data/lib/pgbus/active_job/adapter.rb

@@ -80,6 +80,7 @@ module Pgbus
         # reset: once the send returns, msg_id is set and the rescue routes
         # on that instead.
         sending = false
+        retry_lock = hand_lock_to_retry(active_job, payload_hash, queue)
 
         if key && concurrency
           # The check and the park commit together, under the semaphore row
@@ -115,6 +116,9 @@ module Pgbus
         # Bind before backfill so a live message is never left with an unbound
         # uniqueness row if execution-row bookkeeping raises.
         bind_acquired_uniqueness_lock(queue, msg_id) if msg_id
+        bind_retry_lock(retry_lock, queue, msg_id) if msg_id
+        # Dropped by its concurrency limit: no retry will run, the attempt does.
+        return_retry_lock(retry_lock) unless msg_id || blocked
         Batch.backfill_execution(payload_hash, msg_id, physical_queue(queue, priority)) if msg_id
         # A retry re-enqueue that is now live (sent, or parked as a blocked
         # execution) must stop the original attempt from signalling completion.
@@ -135,6 +139,7 @@ module Pgbus
         # database error from the slot upsert or the park is not ambiguous.
         if msg_id.nil? && !(sending && ambiguous_delivery?(e))
           rollback_acquired_uniqueness_lock
+          return_retry_lock(retry_lock)
           uncount_batch_job(payload_hash, active_job)
         else
           # Drop the thread-local so a later discard on this thread cannot
@@ -247,9 +252,10 @@ module Pgbus
         # the executor still holds the key (it releases only on success/DLQ). So
         # a re-enqueue with executions > 0 would otherwise hit its own held key,
         # be rejected as a duplicate (JobNotUnique), and dead-letter the original
-        # while losing the retry. Let the retry through; the existing key row
-        # correctly stays held until the job finally succeeds or dead-letters.
-        # See issue #333.
+        # while losing the retry. Let the retry through (issue #333); the key
+        # row is handed to it (hand_lock_to_retry, then bind_retry_lock once
+        # sent), so the attempt's release leaves it held until the job finally
+        # succeeds or dead-letters (issue #564).
         return false if active_job.executions.to_i.positive?
 
         result = Uniqueness.acquire_enqueue_lock(uniqueness_key, active_job, queue_name: queue)
@@ -285,6 +291,78 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Uniqueness bind failed: #{e.message}" }
       end
 
+      # The job's :until_executed key and the delivery of the attempt running
+      # it, when this enqueue is that attempt's retry: the retry is let
+      # through the key the attempt holds and never acquires one, so the key
+      # row has to follow it. nil for a first attempt (it acquired its own
+      # row), a retry enqueued outside the executor (no attempt to take it
+      # from), or a job run inline inside another job, whose delivery it sees.
+      def retry_uniqueness_lock(active_job, payload_hash)
+        key = Uniqueness.extract_key(payload_hash)
+        return unless key && Uniqueness.extract_strategy(payload_hash) == :until_executed
+        return unless active_job.executions.to_i.positive?
+
+        delivery = Delivery.current
+        [key, delivery] if delivery && delivery[:job_id] == active_job.job_id
+      end
+
+      # Take the attempt's row for its retry before the retry exists — sent or
+      # parked — the way a first enqueue acquires before its send (see
+      # UniquenessKey.unbind!). Returns [key, delivery, stamp] for
+      # bind_retry_lock / return_retry_lock, or nil when there is nothing to
+      # hand over. A failure is logged and the retry goes out without the row,
+      # which then stays with the attempt.
+      def hand_lock_to_retry(active_job, payload_hash, queue)
+        key, delivery = retry_uniqueness_lock(active_job, payload_hash)
+        return unless key
+
+        stamp = UniquenessKey.unbind!(key, from_queue_name: Uniqueness.lock_queue_name(delivery[:queue_name]),
+                                           from_msg_id: delivery[:msg_id], from_enqueued_at: delivery[:enqueued_at],
+                                           queue_name: Uniqueness.lock_queue_name(queue))
+        return [key, delivery, stamp] if stamp
+
+        warn_retry_lock_not_held(key)
+        nil
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness handoff to retry failed for #{key}: #{e.message}" }
+        nil
+      end
+
+      # Point the handed-over row at the sent retry. The retry is live, so a
+      # failure is logged, not raised: the row stays unbound and stamped
+      # before the send, and the retry's own release takes it.
+      def bind_retry_lock(retry_lock, queue, msg_id)
+        return unless retry_lock
+
+        key, _delivery, stamp = retry_lock
+        UniquenessKey.bind!(key, queue_name: Uniqueness.lock_queue_name(queue), msg_id: msg_id, acquired_at: stamp)
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness bind to retry failed for #{key}: #{e.message}" }
+      end
+
+      # No retry came of it (dropped by its concurrency limit, or the send
+      # failed before any message existed): bind the row back to the attempt,
+      # which runs on and releases it when it finishes.
+      def return_retry_lock(retry_lock)
+        return unless retry_lock
+
+        key, delivery, stamp = retry_lock
+        UniquenessKey.bind!(key, queue_name: Uniqueness.lock_queue_name(delivery[:queue_name]),
+                                 msg_id: delivery[:msg_id], acquired_at: stamp)
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness return to the attempt failed for #{key}: #{e.message}" }
+      end
+
+      # The row is gone (released by an operator, reaped) or a successor's:
+      # the retry runs without the key, and a fresh enqueue is not deduped
+      # against it.
+      def warn_retry_lock_not_held(key)
+        Pgbus.logger.warn do
+          "[Pgbus] Uniqueness key #{key} is no longer held by the attempt that enqueued its retry; " \
+            "the retry runs without it"
+        end
+      end
+
       # Reverses inject_batch_metadata for a job discarded at enqueue time
       # (uniqueness duplicate or concurrency :discard conflict): the message is
       # never sent, so it can never signal completion. Only applies to a job

data/lib/pgbus/active_job/delivery.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module ActiveJob
+    # The PGMQ delivery of the job running in this fiber:
+    #
+    #   Pgbus::ActiveJob::Delivery.current
+    #   # => { msg_id: 42, read_ct: 2, queue_name: "default",
+    #   #      enqueued_at: "2026-10-18 10:30:00+00", job_id: "8f0c…" }
+    #
+    # Set by Executor#execute around perform_now and cleared after, also when
+    # the job raises; nil outside the executor (perform_now in a test, a
+    # top-level inline-adapter job). A job run inline from inside an executing
+    # job sees the enclosing job's delivery; StepJob only acts on it when the
+    # step row's msg_id matches, and the adapter only when job_id is its own,
+    # so that is harmless. Fiber-local (Thread.current[]), so concurrent jobs under
+    # execution_mode: :async each see their own. Pgbus::Workflow::StepJob reads
+    # read_ct to tell a redelivery after a worker died from a first delivery;
+    # the adapter reads the message identity and enqueued_at to move the
+    # job's uniqueness lock onto a retry the job enqueues (issue #564).
+    #
+    # The values sit in one fiber-local each and the Hash is built only
+    # when read: setting them allocates nothing, which keeps the executor's
+    # per-job allocation budget (spec/pgbus/active_job/executor_allocation_budget_spec.rb).
+    module Delivery
+      MSG_ID_KEY = :pgbus_delivery_msg_id
+      READ_CT_KEY = :pgbus_delivery_read_ct
+      QUEUE_NAME_KEY = :pgbus_delivery_queue_name
+      ENQUEUED_AT_KEY = :pgbus_delivery_enqueued_at
+      JOB_ID_KEY = :pgbus_delivery_job_id
+
+      module_function
+
+      def current
+        msg_id = Thread.current[MSG_ID_KEY]
+        return nil if msg_id.nil?
+
+        { msg_id: msg_id, read_ct: Thread.current[READ_CT_KEY], queue_name: Thread.current[QUEUE_NAME_KEY],
+          enqueued_at: Thread.current[ENQUEUED_AT_KEY], job_id: Thread.current[JOB_ID_KEY] }
+      end
+
+      def with(msg_id:, read_ct:, queue_name:, enqueued_at: nil, job_id: nil)
+        previous_msg_id = Thread.current[MSG_ID_KEY]
+        previous_read_ct = Thread.current[READ_CT_KEY]
+        previous_queue_name = Thread.current[QUEUE_NAME_KEY]
+        previous_enqueued_at = Thread.current[ENQUEUED_AT_KEY]
+        previous_job_id = Thread.current[JOB_ID_KEY]
+        Thread.current[MSG_ID_KEY] = msg_id
+        Thread.current[READ_CT_KEY] = read_ct
+        Thread.current[QUEUE_NAME_KEY] = queue_name
+        Thread.current[ENQUEUED_AT_KEY] = enqueued_at
+        Thread.current[JOB_ID_KEY] = job_id
+        yield
+      ensure
+        Thread.current[MSG_ID_KEY] = previous_msg_id
+        Thread.current[READ_CT_KEY] = previous_read_ct
+        Thread.current[QUEUE_NAME_KEY] = previous_queue_name
+        Thread.current[ENQUEUED_AT_KEY] = previous_enqueued_at
+        Thread.current[JOB_ID_KEY] = previous_job_id
+      end
+    end
+  end
+end

data/lib/pgbus/active_job/executor.rb

@@ -33,7 +33,7 @@ module Pgbus
           FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
           signal_concurrency(payload)
           signal_batch_discarded(payload)
-          Uniqueness.release_lock(Uniqueness.extract_key(payload))
+          release_uniqueness_lock(Uniqueness.extract_key(payload), queue_name, message)
           record_stat(payload, queue_name, "dead_lettered", execution_start, message: message)
           instrument(
             "pgbus.job_dead_lettered",
@@ -99,7 +99,12 @@ module Pgbus
           # `batch` (and `batch.enqueue` for open batches) work inside a job.
           assign_batch_id(job, payload)
           Pgbus.logger.debug { "[Pgbus::Executor] running #{log_tag(message, queue_name)} job_class=#{job_class}" }
-          with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) { execute_job(job) }
+          with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) do
+            Delivery.with(msg_id: msg_id, read_ct: read_count, queue_name: queue_name,
+                          enqueued_at: message.enqueued_at, job_id: payload["job_id"]) do
+              execute_job(job)
+            end
+          end
           # retry_on re-enqueues from inside perform_now and returns normally:
           # this attempt is done (archive it) but the job is not — the retry
           # message carries the batch tag and signals on its own outcome.
@@ -119,7 +124,7 @@ module Pgbus
           end
           Pgbus.logger.debug { "[Pgbus::Executor] archived #{log_tag(message, queue_name)} job_class=#{job_class}" }
           job_succeeded = true
-          release_uniqueness_lock(uniqueness_key)
+          release_uniqueness_lock(uniqueness_key, queue_name, message)
           # 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-
@@ -144,7 +149,7 @@ module Pgbus
         # A failed :while_executing attempt is no longer executing — release
         # so the retry (same message, after VT) can acquire. :until_executed
         # keeps its lock until success/DLQ by design (#126, #333).
-        release_uniqueness_lock(uniqueness_key) if uniqueness_strategy == :while_executing
+        release_uniqueness_lock(uniqueness_key, queue_name, message) if uniqueness_strategy == :while_executing
         instrument(
           "pgbus.job_failed",
           queue: queue_name,
@@ -190,10 +195,15 @@ module Pgbus
         job.batch_id = batch_id
       end
 
-      def release_uniqueness_lock(key)
+      # Releases only the row this message holds, never the key as such: a
+      # row the job moved onto its retry (issue #564), or a successor's, stays.
+      # The queue is spelled as the row was bound (Uniqueness.lock_queue_name),
+      # as for release_duplicate_execution_lock.
+      def release_uniqueness_lock(key, queue_name, message)
         return unless key
 
-        Uniqueness.release_lock(key)
+        UniquenessKey.release_held_by!(key, queue_name: Uniqueness.lock_queue_name(queue_name, config: config),
+                                            msg_id: message.msg_id.to_i, enqueued_at: message.enqueued_at)
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Uniqueness release failed: #{e.message}" }
       end
@@ -423,7 +433,8 @@ module Pgbus
 
         # Same queue the execution lock was acquired under, so the match
         # cannot land on another queue's message of the same id.
-        UniquenessKey.release_if_bound!(uniqueness_key, queue_name: queue_name, msg_id: msg_id)
+        UniquenessKey.release_if_bound!(uniqueness_key, queue_name: Uniqueness.lock_queue_name(queue_name, config: config),
+                                                        msg_id: msg_id)
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Duplicate-execution lock release failed: #{e.message}" }
       end
@@ -440,7 +451,8 @@ module Pgbus
         end
         headers = DeadLetterHeader.build(
           existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "worker",
-          source_queue: source_queue || config.queue_name(queue_name), attempts: message.read_ct.to_i,
+          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
         )
         if source_queue

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -16,13 +16,21 @@ module Pgbus
         # once. Handing it a pre-serialized String stored a JSON *string*
         # (double-encoded), which every document reader of the column —
         # `payload->>'job_id'`, the job-class lookup, `scheduled_at` — misread.
+        #
+        # created_at is left to the column's CURRENT_TIMESTAMP default: the
+        # job's uniqueness lock is stamped by the database too, and discarding
+        # a parked job releases only a lock acquired no later than the park
+        # (UniquenessKey.release_if_unbound!), so both sides need one clock.
         def insert(concurrency_key:, queue_name:, payload:, duration:, priority: 0)
-          Pgbus::BlockedExecution.create!(
-            concurrency_key: concurrency_key,
-            queue_name: queue_name,
-            payload: payload,
-            priority: priority,
-            expires_at: Time.current + duration
+          Pgbus::BlockedExecution.insert!(
+            {
+              concurrency_key: concurrency_key,
+              queue_name: queue_name,
+              payload: payload,
+              priority: priority,
+              expires_at: Time.current + duration
+            },
+            record_timestamps: false
           )
         end