pgbus 0.19.4 → 0.20.1

data/lib/pgbus/mcp/write_tool.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # Base class for the opt-in write tools (issue #550). Deliberately not a
+    # BaseTool subclass: no write tool can inherit the read-only annotations,
+    # and no read tool can become a write tool by changing its superclass.
+    # Server registers these only when config.mcp_write_tools is true.
+    #
+    # Every call (#perform): the run loaded (unknown: ok: false), the tool's
+    # inputs and a reason (1-500 characters after trimming) checked,
+    # expected_status checked when given, the verb checked against the run's
+    # available_actions, then the same Web::DataSource action the dashboard
+    # uses, recorded as actor "mcp" (or "mcp:<client name>"). The answer is
+    # { ok:, reason:, workflow: } with the run as it is after the call,
+    # payloads always redacted; a refusal changes nothing and records nothing.
+    #
+    # The two checks read the run before acting, so they are advisory: the
+    # action's guarded transition under the run's row lock decides, and its
+    # code (:not_allowed, with the status the run is in now) is passed on.
+    class WriteTool < ::MCP::Tool
+      ANNOTATIONS = { read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: false }.freeze
+      REASON_LIMIT = 500
+      CLIENT_NAME_LIMIT = 100
+      ACTOR = "mcp"
+      # What an unexpected failure answers: its text can carry internals
+      # (hosts, SQL, values), and Web::DataSource has already logged it.
+      FAILED = "the action failed unexpectedly; the error is in the pgbus log"
+
+      annotations(**ANNOTATIONS)
+
+      class << self
+        # MCP::Tool.inherited resets @annotations_value on every subclass, so
+        # fall back to the nearest ancestor's (as BaseTool does).
+        def annotations_value
+          super || (superclass.respond_to?(:annotations_value) ? superclass.annotations_value : nil)
+        end
+
+        # For a verb whose repeat can never act again (cancel: a cancelled run
+        # stays cancelled). Not skip or resume at: a retry can act again once
+        # the run has parked or paused again.
+        def idempotent!
+          annotations(**ANNOTATIONS, idempotent_hint: true)
+        end
+
+        # The input_schema every write tool takes, plus the tool's own fields.
+        def workflow_input_schema(properties: {}, required: [])
+          {
+            properties: {
+              workflow_id: { type: "string", description: "The run's workflow_id (a UUID)." },
+              reason: { type: "string", minLength: 1, maxLength: REASON_LIMIT,
+                        description: "Why, in 1-#{REASON_LIMIT} characters. Recorded on the run's audit trail." },
+              expected_status: {
+                type: "string", enum: Workflow::States::WORKFLOW,
+                description: "The status you read. If the run is in another one when the call starts: ok: false, nothing done."
+              },
+              **properties
+            },
+            required: %w[workflow_id reason] + required
+          }
+        end
+
+        # The tool description: what it does, the transition it makes, and the
+        # opt-in. Frozen: it is class state (the conformance audit checks).
+        def verb_description(verb, summary)
+          transition = Workflow::States.fetch(verb)
+          <<~DESC.freeze
+            #{summary} Allowed from: #{transition.from.join(", ")}. What happens: #{transition.effect}. A write tool: it exists only when the server was built with config.mcp_write_tools = true. reason is required and recorded on the run's audit trail with actor "mcp" (or "mcp:<client name>" when the transport knows the client); pass expected_status (the status you read with pgbus_workflow): a run that has moved on by the time the call starts answers ok: false and nothing is done (the check runs just before the action, whose transition is guarded again under the run's row lock). Answers { ok, reason, workflow } with the run as it is after the call; a refused call changes nothing and records nothing (a transition refused under the lock adds code and status, a disallowed verb available_actions); arguments, outputs, signal payloads and error text are redacted.
+          DESC
+        end
+
+        # Runs the checks, then yields (data_source, actor:, reason:) for the
+        # DataSource action, whose { ok:, ... } becomes the answer. +invalid+
+        # is the tool's own input refusal (a blank step, an oversized
+        # payload), answered like every other refusal: with the run as it is.
+        def perform(verb, workflow_id:, reason:, expected_status:, server_context:, invalid: nil)
+          data_source = BaseTool.data_source_from(server_context)
+          detail = data_source.workflow_detail(workflow_id)
+          return answer(ok: false, reason: "workflow #{workflow_id} not found", workflow: nil) unless detail
+
+          note = reason.to_s.strip
+          refusal = input_refusal(note, invalid) || guard_refusal(verb, detail, expected_status)
+          return answer(**refusal, workflow: present(detail)) if refusal
+
+          result = outcome(yield(data_source, actor: actor(server_context), reason: note))
+          answer(**result, workflow: present(data_source.workflow_detail(workflow_id)))
+        end
+
+        def answer(**value) = BaseTool.json_response(value)
+
+        private
+
+        def input_refusal(note, invalid)
+          unless note.length.between?(1, REASON_LIMIT)
+            return { ok: false, reason: "reason must be 1-#{REASON_LIMIT} characters after trimming whitespace" }
+          end
+
+          { ok: false, reason: invalid } if invalid
+        end
+
+        # The DataSource action's answer, ok and reason first; an unexpected
+        # failure's text replaced (FAILED).
+        def outcome(result)
+          reason = result[:code] == :failed ? FAILED : result[:reason]
+          { ok: result[:ok], reason: reason, **result.except(:ok, :reason) }
+        end
+
+        def guard_refusal(verb, detail, expected_status)
+          status = detail[:status].to_s
+          if expected_status && expected_status.to_s != status
+            return { ok: false, reason: "workflow #{detail[:workflow_id]} is #{status}, not #{expected_status}" }
+          end
+
+          allowed = Array(detail[:available_actions]).map(&:to_s)
+          return if allowed.include?(verb.to_s)
+
+          { ok: false, reason: "cannot #{verb.to_s.tr("_", " ")} a #{status} workflow", available_actions: allowed }
+        end
+
+        def present(detail) = detail && WorkflowPayloads.detail(detail, allowed: false)
+
+        # "mcp", or "mcp:<name>" when the transport knows the client (an
+        # MCP::ServerContext on mcp >= 1.x; a plain Hash context has none).
+        # The name is client-supplied: control characters dropped, length capped.
+        def actor(server_context)
+          info = server_context.client_info if server_context.respond_to?(:client_info)
+          name = info.is_a?(Hash) ? (info[:name] || info["name"]) : nil
+          name = name.to_s.gsub(/[^[:print:]]/, "").strip[0, CLIENT_NAME_LIMIT]
+          name.empty? ? ACTOR : "#{ACTOR}:#{name}"
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp.rb

@@ -14,6 +14,7 @@ module Pgbus
     REQUIRES = %w[
       pgbus/mcp/redactor
       pgbus/mcp/base_tool
+      pgbus/mcp/serialization
       pgbus/mcp/health_analyzer
       pgbus/mcp/tools/health_tool
       pgbus/mcp/tools/queues_tool
@@ -29,6 +30,20 @@ module Pgbus
       pgbus/mcp/tools/stats_tool
       pgbus/mcp/tools/recurring_tool
       pgbus/mcp/tools/deploy_tasks_tool
+      pgbus/mcp/workflow_payloads
+      pgbus/mcp/tools/workflows_tool
+      pgbus/mcp/tools/workflow_detail_tool
+      pgbus/mcp/tools/workflows_attention_tool
+      pgbus/mcp/workflow_insights_payload
+      pgbus/mcp/tools/workflow_definitions_tool
+      pgbus/mcp/tools/workflow_stats_tool
+      pgbus/mcp/write_tool
+      pgbus/mcp/tools/workflow_resume_tool
+      pgbus/mcp/tools/workflow_cancel_tool
+      pgbus/mcp/tools/workflow_skip_step_tool
+      pgbus/mcp/tools/workflow_resume_at_tool
+      pgbus/mcp/tools/workflow_run_now_tool
+      pgbus/mcp/tools/workflow_signal_tool
       pgbus/mcp/server
       pgbus/mcp/runner
       pgbus/mcp/rack_app

data/lib/pgbus/metrics/backends/statsd.rb

@@ -11,6 +11,10 @@ module Pgbus
       #   gauge     -> "name:value|g"
       #   histogram -> "name:value|ms"
       #
+      # StatsD reads |ms values as milliseconds, so a histogram named
+      # *_seconds (the Prometheus convention, e.g.
+      # pgbus_workflow_step_duration_seconds) is sent as *_ms, times 1000.
+      #
       # Tags are appended as DogStatsD `|#k:v,k:v`. No gem dependency — a plain
       # UDPSocket. UDP send is fire-and-forget; any socket error is logged and
       # swallowed so a metrics hiccup never propagates into the producer thread.
@@ -32,6 +36,8 @@ module Pgbus
         end
 
         def histogram(name, value, tags = {})
+          return emit("#{name.delete_suffix("_seconds")}_ms", value * 1000.0, "ms", tags) if name.end_with?("_seconds")
+
           emit(name, value, "ms", tags)
         end
 

data/lib/pgbus/metrics/subscriber.rb

@@ -73,7 +73,8 @@ module Pgbus
             subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
             subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) },
             subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) },
-            subscribe("pgbus.client.pool") { |event| on_client_pool(event) }
+            subscribe("pgbus.client.pool") { |event| on_client_pool(event) },
+            *WorkflowMetrics::EVENTS.map { |name| subscribe(name) { |event| on_workflow(event) } }
           ].freeze
         end
 
@@ -251,6 +252,18 @@ module Pgbus
           backend.gauge("#{METRIC_PREFIX}pool_available", payload[:available], tags)
         end
 
+        # ── Workflows (issue #540) ────────────────────────────────────────
+
+        def on_workflow(event)
+          WorkflowMetrics.samples(event.name, event.payload).each do |kind, name, value, tags|
+            case kind
+            when :histogram then backend.histogram(name, value, tags)
+            when :counter then backend.increment(name, value, tags)
+            when :gauge then backend.gauge(name, value, tags)
+            end
+          end
+        end
+
         def hostname
           Socket.gethostname
         end

data/lib/pgbus/metrics/workflow_metrics.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Metrics
+    # The pgbus.workflow.* event → metric mapping (issue #540), shared by
+    # Metrics::Subscriber (Prometheus, StatsD) and the AppSignal subscriber so
+    # both backends report the same names and labels:
+    #
+    #   pgbus_workflow_step_duration_seconds{workflow_class, step, outcome}  histogram
+    #   pgbus_workflow_steps_total{workflow_class, step, outcome}            counter
+    #   pgbus_workflows_finished_total{workflow_class}                       counter
+    #   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
+    #
+    # Label values come from code (class, step and exception names), so
+    # their cardinality is bounded; workflow ids never become labels.
+    module WorkflowMetrics
+      EVENTS = %w[
+        pgbus.workflow.step pgbus.workflow_finished pgbus.workflow_paused pgbus.workflow_cancelled
+        pgbus.workflow.stall_detected pgbus.workflow.wait_timed_out pgbus.workflow.gauge
+      ].freeze
+
+      module_function
+
+      # [[kind, name, value, tags], ...] for one event; kind is :histogram,
+      # :counter or :gauge.
+      def samples(event_name, payload)
+        klass = payload[:workflow_class]
+        case event_name
+        when "pgbus.workflow.step" then step_samples(klass, payload)
+        when "pgbus.workflow_finished" then [counter("pgbus_workflows_finished_total", workflow_class: klass)]
+        when "pgbus.workflow_paused"
+          [counter("pgbus_workflows_paused_total", workflow_class: klass, error_class: payload[:error_class])]
+        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
+      end
+
+      def step_samples(klass, payload)
+        tags = { workflow_class: klass, step: payload[:step_name], outcome: payload[:outcome] }.compact
+        samples = [[:counter, "pgbus_workflow_steps_total", 1, tags]]
+        samples.unshift([:histogram, "pgbus_workflow_step_duration_seconds", payload[:duration], tags]) if payload[:duration]
+        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] }]
+        end
+        stuck = Array(payload[:stuck]).map do |row|
+          [:gauge, "pgbus_workflows_stuck", row[:count], { workflow_class: row[:workflow_class], reason: row[:reason] }]
+        end
+        statuses + stuck
+      end
+
+      def counter(name, **tags) = [:counter, name, 1, tags.compact]
+    end
+  end
+end

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

@@ -19,6 +19,7 @@ module Pgbus
       JOB_LOCK_CLEANUP_INTERVAL = 300 # Run job lock cleanup every 5 minutes
       STATS_CLEANUP_INTERVAL = 3600 # Run stats cleanup every hour
       ORPHAN_STREAM_SWEEP_INTERVAL = 3600 # Run orphan stream sweep every hour
+      WORKFLOW_CLEANUP_INTERVAL = 3600 # Delete finished/cancelled workflows past workflow_retention every hour
       TABLE_MAINTENANCE_INTERVAL = Pgbus::TableMaintenance::MAINTENANCE_INTERVAL
 
       # Page size for archive compaction. Each cycle deletes up to this
@@ -57,6 +58,7 @@ module Pgbus
         @last_stream_archive_compaction_at
         @last_outbox_cleanup_at @last_job_lock_cleanup_at @last_stats_cleanup_at
         @last_orphan_stream_sweep_at @last_table_maintenance_at
+        @last_workflow_sweep_at @last_workflow_cleanup_at
       ].freeze
 
       # Outcome of a single maintenance task in a cycle. Lets run_maintenance
@@ -247,6 +249,8 @@ module Pgbus
         sweep_interval = config.streams_orphan_sweep_interval
         results << run_if_due(now, :@last_orphan_stream_sweep_at, sweep_interval) { sweep_orphan_streams } if sweep_interval
         results << run_if_due(now, :@last_table_maintenance_at, TABLE_MAINTENANCE_INTERVAL) { run_table_maintenance }
+        results << run_if_due(now, :@last_workflow_sweep_at, config.workflow_sweep_interval) { sweep_workflows }
+        results << run_if_due(now, :@last_workflow_cleanup_at, WORKFLOW_CLEANUP_INTERVAL) { cleanup_workflows }
         results
       end
 
@@ -388,6 +392,28 @@ module Pgbus
         e
       end
 
+      # Stalled and overdue workflow steps, timed-out waits, and the workflow gauges.
+      def sweep_workflows
+        summary = Workflow::Sweep.repair(config: config)
+        return unless summary && summary.values_at(:stalled, :resent, :timed_out, :fan_outs).compact.any?(&:positive?)
+
+        Pgbus.logger.info do
+          "[Pgbus] Workflow sweep: #{summary[:stalled]} stalled step(s) repaired, #{summary[:resent]} overdue step(s) re-sent, " \
+            "#{summary[:timed_out].to_i} wait(s) timed out, #{summary[:fan_outs].to_i} fan-out(s) resolved"
+        end
+      rescue StandardError => e
+        log_maintenance_failure("Workflow sweep", e)
+        e
+      end
+
+      def cleanup_workflows
+        deleted = Workflow::Sweep.cleanup(retention: config.workflow_retention)
+        Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} finished workflows" } if deleted.positive?
+      rescue StandardError => e
+        log_maintenance_failure("Workflow cleanup", e)
+        e
+      end
+
       def cleanup_stats
         retention = config.stats_retention
         return unless retention&.positive?
@@ -479,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