pgbus 0.20.0 → 0.21.0

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",
@@ -100,7 +100,10 @@ module Pgbus
           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) do
-            Delivery.with(msg_id: msg_id, read_ct: read_count, queue_name: queue_name) { execute_job(job) }
+            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
@@ -121,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-
@@ -146,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,
@@ -192,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
@@ -425,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
@@ -442,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
 

data/lib/pgbus/configuration/workflow_settings.rb

@@ -12,7 +12,7 @@ module Pgbus
     #   config.workflow_max_payload_size = 131_072      # bytes: arguments and step outputs
     #   config.workflow_error_backtrace_lines = 50      # backtrace lines kept on a failed step
     #   config.workflow_waiting_visibility_threshold = 7.days # a step waiting this long without a
-    #                                                   # wait_timeout: counts as stuck (waiting_overdue)
+    #                                                   # deadline counts as stuck (waiting_overdue)
     #   config.workflow_subject_url = ->(type, id) { "/admin/#{type.underscore.pluralize}/#{id}" }
     #                                                   # the dashboard's subject link (nil: plain text)
     module WorkflowSettings

data/lib/pgbus/configuration.rb

@@ -13,7 +13,8 @@ module Pgbus
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
 
     # Queue settings
-    attr_accessor :default_queue, :queue_prefix
+    attr_accessor :default_queue
+    attr_reader :queue_prefix # rubocop:disable Style/AccessorGrouping -- the writer normalizes (see queue_prefix=)
 
     # Worker settings
     attr_accessor :polling_interval, :prefetch_limit, :execution_mode
@@ -597,6 +598,25 @@ module Pgbus
       @finalized = false
     end
 
+    # Stored the way the queue tables spell it ("my-app" → "my_app"). Table
+    # names are unchanged (queue_name normalizes the joined name the same
+    # way), but code that strips the prefix off a table name to get its queue
+    # back (the dashboard, the worker, a job's uniqueness lock queue) then
+    # finds it. A value normalize cannot spell (nothing table-safe left, or
+    # too long) is kept as given, as before: validate! rejects one that is
+    # too long, and queue_name drops one with nothing table-safe in it.
+    def queue_prefix=(value)
+      @queue_prefix = if value.is_a?(String) && !value.empty?
+                        begin
+                          QueueNameValidator.normalize(value)
+                        rescue ArgumentError
+                          value
+                        end
+                      else
+                        value
+                      end
+    end
+
     def queue_name(name)
       full = "#{queue_prefix}_#{name}"
       QueueNameValidator.normalize(full)
@@ -1002,6 +1022,27 @@ module Pgbus
       raise Pgbus::ConfigurationError, "capsule processes must be a positive Integer (got #{value.inspect})"
     end
 
+    # A prefix with a leading, trailing or doubled underscore is kept as
+    # written (its tables already exist under it), but queue_name collapses
+    # the separator after it only for a queue name that needs normalizing:
+    # "myapp_" gives myapp__orders yet myapp_orders_handler for
+    # "orders-handler". A job's own release and the dashboard derive the same
+    # lock queue for it and still match, but the reaper cannot resolve that
+    # name back to the table, so a lock orphaned there is never reclaimed and
+    # has to be released by key. Legal, but warned.
+    def warn_queue_prefix_underscores
+      return unless queue_prefix.match?(/\A_|_\z|__/)
+
+      suggested = queue_prefix.squeeze("_").delete_prefix("_").delete_suffix("_")
+      suggestion = suggested.empty? ? "" : "; prefer #{suggested.inspect} for new deployments"
+      Pgbus.logger.warn do
+        "[Pgbus] queue_prefix #{queue_prefix.inspect} has a leading, trailing or doubled underscore — a queue " \
+          "whose name needs normalizing (\"orders-handler\") gets a table spelled unlike its queue, so the " \
+          "reaper cannot find that table: a uniqueness lock orphaned there (a worker crash before its release) " \
+          "is never reclaimed and has to be released by key#{suggestion}"
+      end
+    end
+
     # Buffered claims are kept invisible only by the visibility heartbeat.
     # Without it a message buffered longer than visibility_timeout can be
     # claimed by another worker while it still waits here. Legal, but warned.
@@ -1075,6 +1116,7 @@ module Pgbus
       { queue_prefix: queue_prefix, default_queue: default_queue }.each do |name, value|
         raise Pgbus::ConfigurationError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
       end
+      warn_queue_prefix_underscores
 
       # web_auth gates the dashboard; a non-callable value silently leaves it
       # open (mirror streams_presence_member).

data/lib/pgbus/dead_letter_header.rb

@@ -30,7 +30,13 @@ module Pgbus
 
     # error: FailedEventRecorder.last_error's Hash, or nil when no failure
     # was recorded. Returns the merged headers as a JSON string.
-    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, now: Time.now.utc)
+    # source_msg_id / source_enqueued_at: the message's id in source_queue and
+    # when it was sent (the copy gets a new id and enqueued_at in the DLQ).
+    # A discard of the copy uses both to release only the uniqueness lock the
+    # original still holds: bound to it, or unbound and acquired before its
+    # send, never a lock it handed to a retry after (issue #564).
+    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, source_msg_id: nil,
+              source_enqueued_at: nil, now: Time.now.utc)
       headers = decode(existing, warn: true)
       retries = count(headers.delete(RETRIES_KEY))
       block = {
@@ -42,6 +48,8 @@ module Pgbus
         "max_retries" => max_retries,
         "dead_lettered_at" => iso(now)
       }
+      block["source_msg_id"] = source_msg_id if source_msg_id
+      block["source_enqueued_at"] = iso(source_enqueued_at) if source_enqueued_at
       block["retries_from_dlq"] = retries if retries.positive?
       block.merge!(error_fields(error)) if error
       JSON.generate(headers.merge(KEY => block))

data/lib/pgbus/instrumentation.rb

@@ -79,9 +79,10 @@ module Pgbus
   #                                  payload: workflow_class, workflow_id, name, duplicate,
   #                                  woke (true when it woke the step waiting for it)
   #   pgbus.workflow.wait_timed_out — a waiting step's wait_timeout: passed; its on_timeout
-  #                                  applied (the sweep, or TestHelpers#expire_wait)
+  #                                  applied (the sweep, or TestHelpers#expire_wait); under
+  #                                  notify the step keeps waiting, once per sweep that finds it late
   #                                  payload: workflow_class, workflow_id, step_name, attempt,
-  #                                  action (pause! | cancel! | skip! | run)
+  #                                  action (pause! | cancel! | skip! | run | notify)
   #   pgbus.workflow.gauge         — emitted by each dispatcher workflow sweep
   #                                  payload: statuses ([{ workflow_class:, status:, count: }]),
   #                                  stuck ([{ workflow_class:, reason:, count: }]), zero-filled

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -4,7 +4,7 @@
   ],
   "dashboard": {
     "title": "Pgbus",
-    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, and stuck workflows.\n",
+    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, stuck workflows and late waits.\n",
     "visuals": [
       {
         "type": "timeseries",
@@ -520,6 +520,35 @@
             ]
           }
         ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Late workflow waits",
+        "description": "Deadlines an on_timeout: :notify wait missed, by class and step: the run keeps waiting for its signal.",
+        "line_label": "%workflow_class% - %step%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_wait_overdue_total",
+            "fields": [
+              {
+                "field": "COUNTER"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              }
+            ]
+          }
+        ]
       }
     ]
   }

data/lib/pgbus/mcp/tools/workflow_stats_tool.rb

@@ -11,7 +11,7 @@ module Pgbus
         tool_name "pgbus_workflow_stats"
         title "Pgbus Workflow Stats"
         description <<~DESC
-          One Pgbus::Workflow class over a window (1h, 24h default, 7d or 30d, capped at workflow_retention). steps, in declaration order (gravestones as kind "removed"; names only the rows hold as declared: false): counts (runs sitting at the step now by run status ready/performing/waiting/paused), run_ms (p50/p95/p99 of finished_at - started_at over completed or failed attempts) and pickup_ms (p50/p95 of scheduled → started), rates (failed: an error was recorded, reattempted, skipped) and outcomes over the sample_size attempts that finished in the window; percentiles over fewer than 20 samples are noisy. Also: started/finished/cancelled, e2e_ms, duration_histogram (finished runs per created → finished range), throughput (runs started/finished/cancelled per bucket_seconds), funnel (of the runs started in the window: reached = runs with a row for the step, stopped = where each run is now by status) and by_revision (the five app revisions that finished an attempt last, newest first, totals and per step).
+          One Pgbus::Workflow class over a window (1h, 24h default, 7d or 30d, capped at workflow_retention). steps, in declaration order (gravestones as kind "removed"; names only the rows hold as declared: false): wait_timeout (a wait_for: step's wait_timeout: in seconds, "dynamic" when a lambda or a method name sets it per run, null without one), counts (runs sitting at the step now by run status ready/performing/waiting/paused), run_ms (p50/p95/p99 of finished_at - started_at over completed or failed attempts) and pickup_ms (p50/p95 of scheduled → started), rates (failed: an error was recorded, reattempted, skipped) and outcomes over the sample_size attempts that finished in the window; percentiles over fewer than 20 samples are noisy. Also: started/finished/cancelled, e2e_ms, duration_histogram (finished runs per created → finished range), throughput (runs started/finished/cancelled per bucket_seconds), funnel (of the runs started in the window: reached = runs with a row for the step, stopped = where each run is now by status) and by_revision (the five app revisions that finished an attempt last, newest first, totals and per step).
         DESC
 
         input_schema(

data/lib/pgbus/mcp/tools/workflows_attention_tool.rb

@@ -9,7 +9,7 @@ module Pgbus
         tool_name "pgbus_workflows_attention"
         title "Pgbus Workflows Needing Attention"
         description <<~DESC
-          Ongoing Pgbus::Workflow runs that need a person, grouped by (workflow_class, step_name, reason, error_class): reason is paused_error, stalled, paused_manual, overdue (due but not picked up past workflow_stall_threshold) or waiting_overdue (waiting past workflow_waiting_visibility_threshold without a wait_timeout). Each group has its run count, first_seen_at/last_seen_at, the status its runs are in and the actions that status allows; total_runs sums the groups (at most 200 groups, biggest first). workflow_class narrows them to one class. The newest error message is redacted unless the server allows payloads and include_payloads is set.
+          Ongoing Pgbus::Workflow runs that need a person, grouped by (workflow_class, step_name, reason, error_class): reason is paused_error, stalled, paused_manual, overdue (due but not picked up past workflow_stall_threshold) or waiting_overdue (waiting past workflow_waiting_visibility_threshold without a deadline: no wait_timeout, or a per-run one that set none or cleared it after a :notify notice). Each group has its run count, first_seen_at/last_seen_at, the status its runs are in and the actions that status allows; total_runs sums the groups (at most 200 groups, biggest first). workflow_class narrows them to one class. The newest error message is redacted unless the server allows payloads and include_payloads is set.
         DESC
 
         input_schema(

data/lib/pgbus/metrics/workflow_metrics.rb

@@ -12,6 +12,7 @@ module Pgbus
     #   pgbus_workflows_paused_total{workflow_class, error_class}            counter (error_class absent for a manual pause)
     #   pgbus_workflows_cancelled_total{workflow_class}                      counter
     #   pgbus_workflow_stalls_total{workflow_class, step, detection}         counter (detection: redelivery | sweep)
+    #   pgbus_workflow_wait_overdue_total{workflow_class, step}              counter (a late notice of an on_timeout: :notify wait)
     #   pgbus_workflows{workflow_class, status}                              gauge, from each sweep
     #   pgbus_workflows_stuck{workflow_class, reason}                        gauge, from each sweep
     #
@@ -20,7 +21,7 @@ module Pgbus
     module WorkflowMetrics
       EVENTS = %w[
         pgbus.workflow.step pgbus.workflow_finished pgbus.workflow_paused pgbus.workflow_cancelled
-        pgbus.workflow.stall_detected pgbus.workflow.gauge
+        pgbus.workflow.stall_detected pgbus.workflow.wait_timed_out pgbus.workflow.gauge
       ].freeze
 
       module_function
@@ -37,6 +38,7 @@ module Pgbus
         when "pgbus.workflow_cancelled" then [counter("pgbus_workflows_cancelled_total", workflow_class: klass)]
         when "pgbus.workflow.stall_detected"
           [counter("pgbus_workflow_stalls_total", workflow_class: klass, step: payload[:step_name], detection: payload[:detection])]
+        when "pgbus.workflow.wait_timed_out" then wait_timed_out_samples(klass, payload)
         when "pgbus.workflow.gauge" then gauge_samples(payload)
         else []
         end
@@ -49,6 +51,14 @@ module Pgbus
         samples
       end
 
+      # Only :notify keeps waiting past the deadline; every other on_timeout
+      # ends the wait and is counted by the step or run it ends.
+      def wait_timed_out_samples(klass, payload)
+        return [] unless payload[:action] == "notify"
+
+        [counter("pgbus_workflow_wait_overdue_total", workflow_class: klass, step: payload[:step_name])]
+      end
+
       def gauge_samples(payload)
         statuses = Array(payload[:statuses]).map do |row|
           [:gauge, "pgbus_workflows", row[:count], { workflow_class: row[:workflow_class], status: row[:status] }]

data/lib/pgbus/process/consumer.rb

@@ -296,7 +296,8 @@ module Pgbus
         last_error = FailedEventRecorder.last_error(queue_name: queue_name, msg_id: message.msg_id.to_i)
         headers = DeadLetterHeader.build(
           existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "consumer",
-          source_queue: config.queue_name(queue_name), attempts: message.read_ct.to_i,
+          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
         )
         Pgbus.client.move_to_dead_letter(queue_name, message, headers: headers)

data/lib/pgbus/process/dispatcher.rb

@@ -505,12 +505,22 @@ module Pgbus
       # Unbound rows (synthetic "pending" queue and/or msg_id=0) must not probe
       # pgmq.q_<prefix>_pending — that table does not exist, message_exists?
       # returns nil, and the reaper would keep the lock forever (issue #418).
-      # Scan every live queue for the payload key instead.
+      # Scan every live queue for the payload key instead. A job parked behind
+      # its concurrency slot is in no queue: its key counts as live while it
+      # is parked (issue #564). The parked jobs are asked first: a promotion
+      # sends the job's message before its parked row's delete commits (or
+      # both in one transaction), so a job promoted between the two reads is
+      # still parked for the first or already queued for the second. Read the
+      # other way round it could be in neither.
       def gone_unbound_locks(unbound)
         return [] if unbound.empty?
 
-        present = Pgbus.client.uniqueness_keys_present(unbound.map(&:lock_key))
-        unbound.reject { |key| present.include?(key.lock_key) }
+        parked = BlockedExecution.parked_uniqueness_keys(unbound.map(&:lock_key))
+        unparked = unbound.reject { |key| parked.include?(key.lock_key) }
+        return [] if unparked.empty?
+
+        present = Pgbus.client.uniqueness_keys_present(unparked.map(&:lock_key))
+        unparked.reject { |key| present.include?(key.lock_key) }
       end
 
       # Returns true if the message referenced by this bound lock is definitely

data/lib/pgbus/process/worker.rb

@@ -407,12 +407,21 @@ module Pgbus
       # so we also pass `limit: qty` to cap the total across all queues —
       # otherwise we get `queue_count * qty` messages and overflow the
       # execution pool, crashing the worker fork (issue #123).
+      #
+      # The logical name is the configured one the table was made from, not
+      # the table name with its prefix cut: a name normalized for its table
+      # ("orders-handler" → "orders_handler") would otherwise reach the
+      # executor spelled unlike the name its jobs' uniqueness locks are bound
+      # under, and unlike every other fetch path (issue #564).
       def fetch_multi(active_queues, qty)
         messages = Pgbus.client.read_multi(active_queues, qty: qty, limit: qty) || []
+        return messages if messages.empty?
+
         prefix = "#{config.queue_prefix}_"
+        configured = active_queues.to_h { |q| [config.queue_name(q), q] }
 
         messages.map do |m|
-          logical = m.queue_name&.delete_prefix(prefix) || active_queues.first
+          logical = configured[m.queue_name] || m.queue_name&.delete_prefix(prefix) || active_queues.first
           [logical, m]
         end
       end

data/lib/pgbus/recurring/schedule.rb

@@ -143,7 +143,7 @@ module Pgbus
         key = resolve_uniqueness_key(job_class, config, task)
         return nil unless key
 
-        acquired = UniquenessKey.acquire!(key, queue_name: resolve_queue(task), msg_id: 0)
+        acquired = UniquenessKey.acquire!(key, queue_name: Uniqueness.lock_queue_name(resolve_queue(task)), msg_id: 0)
 
         if acquired
           key

data/lib/pgbus/streams/presence.rb

@@ -72,6 +72,7 @@ module Pgbus
       @schema_mutex = Mutex.new
       @seats_supported = nil
       @probed_at = nil
+      @schema_generation = 0
 
       class << self
         # True when pgbus_presence_members has the seat columns (the
@@ -81,17 +82,29 @@ module Pgbus
         # The answer is read and written under @schema_mutex only (issue
         # #527). A successful probe is kept as above; a probe that raises is
         # not, so the next call probes again.
+        #
+        # The probe itself runs outside @schema_mutex (issue #566): it waits
+        # for the adapter's lock, and a request inside a transaction holds
+        # that lock while it asks seats_supported?. Two threads may probe at
+        # once; a true answer one of them stored is never taken back, and a
+        # probe that a reset_schema_cache! overtook stores nothing.
         def seats_supported?
+          cached, generation = @schema_mutex.synchronize do
+            [(@seats_supported if schema_answer_fresh?(@seats_supported, @probed_at)), @schema_generation]
+          end
+          return cached unless cached.nil?
+
+          rows = exec_params(<<~SQL, [])
+            SELECT 1 AS present FROM information_schema.columns
+            WHERE table_name = 'pgbus_presence_members' AND column_name = 'connection_id'
+              AND table_schema = ANY (current_schemas(false))
+          SQL
+          supported = !rows.to_a.empty?
           @schema_mutex.synchronize do
-            next @seats_supported if schema_answer_fresh?(@seats_supported, @probed_at)
+            next supported unless generation == @schema_generation
 
-            rows = connection.exec_params(<<~SQL, [])
-              SELECT 1 AS present FROM information_schema.columns
-              WHERE table_name = 'pgbus_presence_members' AND column_name = 'connection_id'
-                AND table_schema = ANY (current_schemas(false))
-            SQL
             @probed_at = monotonic_now
-            @seats_supported = !rows.to_a.empty?
+            @seats_supported ||= supported
           end
         end
 
@@ -108,6 +121,7 @@ module Pgbus
 
         def reset_schema_cache!
           @schema_mutex.synchronize do
+            @schema_generation += 1
             @probed_at = nil
             @seats_supported = nil
           end
@@ -124,7 +138,7 @@ module Pgbus
         def expire_seats!(ttl_for:, min_ttl:)
           return [] unless seats_supported?
 
-          candidates = connection.exec_params(<<~SQL, [min_ttl])
+          candidates = exec_params(<<~SQL, [min_ttl])
             SELECT stream_name, connection_id FROM pgbus_presence_members
             WHERE connection_id IS NOT NULL AND last_seen_at < NOW() - make_interval(secs => $1)
           SQL
@@ -133,23 +147,23 @@ module Pgbus
           end
         end
 
+        # The PG::Connection under the adapter. Run SQL through exec_params,
+        # not on this: the adapter's lock is released once it is returned.
         def connection
-          # Respect multi-database setups (connects_to). When
-          # Pgbus.configuration.connects_to is set, the pgbus tables
-          # live in a separate database accessed via Pgbus::BusRecord;
-          # the default path uses ActiveRecord::Base. Matches the
-          # canonical pattern in Pgbus::Process::QueueLock#connection
-          # and Pgbus::Configuration's connection probe.
-          unless defined?(::ActiveRecord::Base)
-            raise Pgbus::ConfigurationError,
-                  "Pgbus::Streams::Presence requires ActiveRecord (no AR connection available)"
-          end
+          adapter.raw_connection
+        end
 
-          if Pgbus.configuration.connects_to
-            Pgbus::BusRecord.connection.raw_connection
-          else
-            ::ActiveRecord::Base.connection.raw_connection
-          end
+        # Runs one statement on the adapter's PG::Connection while holding
+        # the adapter's lock (issue #566). raw_connection takes that lock
+        # only to hand the connection out; on a pinned pool (transactional
+        # tests) every thread shares the one adapter, and its lock is all
+        # that keeps a second thread's statement off the libpq connection
+        # while this one is in flight. Unpinned, the lock is a NullLock. The
+        # lock is reentrant, so a thread already holding it (a request
+        # inside a transaction) re-enters it.
+        def exec_params(sql, binds)
+          adapter = self.adapter
+          adapter.lock.synchronize { adapter.raw_connection.exec_params(sql, binds) }
         end
 
         # Reports a seat join/leave to streams_presence_on_change (issue #515).
@@ -171,6 +185,21 @@ module Pgbus
 
         private
 
+        # Respect multi-database setups (connects_to). When
+        # Pgbus.configuration.connects_to is set, the pgbus tables
+        # live in a separate database accessed via Pgbus::BusRecord;
+        # the default path uses ActiveRecord::Base. Matches the
+        # canonical pattern in Pgbus::Process::QueueLock#connection
+        # and Pgbus::Configuration's connection probe.
+        def adapter
+          unless defined?(::ActiveRecord::Base)
+            raise Pgbus::ConfigurationError,
+                  "Pgbus::Streams::Presence requires ActiveRecord (no AR connection available)"
+          end
+
+          Pgbus.configuration.connects_to ? Pgbus::BusRecord.connection : ::ActiveRecord::Base.connection
+        end
+
         def schema_answer_fresh?(supported, probed_at)
           return false if supported.nil? || probed_at.nil?
 
@@ -178,7 +207,7 @@ module Pgbus
         end
 
         def expire_stream_seats(stream_name, connection_ids, ttl)
-          rows = connection.exec_params(<<~SQL, [stream_name, text_array(connection_ids), ttl])
+          rows = exec_params(<<~SQL, [stream_name, text_array(connection_ids), ttl])
             DELETE FROM pgbus_presence_members
             WHERE stream_name = $1 AND connection_id = ANY($2::text[])
               AND last_seen_at < NOW() - make_interval(secs => $3)
@@ -306,7 +335,7 @@ module Pgbus
         return touch_seats(Array(connection_id)) if connection_id
 
         member_id = member_id.to_s
-        connection.exec_params(<<~SQL, [@stream.name, member_id])
+        exec_params(<<~SQL, [@stream.name, member_id])
           UPDATE pgbus_presence_members
           SET last_seen_at = NOW()
           WHERE stream_name = $1 AND member_id = $2#{" AND connection_id IS NULL" if seats_now?}
@@ -320,7 +349,7 @@ module Pgbus
       def set_state(connection_id:, state:)
         raise ArgumentError, "set_state takes a Hash (got #{state.class})" unless state.is_a?(Hash)
 
-        rows = connection.exec_params(<<~SQL, [@stream.name, connection_id.to_s, JSON.generate(state)])
+        rows = exec_params(<<~SQL, [@stream.name, connection_id.to_s, JSON.generate(state)])
           UPDATE pgbus_presence_members
           SET state = state || $3::jsonb, last_seen_at = NOW()
           WHERE stream_name = $1 AND connection_id = $2
@@ -335,7 +364,7 @@ module Pgbus
       # table each row is one seat and also carries connection_id, seat
       # and state; group by "id" for one entry per member.
       def members
-        rows = connection.exec_params(<<~SQL, [@stream.name])
+        rows = exec_params(<<~SQL, [@stream.name])
           SELECT #{seats? ? SEAT_RECORD_COLUMNS : RECORD_COLUMNS}
           FROM pgbus_presence_members
           WHERE stream_name = $1
@@ -347,7 +376,7 @@ module Pgbus
       # Returns the count of current members. Faster than members.size
       # because it doesn't deserialize metadata.
       def count
-        rows = connection.exec_params(<<~SQL, [@stream.name])
+        rows = exec_params(<<~SQL, [@stream.name])
           SELECT COUNT(*) AS n FROM pgbus_presence_members WHERE stream_name = $1
         SQL
         rows.first["n"].to_i
@@ -362,7 +391,7 @@ module Pgbus
       # workers running the sweep concurrently won't double-emit leave
       # events. Yields each expired record when a block is given.
       def sweep!(older_than:)
-        rows = connection.exec_params(<<~SQL, [@stream.name, older_than])
+        rows = exec_params(<<~SQL, [@stream.name, older_than])
           DELETE FROM pgbus_presence_members
           WHERE stream_name = $1 AND last_seen_at < $2#{" AND connection_id IS NULL" if seats_now?}
           RETURNING #{RECORD_COLUMNS}
@@ -388,7 +417,7 @@ module Pgbus
 
       def upsert_member_once(member_id, metadata)
         conflict = seats? ? "(stream_name, member_id) WHERE connection_id IS NULL" : "(stream_name, member_id)"
-        rows = connection.exec_params(<<~SQL, [@stream.name, member_id, JSON.generate(metadata)])
+        rows = exec_params(<<~SQL, [@stream.name, member_id, JSON.generate(metadata)])
           INSERT INTO pgbus_presence_members (stream_name, member_id, metadata, joined_at, last_seen_at)
           VALUES ($1, $2, $3::jsonb, NOW(), NOW())
           ON CONFLICT #{conflict}
@@ -399,7 +428,7 @@ module Pgbus
       end
 
       def upsert_seat(member_id, metadata, connection_id, seat)
-        rows = connection.exec_params(<<~SQL, [@stream.name, member_id, JSON.generate(metadata), connection_id, seat])
+        rows = exec_params(<<~SQL, [@stream.name, member_id, JSON.generate(metadata), connection_id, seat])
           INSERT INTO pgbus_presence_members
             (stream_name, member_id, metadata, connection_id, seat, joined_at, last_seen_at)
           VALUES ($1, $2, $3::jsonb, $4, $5, NOW(), NOW())
@@ -412,7 +441,7 @@ module Pgbus
       end
 
       def delete_member(member_id)
-        rows = connection.exec_params(<<~SQL, [@stream.name, member_id])
+        rows = exec_params(<<~SQL, [@stream.name, member_id])
           DELETE FROM pgbus_presence_members
           WHERE stream_name = $1 AND member_id = $2#{" AND connection_id IS NULL" if seats_now?}
           RETURNING #{RECORD_COLUMNS}
@@ -422,7 +451,7 @@ module Pgbus
       end
 
       def delete_seat(connection_id)
-        rows = connection.exec_params(<<~SQL, [@stream.name, connection_id])
+        rows = exec_params(<<~SQL, [@stream.name, connection_id])
           DELETE FROM pgbus_presence_members
           WHERE stream_name = $1 AND connection_id = $2
           RETURNING #{SEAT_RECORD_COLUMNS}
@@ -434,7 +463,7 @@ module Pgbus
       def touch_seats(connection_ids)
         return [] if connection_ids.empty?
 
-        rows = connection.exec_params(<<~SQL, [@stream.name, self.class.text_array(connection_ids)])
+        rows = exec_params(<<~SQL, [@stream.name, self.class.text_array(connection_ids)])
           UPDATE pgbus_presence_members
           SET last_seen_at = NOW()
           WHERE stream_name = $1 AND connection_id = ANY($2::text[])
@@ -443,8 +472,8 @@ module Pgbus
         rows.to_a.map { |row| row["connection_id"] }
       end
 
-      def connection
-        self.class.connection
+      def exec_params(sql, binds)
+        self.class.exec_params(sql, binds)
       end
     end
   end