pgbus 0.3.2 → 0.3.4

data/lib/generators/pgbus/migrate_job_locks_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class MigrateJobLocksGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Migrate pgbus_job_locks to lightweight pgbus_uniqueness_keys table"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        if separate_database?
+          migration_template "migrate_job_locks_to_uniqueness_keys.rb.erb",
+                             "db/pgbus_migrate/migrate_pgbus_job_locks_to_uniqueness_keys.rb"
+        else
+          migration_template "migrate_job_locks_to_uniqueness_keys.rb.erb",
+                             "db/migrate/migrate_pgbus_job_locks_to_uniqueness_keys.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus uniqueness keys migration created!", :green
+        say ""
+        say "This migration will:"
+        say "  1. Create the new pgbus_uniqueness_keys table (3 columns, 1 index)"
+        say "  2. Migrate existing locks from pgbus_job_locks"
+        say "  3. Drop the old pgbus_job_locks table (8 columns, 3 indexes)"
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Restart pgbus: bin/pgbus start"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+class AddPgbusUniquenessKeys < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :pgbus_uniqueness_keys, id: false do |t|
+      t.string :lock_key, null: false
+      t.string :queue_name, null: false
+      t.bigint :msg_id, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :pgbus_uniqueness_keys, :lock_key,
+      unique: true, name: "idx_pgbus_uniqueness_keys_key"
+  end
+end

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

@@ -0,0 +1,33 @@
+class MigratePgbusJobLocksToUniquenessKeys < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # Create the new lightweight uniqueness keys table
+    unless table_exists?(:pgbus_uniqueness_keys)
+      create_table :pgbus_uniqueness_keys, id: false do |t|
+        t.string :lock_key, null: false
+        t.string :queue_name, null: false
+        t.bigint :msg_id, null: false
+        t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      end
+
+      add_index :pgbus_uniqueness_keys, :lock_key,
+        unique: true, name: "idx_pgbus_uniqueness_keys_key"
+    end
+
+    # Drop the old table. Require it to be empty — active locks should be
+    # drained before migrating (stop workers, let VT expire, restart).
+    if table_exists?(:pgbus_job_locks)
+      count = execute("SELECT COUNT(*) FROM pgbus_job_locks").first["count"].to_i
+      if count > 0
+        raise "pgbus_job_locks has #{count} active lock(s). " \
+              "Drain workers and wait for locks to clear before migrating."
+      end
+
+      drop_table :pgbus_job_locks
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          "Cannot safely reconstruct pgbus_job_locks from pgbus_uniqueness_keys"
+  end
+end

data/lib/pgbus/active_job/adapter.rb

@@ -23,7 +23,7 @@ module Pgbus
         payload_hash = Concurrency.inject_metadata(active_job, payload_hash)
         payload_hash = Uniqueness.inject_metadata(active_job, payload_hash)
         payload_hash = inject_batch_metadata(payload_hash)
-        delay = [(timestamp - Time.now.to_f).ceil, 0].max
+        delay = [(timestamp - Time.current.to_f).ceil, 0].max
 
         return active_job if uniqueness_rejected?(active_job, payload_hash)
 
@@ -34,7 +34,7 @@ module Pgbus
         # Jobs with uniqueness must go through individual enqueue to acquire locks
         unique, bulk = active_jobs.partition { |j| Uniqueness.uniqueness_config(j) }
         unique.each do |j|
-          if j.scheduled_at && j.scheduled_at > Time.now
+          if scheduled_in_future?(j)
             enqueue_at(j, j.scheduled_at.to_f)
           else
             enqueue(j)
@@ -42,8 +42,9 @@ module Pgbus
         end
 
         bulk.group_by { |j| j.queue_name || Pgbus.configuration.default_queue }.each do |queue, jobs|
-          enqueue_immediate(queue, jobs.reject { |j| j.scheduled_at && j.scheduled_at > Time.now })
-          jobs.select { |j| j.scheduled_at && j.scheduled_at > Time.now }.each { |j| enqueue_at(j, j.scheduled_at.to_f) }
+          immediate, scheduled = jobs.partition { |j| !scheduled_in_future?(j) }
+          enqueue_immediate(queue, immediate)
+          scheduled.each { |j| enqueue_at(j, j.scheduled_at.to_f) }
         end
 
         active_jobs.count
@@ -159,6 +160,10 @@ module Pgbus
         raise
       end
 
+      def scheduled_in_future?(job)
+        job.scheduled_at && job.scheduled_at > Time.current
+      end
+
       def enqueue_after_transaction_commit?
         true
       end

data/lib/pgbus/active_job/executor.rb

@@ -7,9 +7,10 @@ module Pgbus
     class Executor
       attr_reader :client, :config
 
-      def initialize(client: Pgbus.client, config: Pgbus.configuration)
+      def initialize(client: Pgbus.client, config: Pgbus.configuration, stat_buffer: nil)
         @client = client
         @config = config
+        @stat_buffer = stat_buffer
       end
 
       def execute(message, queue_name, source_queue: nil)
@@ -29,15 +30,14 @@ module Pgbus
         job_class = payload["job_class"]
         uniqueness_key = Uniqueness.extract_key(payload)
         uniqueness_strategy = Uniqueness.extract_strategy(payload)
-        uniqueness_ttl = payload[Uniqueness::TTL_KEY] || Uniqueness::DEFAULT_LOCK_TTL
 
         if uniqueness_key
           case uniqueness_strategy
           when :until_executed
-            # Transition the queued lock to executing state with our PID.
-            # The lock was acquired at enqueue time — now we claim ownership
-            # so the reaper can correlate it with our heartbeat.
-            Uniqueness.claim_for_execution!(uniqueness_key, ttl: uniqueness_ttl)
+            # No claim step needed — PGMQ's visibility timeout is the execution lock.
+            # The uniqueness key row was inserted at enqueue time and will be
+            # released on completion or DLQ.
+            nil
           when :while_executing
             # Acquire the lock now. If another worker is already executing
             # this job, skip it — VT will expire and it'll be retried.
@@ -96,18 +96,20 @@ module Pgbus
       def record_stat(payload, queue_name, status, start_time, message: nil)
         return unless config.stats_enabled
 
-        duration_ms = ((monotonic_now - start_time) * 1000).round
-        enqueue_latency_ms = compute_enqueue_latency(message)
-        retry_count = message ? [message.read_ct.to_i - 1, 0].max : 0
-
-        JobStat.record!(
+        attrs = {
           job_class: payload&.dig("job_class") || "unknown",
           queue_name: queue_name,
           status: status,
-          duration_ms: duration_ms,
-          enqueue_latency_ms: enqueue_latency_ms,
-          retry_count: retry_count
-        )
+          duration_ms: ((monotonic_now - start_time) * 1000).round,
+          enqueue_latency_ms: compute_enqueue_latency(message),
+          retry_count: message ? [message.read_ct.to_i - 1, 0].max : 0
+        }
+
+        if @stat_buffer
+          @stat_buffer.push(attrs)
+        else
+          JobStat.record!(**attrs)
+        end
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus] Stat recording failed: #{e.message}" }
       end
@@ -115,15 +117,32 @@ module Pgbus
       def compute_enqueue_latency(message)
         return unless message
 
-        enqueued_at_str = message.enqueued_at
-        return unless enqueued_at_str
+        enqueued_at = message.enqueued_at
+        return unless enqueued_at
 
-        enqueued_at = Time.parse(enqueued_at_str.to_s)
-        [((Time.now.utc - enqueued_at) * 1000).round, 0].max
+        # 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
       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
+      end
+
       def handle_failure(_message, _queue_name, error)
         Pgbus.logger.error { "[Pgbus] Job failed: #{error.class}: #{error.message}" }
         Pgbus.logger.debug { error.backtrace&.join("\n") }

data/lib/pgbus/circuit_breaker.rb

@@ -29,10 +29,10 @@ module Pgbus
 
     def paused?(queue_name)
       cached = @pause_cache[queue_name]
-      return cached[:paused] if cached && (Time.now - cached[:checked_at]) < @pause_cache_ttl
+      return cached[:paused] if cached && (Time.current - cached[:checked_at]) < @pause_cache_ttl
 
       paused = check_paused(queue_name)
-      @pause_cache[queue_name] = { paused: paused, checked_at: Time.now }
+      @pause_cache[queue_name] = { paused: paused, checked_at: Time.current }
       paused
     end
 

data/lib/pgbus/client.rb

@@ -76,8 +76,7 @@ module Pgbus
     def send_batch(queue_name, payloads, headers: nil, delay: 0)
       full_name = config.queue_name(queue_name)
       ensure_queue(queue_name)
-      serialized = payloads.map { |p| serialize(p) }
-      serialized_headers = headers&.map { |h| h.nil? ? nil : serialize(h) }
+      serialized, serialized_headers = serialize_batch(payloads, headers)
       Instrumentation.instrument("pgbus.client.send_batch", queue: full_name, size: payloads.size) do
         synchronized { @pgmq.produce_batch(full_name, serialized, headers: serialized_headers, delay: delay) }
       end
@@ -378,5 +377,22 @@ module Pgbus
         JSON.generate(data)
       end
     end
+
+    # Single-pass serialization of payloads and optional headers.
+    # Avoids two separate .map iterations over the same index range.
+    def serialize_batch(payloads, headers)
+      serialized = Array.new(payloads.size)
+      serialized_headers = headers ? Array.new(headers.size) : nil
+
+      payloads.each_with_index do |p, i|
+        serialized[i] = serialize(p)
+        if serialized_headers && i < headers.size
+          h = headers[i]
+          serialized_headers[i] = h.nil? ? nil : serialize(h)
+        end
+      end
+
+      [serialized, serialized_headers]
+    end
   end
 end

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -13,7 +13,7 @@ module Pgbus
             queue_name: queue_name,
             payload: JSON.generate(payload),
             priority: priority,
-            expires_at: Time.now.utc + duration
+            expires_at: Time.current + duration
           )
         end
 
@@ -45,7 +45,7 @@ module Pgbus
         # Delete blocked executions that have expired.
         # Returns the count of deleted rows.
         def expire_stale
-          Pgbus::BlockedExecution.expired(Time.now.utc).delete_all
+          Pgbus::BlockedExecution.expired(Time.current).delete_all
         end
 
         # Count blocked executions for a given key. Useful for testing/monitoring.
@@ -59,7 +59,7 @@ module Pgbus
           scheduled_at = payload["scheduled_at"]
           return default_delay unless scheduled_at
 
-          [Time.parse(scheduled_at).to_f - Time.now.to_f, 0].max.ceil
+          [Time.parse(scheduled_at).to_f - Time.current.to_f, 0].max.ceil
         rescue StandardError
           default_delay
         end

data/lib/pgbus/concurrency/semaphore.rb

@@ -7,7 +7,7 @@ module Pgbus
         # Attempt to acquire a slot in the semaphore for the given key.
         # Returns :acquired if a slot was available, :blocked if the limit is reached.
         def acquire(key, max_value, duration)
-          expires_at = Time.now.utc + duration
+          expires_at = Time.current + duration
           Pgbus::Semaphore.acquire!(key, max_value, expires_at)
         end
 
@@ -23,7 +23,7 @@ module Pgbus
           result = Pgbus::Semaphore.connection.exec_query(
             "DELETE FROM pgbus_semaphores WHERE expires_at < $1 RETURNING key",
             "Pgbus Semaphore Expire",
-            [Time.now.utc]
+            [Time.current]
           )
           result.rows.map { |row| { "key" => row[0] } }
         end

data/lib/pgbus/process/dispatcher.rb

@@ -21,15 +21,15 @@ module Pgbus
       def initialize(config: Pgbus.configuration)
         @config = config
         @shutting_down = false
-        @last_cleanup_at = Time.now
-        @last_reap_at = Time.now
-        @last_concurrency_at = Time.now
-        @last_batch_cleanup_at = Time.now
-        @last_recurring_cleanup_at = Time.now
-        @last_archive_compaction_at = Time.now
-        @last_outbox_cleanup_at = Time.now
-        @last_job_lock_cleanup_at = Time.now
-        @last_stats_cleanup_at = Time.now
+        @last_cleanup_at = monotonic_now
+        @last_reap_at = monotonic_now
+        @last_concurrency_at = monotonic_now
+        @last_batch_cleanup_at = monotonic_now
+        @last_recurring_cleanup_at = monotonic_now
+        @last_archive_compaction_at = monotonic_now
+        @last_outbox_cleanup_at = monotonic_now
+        @last_job_lock_cleanup_at = monotonic_now
+        @last_stats_cleanup_at = monotonic_now
       end
 
       def run
@@ -65,7 +65,7 @@ module Pgbus
       private
 
       def run_maintenance
-        now = Time.now
+        now = monotonic_now
 
         run_if_due(now, :@last_cleanup_at, CLEANUP_INTERVAL) { cleanup_processed_events }
         run_if_due(now, :@last_reap_at, REAP_INTERVAL) { reap_stale_processes }
@@ -93,7 +93,7 @@ module Pgbus
         ttl = config.idempotency_ttl
         return unless ttl&.positive?
 
-        deleted = ProcessedEvent.expired(Time.now.utc - ttl).delete_all
+        deleted = ProcessedEvent.expired(Time.current - ttl).delete_all
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} expired processed events" } if deleted.positive?
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Idempotency cleanup failed: #{e.message}" }
@@ -101,7 +101,7 @@ module Pgbus
 
       def reap_stale_processes
         threshold = Heartbeat::ALIVE_THRESHOLD
-        deleted = ProcessEntry.stale(Time.now.utc - threshold).delete_all
+        deleted = ProcessEntry.stale(Time.current - threshold).delete_all
         Pgbus.logger.info { "[Pgbus] Reaped #{deleted} stale processes" } if deleted.positive?
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Stale process reaping failed: #{e.message}" }
@@ -127,7 +127,7 @@ module Pgbus
       end
 
       def cleanup_batches
-        deleted = Batch.cleanup(older_than: Time.now.utc - (7 * 24 * 3600)) # 7 days
+        deleted = Batch.cleanup(older_than: Time.current - (7 * 24 * 3600)) # 7 days
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} finished batches" } if deleted.positive?
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Batch cleanup failed: #{e.message}" }
@@ -139,21 +139,44 @@ module Pgbus
         retention = config.stats_retention
         return unless retention&.positive?
 
-        deleted = JobStat.cleanup!(older_than: Time.now.utc - retention)
+        deleted = JobStat.cleanup!(older_than: Time.current - retention)
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old job stats" } if deleted.positive?
       end
 
       def cleanup_job_locks
-        # Primary: reap orphaned locks whose owner worker is no longer alive.
-        # Cross-references (owner_pid, owner_hostname) against pgbus_processes heartbeats.
-        reaped = JobLock.reap_orphaned!
-        Pgbus.logger.info { "[Pgbus] Reaped #{reaped} orphaned job locks" } if reaped.positive?
+        # Clean up orphaned uniqueness keys whose msg_id no longer exists
+        # in any PGMQ queue. This handles the rare case where a message is
+        # lost (e.g., queue table truncated) but the uniqueness key remains.
+        reaped = reap_orphaned_uniqueness_keys
+        Pgbus.logger.info { "[Pgbus] Reaped #{reaped} orphaned uniqueness keys" } if reaped.positive?
+      end
+
+      def reap_orphaned_uniqueness_keys
+        keys = UniquenessKey.all.to_a
+        return 0 if keys.empty?
+
+        threshold = Time.current - (config.visibility_timeout * 2)
+
+        orphaned = keys.select do |key|
+          # msg_id == 0 means pre-produce placeholder or :while_executing lock.
+          # These are live locks — never reap them based on msg_id alone.
+          # Only reap if old enough that the job is certainly gone.
+          next false if key.msg_id.zero? && (!key.created_at || key.created_at >= threshold)
+          next true if key.msg_id.zero? && key.created_at && key.created_at < threshold
+
+          # For real msg_ids, only reap if stale (old enough that VT has
+          # long expired). The message itself may still be in the queue
+          # awaiting retry — age is the only safe signal without scanning
+          # every queue table.
+          key.created_at && key.created_at < threshold
+        end
+
+        return 0 if orphaned.empty?
 
-        # Last resort: clean up locks with expired TTL (handles case where
-        # even the reaper/supervisor is dead and locks are truly abandoned).
-        expired = JobLock.cleanup_expired!
-        Pgbus.logger.debug { "[Pgbus] Cleaned up #{expired} expired job locks" } if expired.positive?
-        # No rescue here — let run_if_due handle the error and retry next tick
+        UniquenessKey.where(lock_key: orphaned.map(&:lock_key)).delete_all
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness key cleanup failed: #{e.message}" }
+        0
       end
 
       def cleanup_outbox
@@ -162,7 +185,7 @@ module Pgbus
         retention = config.outbox_retention
         return unless retention&.positive?
 
-        deleted = OutboxEntry.published_before(Time.now.utc - retention).delete_all
+        deleted = OutboxEntry.published_before(Time.current - retention).delete_all
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} published outbox entries" } if deleted.positive?
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Outbox cleanup failed: #{e.message}" }
@@ -176,7 +199,7 @@ module Pgbus
         retention = config.archive_retention
         return unless retention&.positive?
 
-        cutoff = Time.now.utc - retention
+        cutoff = Time.current - retention
         batch_size = config.archive_compaction_batch_size || 1000
         prefix = config.queue_prefix
 
@@ -200,12 +223,16 @@ module Pgbus
         retention = config.recurring_execution_retention
         return unless retention&.positive?
 
-        deleted = RecurringExecution.older_than(Time.now.utc - retention).delete_all
+        deleted = RecurringExecution.older_than(Time.current - retention).delete_all
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} old recurring executions" } if deleted.positive?
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Recurring execution cleanup failed: #{e.message}" }
       end
 
+      def monotonic_now
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+
       def start_heartbeat
         @heartbeat = Heartbeat.new(kind: "dispatcher", metadata: { pid: ::Process.pid })
         @heartbeat.start

data/lib/pgbus/process/worker.rb

@@ -23,8 +23,10 @@ module Pgbus
         @jobs_failed = Concurrent::AtomicFixnum.new(0)
         @in_flight = Concurrent::AtomicFixnum.new(0)
         @rate_counter = RateCounter.new(:processed, :failed, :dequeued)
-        @started_at = Time.now
-        @executor = Pgbus::ActiveJob::Executor.new
+        @started_at = Time.current
+        @started_at_monotonic = monotonic_now
+        @stat_buffer = config.stats_enabled ? Pgbus::StatBuffer.new : nil
+        @executor = Pgbus::ActiveJob::Executor.new(stat_buffer: @stat_buffer)
         @pool = Concurrent::FixedThreadPool.new(threads)
         @circuit_breaker = Pgbus::CircuitBreaker.new(config: config)
         @queue_lock = QueueLock.new if @single_active_consumer
@@ -61,6 +63,7 @@ module Pgbus
           break if @lifecycle.draining? && @pool.queue_length.zero?
 
           claim_and_execute if @lifecycle.can_process?
+          @stat_buffer&.flush_if_due
           @wake_signal.wait(timeout: config.polling_interval) if @lifecycle.draining? || @lifecycle.paused?
         end
 
@@ -271,7 +274,7 @@ module Pgbus
       end
 
       def exceeded_max_lifetime?
-        return false unless config.max_worker_lifetime && (Time.now - @started_at) > config.max_worker_lifetime
+        return false unless config.max_worker_lifetime && (monotonic_now - @started_at_monotonic) > config.max_worker_lifetime
 
         Pgbus.logger.info { "[Pgbus] Worker recycling: lifetime exceeded" }
         true
@@ -317,6 +320,7 @@ module Pgbus
         Pgbus.logger.info { "[Pgbus] Worker draining thread pool..." }
         @pool.shutdown
         @pool.wait_for_termination(30)
+        @stat_buffer&.stop
         @queue_lock&.unlock_all
         @heartbeat&.stop
         restore_signals

data/lib/pgbus/recurring/schedule.rb

@@ -10,29 +10,19 @@ module Pgbus
         @tasks = load_tasks
       end
 
-      def due_tasks(time = Time.now)
+      def due_tasks(time = Time.current)
         tasks.select { |task| task_due?(task, time) }
       end
 
       def enqueue_task(task, run_at:)
         queue = resolve_queue(task)
+        acquired_key = acquire_uniqueness_lock(task)
 
-        # Check uniqueness lock before enqueuing. If the job class declares
-        # ensures_uniqueness, we acquire the lock here so duplicate recurring
-        # enqueues are rejected while a previous instance is still queued or running.
-        if uniqueness_locked?(task)
-          Pgbus.logger.debug do
-            "[Pgbus] Recurring task #{task.key} skipped: uniqueness lock held"
-          end
-          return
-        end
+        return if acquired_key == :already_locked
 
         RecurringExecution.record(task.key, run_at) do
           payload = build_payload(task)
           headers = build_headers(task, run_at)
-
-          # Inject uniqueness metadata into the payload so the worker knows
-          # to release the lock after execution.
           payload = inject_uniqueness_metadata(task, payload)
 
           Pgbus.client.ensure_queue(queue)
@@ -44,7 +34,11 @@ module Pgbus
           end
         end
       rescue AlreadyRecorded
+        release_uniqueness_lock(acquired_key)
         Pgbus.logger.debug { "[Pgbus] Recurring task #{task.key} already enqueued for #{run_at.iso8601}" }
+      rescue StandardError
+        release_uniqueness_lock(acquired_key)
+        raise
       end
 
       def build_payload(task)
@@ -112,36 +106,45 @@ module Pgbus
         }
       end
 
-      # Check if the job class has ensures_uniqueness and if its lock is currently held.
-      # Returns true if the lock is held (skip enqueue), false otherwise.
-      def uniqueness_locked?(task)
-        return false unless task.class_name
+      # Acquire the uniqueness lock for a recurring task.
+      # Returns:
+      #   nil              — no uniqueness configured, proceed without lock
+      #   :already_locked  — lock held by a previous instance, caller should skip enqueue
+      #   String           — the lock key (lock was acquired, caller must release on failure)
+      def acquire_uniqueness_lock(task)
+        return nil unless task.class_name
 
         job_class = task.class_name.safe_constantize
-        return false unless job_class
-        return false unless job_class.respond_to?(:pgbus_uniqueness)
+        return nil unless job_class
+        return nil unless job_class.respond_to?(:pgbus_uniqueness)
 
         config = job_class.pgbus_uniqueness
-        return false unless config
-        return false unless config[:strategy] == :until_executed
+        return nil unless config
+        return nil unless config[:strategy] == :until_executed
 
         key = resolve_uniqueness_key(config, task)
-        return false unless key
-
-        # Try to acquire the lock. If it fails, the lock is already held.
-        acquired = JobLock.acquire!(
-          key,
-          job_class: task.class_name,
-          job_id: "recurring-#{task.key}",
-          state: "queued",
-          ttl: config[:lock_ttl]
-        )
-        # If we acquired it, great — the message will be enqueued with the lock held.
-        # If not, a previous instance is still queued/running.
-        !acquired
+        return nil unless key
+
+        acquired = UniquenessKey.acquire!(key, queue_name: resolve_queue(task), msg_id: 0)
+
+        if acquired
+          key
+        else
+          Pgbus.logger.debug { "[Pgbus] Recurring task #{task.key} skipped: uniqueness lock held" }
+          :already_locked
+        end
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness lock failed for #{task.key}: #{e.message}" }
+        nil # Fail open — allow enqueue if lock check errors
+      end
+
+      # Release a uniqueness lock. Safe to call with nil or :already_locked.
+      def release_uniqueness_lock(key)
+        return if key.nil? || key == :already_locked
+
+        UniquenessKey.release!(key)
       rescue StandardError => e
-        Pgbus.logger.warn { "[Pgbus] Uniqueness check failed for #{task.key}: #{e.message}" }
-        false # Fail open — allow enqueue if uniqueness check errors
+        Pgbus.logger.warn { "[Pgbus] Lock rollback failed: #{e.message}" }
       end
 
       # Resolve the uniqueness key for a recurring task.

data/lib/pgbus/recurring/scheduler.rb

@@ -30,7 +30,7 @@ module Pgbus
           process_signals
           break if @shutting_down
 
-          tick(Time.now)
+          tick(Time.current)
           break if @shutting_down
 
           interruptible_sleep(config.recurring_schedule_interval)