pgbus 0.9.10 → 0.9.11

data/lib/generators/pgbus/update_generator.rb

@@ -1,50 +1,26 @@
 # frozen_string_literal: true
 
 require "rails/generators"
-require "pgbus/generators/config_converter"
 require "pgbus/generators/migration_detector"
 require "pgbus/generators/database_target_detector"
 
 module Pgbus
   module Generators
-    # Upgrade command with two independent jobs:
-    #
-    #   1. Config conversion: if config/pgbus.yml exists, convert it to
-    #      config/initializers/pgbus.rb using the modern Ruby DSL. Skip
-    #      silently if the initializer already exists or the YAML is
-    #      absent — safe to re-run.
-    #
-    #   2. Migration detection: inspect the live database and add any
-    #      missing pgbus migrations to db/migrate (or db/pgbus_migrate
-    #      if a separate database is configured). Invokes each matching
-    #      sub-generator in-process via Thor's invoke, so this mirrors
-    #      what the user would get running each generator by hand.
+    # Upgrade command: inspect the live database and add any missing pgbus
+    # migrations to db/migrate (or db/pgbus_migrate if a separate database is
+    # configured). Invokes each matching sub-generator in-process via Thor's
+    # invoke, so this mirrors what the user would get running each generator
+    # by hand.
     #
     # Usage:
     #
     #   bin/rails generate pgbus:update
     #   bin/rails generate pgbus:update --dry-run
-    #   bin/rails generate pgbus:update --skip-config
     #   bin/rails generate pgbus:update --skip-migrations
     #   bin/rails generate pgbus:update --database=pgbus
     #   bin/rails generate pgbus:update --quiet
     class UpdateGenerator < Rails::Generators::Base
-      desc "Upgrade pgbus: convert YAML config + add any missing migrations"
-
-      class_option :source,
-                   type: :string,
-                   default: "config/pgbus.yml",
-                   desc: "Path to an existing YAML config to convert (default: config/pgbus.yml)"
-
-      class_option :destination,
-                   type: :string,
-                   default: "config/initializers/pgbus.rb",
-                   desc: "Path to the generated initializer (default: config/initializers/pgbus.rb)"
-
-      class_option :skip_config,
-                   type: :boolean,
-                   default: false,
-                   desc: "Skip the YAML → Ruby initializer conversion step"
+      desc "Upgrade pgbus: add any missing migrations"
 
       class_option :skip_migrations,
                    type: :boolean,
@@ -67,30 +43,6 @@ module Pgbus
                    default: false,
                    desc: "Suppress verbose per-step output"
 
-      def convert_yaml_if_present
-        return if options[:skip_config]
-
-        source_path = File.expand_path(options[:source], destination_root)
-        destination_path = File.expand_path(options[:destination], destination_root)
-
-        unless File.exist?(source_path)
-          log "YAML config not found at #{options[:source]}; skipping config conversion."
-          return
-        end
-
-        if File.exist?(destination_path)
-          log "Initializer already exists at #{options[:destination]}; skipping config conversion."
-          return
-        end
-
-        ruby_source = load_and_convert(source_path)
-        if options[:dry_run]
-          log_change "[dry-run] would create #{options[:destination]}"
-        else
-          create_file destination_path, ruby_source
-        end
-      end
-
       def detect_and_install_missing_migrations
         return if options[:skip_migrations]
 
@@ -172,18 +124,6 @@ module Pgbus
 
       private
 
-      # Wrap converter and YAML errors as Thor::Error so the generator
-      # surfaces them with the standard "in red, no backtrace, exit 1"
-      # behavior. Catches:
-      #   - ConfigConverter::Error (validation, missing file race)
-      #   - Psych::Exception (malformed YAML, disallowed types)
-      #   - Errno::ENOENT / Errno::EACCES (file disappeared / not readable)
-      def load_and_convert(source_path)
-        ConfigConverter.from_yaml(source_path)
-      rescue ConfigConverter::Error, Psych::Exception, Errno::ENOENT, Errno::EACCES => e
-        raise Thor::Error, "Failed to convert #{options[:source]}: #{e.message}"
-      end
-
       def active_record_available?
         defined?(::ActiveRecord::Base) && ::ActiveRecord::Base.respond_to?(:connection)
       end

data/lib/pgbus/client/ensure_stream_queue.rb

@@ -22,7 +22,14 @@ module Pgbus
         full_name = config.queue_name(stream_name)
 
         with_stale_connection_retry do
-          ensure_queue(stream_name)
+          # Create the BARE queue directly. ensure_queue would fan out through
+          # the priority strategy to _p0.._pN under priority_levels>1, leaving
+          # the bare queue — the one the streamer NOTIFYs on and read_after
+          # peeks — uncreated, and the enable_notify_if_needed below would then
+          # raise on the missing bare table. Streams never use priority
+          # sub-queues (issue #310).
+          ensure_pgmq_schema
+          ensure_single_queue(full_name)
 
           # PGMQ's default NOTIFY throttle is 250ms — meant to coalesce
           # high-frequency worker queue inserts. Streams are latency-
@@ -38,6 +45,8 @@ module Pgbus
         # requires a roundtrip and a brief ACCESS SHARE lock on the archive
         # table. Broadcast-per-after_commit loops can hit this 1000x/sec on
         # the same stream, so memoize per-process after the first success.
+        # The StreamQueue registration shares this memo — both are one-time
+        # per stream per process and must both survive a first-broadcast.
         return if @stream_indexes_created[stream_name]
 
         sanitized = QueueNameValidator.sanitize!(full_name)
@@ -52,6 +61,11 @@ module Pgbus
           end
         end
 
+        # Record the physical queue name so maintenance (stream-archive prune,
+        # orphan sweep, compact_archives) and wildcard workers can tell this
+        # queue apart from a job queue. No-ops on unmigrated installs.
+        Pgbus::StreamQueue.record!(full_name)
+
         @stream_indexes_created[stream_name] = true
       end
     end

data/lib/pgbus/client/read_after.rb

@@ -18,7 +18,7 @@ module Pgbus
         sql = build_read_after_sql(sanitized)
 
         rows = synchronized do
-          with_raw_connection do |conn|
+          with_streams_connection do |conn|
             conn.exec_params(sql, [after_id.to_i, limit.to_i]).to_a
           end
         end
@@ -34,7 +34,7 @@ module Pgbus
         sanitized = sanitized_queue(stream_name)
         sql = "SELECT COALESCE(MAX(msg_id), 0) AS max FROM pgmq.q_#{sanitized}"
         synchronized do
-          with_raw_connection do |conn|
+          with_streams_connection do |conn|
             conn.exec(sql).first.fetch("max").to_i
           end
         end
@@ -53,7 +53,7 @@ module Pgbus
           ) AS least
         SQL
         synchronized do
-          with_raw_connection do |conn|
+          with_streams_connection do |conn|
             value = conn.exec(sql).first.fetch("least")
             value&.to_i
           end
@@ -84,9 +84,10 @@ module Pgbus
       # See issues #101 and #104. The comparison is case-insensitive because
       # Postgres downcases unquoted identifiers in its error output, while
       # `sanitized` can contain uppercase characters for GlobalID-keyed streams
-      # (e.g. `pgbus_stream_Z2lkOi8vY29zbW9zL1VzZXIvMQ` from
-      # `pgbus_stream_from Current.user`). A case-sensitive substring match
-      # would miss the downcased relation name and let the exception escape.
+      # (e.g. `pgbus_Z2lkOi8vY29zbW9zL1VzZXIvMQ` from
+      # `pgbus_stream_from Current.user` — stream queues share the job prefix,
+      # see Configuration#queue_name). A case-sensitive substring match would
+      # miss the downcased relation name and let the exception escape.
       #
       # The regex uses `\b` word boundaries so `pgmq.q_<needle>` doesn't
       # accidentally match longer related identifiers like

data/lib/pgbus/client/resizable_pool.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  class Client
+    # Owns the current streams PGMQ::Client behind a Concurrent::AtomicReference
+    # and resizes it by BUILDING A NEW pool, atomically swapping the reference,
+    # then bounded-draining + shutting down the old one (issue #323 spike).
+    #
+    # connection_pool 2.x cannot resize in place (@size is frozen at
+    # construction; only shutdown/reload/available exist), so growing REQUIRES a
+    # new PGMQ::Client + a reference swap.
+    #
+    # DRAIN CORRECTNESS — the load-bearing detail. We do NOT trust
+    # connection_pool's `available == size` as "drained": pgmq-ruby's
+    # #with_connection retries a lost connection (checkout → checkin → checkout
+    # again), so between the two checkouts the connection sits idle in the queue
+    # and `available` momentarily equals `size` while a produce/read is still
+    # mid-flight. Closing the pool in that window makes the retry's checkout raise
+    # PoolShuttingDownError → a genuinely LOST durable broadcast (the
+    # PgBouncer/failover mid-INSERT case). Instead each reader op is bracketed by
+    # an in-flight AtomicFixnum on the CAPTURED pool, and drain waits until THAT
+    # hits zero. This is immune to the internal retry and independent of the
+    # connection_pool version.
+    #
+    # DURABLE BROADCASTS are loss-safe by construction: #produce captures the
+    # Pool once, runs its whole retrying checkout→INSERT→COMMIT→checkin on that
+    # pool, then decrements. Both old and new pools connect to the same Postgres,
+    # so any INSERT commits; and close waits for the captured pool's inflight to
+    # reach zero, so a pool is never shut while a produce is in flight on it.
+    class ResizablePool
+      # The current pool: a PGMQ::Client plus its own in-flight checkout counter.
+      Pool = Data.define(:pgmq, :inflight)
+
+      SwapStats = Data.define(:swap_count, :last_drain_seconds, :last_conns_closed,
+                              :last_from_size, :last_to_size, :last_drained)
+
+      DRAIN_POLL = 0.01 # 10ms
+
+      # `shared:` is accepted for symmetry with the Client's two connection paths
+      # but is not stored — the shared-AR alias guard lives in #close_current via
+      # the `job_pool:` identity check, and #swap is simply never called on the
+      # shared path (Client#resize_streams_pool short-circuits there).
+      def initialize(pgmq, shared:, drain_timeout:, logger:, clock: ::Process) # rubocop:disable Lint/UnusedMethodArgument
+        @ref = Concurrent::AtomicReference.new(new_pool(pgmq))
+        @drain_timeout = drain_timeout
+        @logger = logger
+        @clock = clock
+        @swap_mutex = Mutex.new # serializes swap AND close_current; reads never take it
+        @swap_count = 0
+        @last = nil
+      end
+
+      # Hot path: one volatile load, no lock.
+      def current = @ref.get
+
+      # Bracketed reader ops — inflight decrements only after the WHOLE retrying
+      # call returns (so drain can't close under an in-flight produce/read).
+      def produce(*, **)
+        pool = @ref.get
+        pool.inflight.increment
+        begin
+          pool.pgmq.produce(*, **)
+        ensure
+          pool.inflight.decrement
+        end
+      end
+
+      def with_connection(&)
+        pool = @ref.get
+        pool.inflight.increment
+        begin
+          pool.pgmq.with_connection(&)
+        ensure
+          pool.inflight.decrement
+        end
+      end
+
+      def stats = @ref.get.pgmq.stats
+
+      # Swap in a freshly-built PGMQ::Client, then drain + close the old Pool.
+      def swap(new_pgmq, from_size:, to_size:)
+        @swap_mutex.synchronize do
+          old = @ref.get
+          @ref.set(new_pool(new_pgmq)) # new checkouts now resolve to the new pool
+          drained, secs, closed = drain_and_close(old)
+          @swap_count += 1
+          @last = SwapStats.new(swap_count: @swap_count, last_drain_seconds: secs,
+                                last_conns_closed: closed, last_from_size: from_size,
+                                last_to_size: to_size, last_drained: drained)
+        end
+      end
+
+      # Teardown of the current pool (from Client#close), race-free vs swap.
+      # Skips the close when the current pool aliases the job pool (shared-AR path).
+      def close_current(job_pool:)
+        @swap_mutex.synchronize do
+          pool = @ref.get
+          pool.pgmq.close unless pool.pgmq.equal?(job_pool)
+        end
+      end
+
+      def stats_snapshot
+        @last || SwapStats.new(swap_count: 0, last_drain_seconds: 0.0, last_conns_closed: 0,
+                               last_from_size: nil, last_to_size: nil, last_drained: nil)
+      end
+
+      private
+
+      def new_pool(pgmq)
+        Pool.new(pgmq: pgmq, inflight: Concurrent::AtomicFixnum.new(0))
+      end
+
+      # Bounded drain on the OLD pool's inflight counter, then shutdown. Mirrors
+      # OutboundPump#stop: fixed budget, log-and-abandon, NEVER Thread#kill /
+      # Timeout.timeout. Returns [drained?, wall_secs, conns_closed].
+      def drain_and_close(old)
+        t0 = mono
+        drained = wait_until_drained(old.inflight)
+        # Count connections about to be torn down BEFORE close (after close it's ~0).
+        conns = conns_open(old.pgmq)
+        unless drained
+          @logger.warn do
+            "[Pgbus::ResizablePool] streams pool did not fully drain in " \
+              "#{@drain_timeout}s (inflight=#{old.inflight.value}); shutting down anyway — " \
+              "in-flight connections self-close on checkin"
+          end
+        end
+        old.pgmq.close
+        [drained, mono - t0, conns]
+      rescue StandardError => e
+        @logger.error { "[Pgbus::ResizablePool] old pool teardown failed: #{e.class}: #{e.message}" }
+        [false, mono - t0, 0]
+      end
+
+      def wait_until_drained(inflight)
+        deadline = mono + @drain_timeout
+        loop do
+          return true if inflight.value <= 0
+          return false if mono >= deadline
+
+          sleep(DRAIN_POLL) # NOT Timeout.timeout — Pgbus/NoRubyTimeout cop
+        end
+      end
+
+      # size - available = connections currently open (created & not idle-in-queue).
+      def conns_open(pgmq)
+        stats = pgmq.stats
+        [stats[:size] - stats[:available], 0].max
+      rescue StandardError
+        0
+      end
+
+      # Qualify ::Process — Pgbus::Process (the worker/supervisor namespace)
+      # shadows the top-level constant here.
+      def mono = @clock.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -7,6 +7,7 @@ require_relative "client/read_after"
 require_relative "client/ensure_stream_queue"
 require_relative "client/notify_stream"
 require_relative "client/connection_health"
+require_relative "client/resizable_pool"
 
 module Pgbus
   class Client
@@ -59,6 +60,12 @@ module Pgbus
         # operations through a mutex.
         @pgmq = PGMQ::Client.new(conn_opts, pool_size: 1, pool_timeout: config.pool_timeout)
         @pgmq_mutex = Mutex.new
+        # No dedicated streams pool on this path: a second PGMQ::Client would
+        # still funnel through the same non-thread-safe AR raw_connection.
+        # Stream publish + replay share the single serialized connection —
+        # @streams_pgmq aliases @pgmq so the code paths are uniform, and
+        # #with_streams_connection falls back to with_raw_connection.
+        @streams_pgmq = @pgmq
       else
         # With a String URL or Hash params, pgmq-ruby creates its own dedicated
         # PG::Connection per pool slot — no shared state with ActiveRecord.
@@ -75,10 +82,44 @@ module Pgbus
         conn_opts = apply_connection_bounds(conn_opts)
         @pgmq = PGMQ::Client.new(conn_opts, pool_size: config.resolved_pool_size, pool_timeout: config.pool_timeout)
         @pgmq_mutex = nil
+        # Dedicated streams pool (issue #315): isolates the durable-stream
+        # publish INSERT (#send_stream_message) and the dispatcher's per-wake
+        # replay reads (#read_after) from the job pool, so a saturated worker
+        # pool can't delay a broadcast on pool checkout, and each wake reuses a
+        # persistent connection instead of a fresh PG.connect per call. Its own
+        # PGMQ::Client → its own connection_pool, sized independently of worker
+        # thread counts.
+        # Build the streams pool from streams_connection_options (which defaults
+        # to connection_options but honors streams_database_url/host/port for a
+        # separate/direct streams DB — issue #315), bounds-applied, and tagged
+        # with a per-process application_name so the autoscaler can count peer
+        # processes from pg_stat_activity (issue #323 P1/P2). Snapshot it so a
+        # hot-swap rebuilds a byte-identical pool at a new size.
+        @streams_conn_opts = tag_application_name(
+          apply_connection_bounds(config.streams_connection_options)
+        )
+        @streams_pgmq = PGMQ::Client.new(@streams_conn_opts, pool_size: config.streams_pool_size,
+                                                             pool_timeout: config.streams_pool_timeout)
       end
 
+      # Wrap the streams pool so its live reference can be atomically hot-swapped
+      # to a new size under load without losing broadcasts or leaking connections
+      # (issue #323 spike; #resize_streams_pool). All streams-pool access goes
+      # through this — see #streams_pool. Default behavior with no swap is
+      # byte-identical (one AtomicReference read + a counter bump per op).
+      @streams_pool = ResizablePool.new(
+        @streams_pgmq,
+        shared: @shared_connection,
+        drain_timeout: config.streams_pool_timeout + 1.0,
+        logger: Pgbus.logger
+      )
+
       @queues_created = Concurrent::Map.new
       @stream_indexes_created = Concurrent::Map.new
+      # Guards the one-time build of the publisher autoscale trigger (issue #323).
+      # NOT @pgmq_mutex — that is nil on the dedicated path (the only path the
+      # trigger exists on), so it wouldn't serialize concurrent first-publishers.
+      @streams_trigger_mutex = Mutex.new
       @queue_strategy = QueueFactory.for(config)
       @schema_ensured = schema_ensured
       @connection_health = ConnectionHealth.new(
@@ -240,6 +281,38 @@ module Pgbus
       end
     end
 
+    # Durable stream broadcast. Unlike #send_message, this ALWAYS targets the
+    # bare queue (config.queue_name) and never the priority strategy's
+    # _p0.._pN sub-queues: streams are delivered by a non-consuming peek
+    # (read_after) on the bare queue, and the streamer LISTENs on the bare
+    # channel, so a broadcast routed to _p1 would never reach the browser
+    # (issue #310). ensure_stream_queue creates the bare queue + NOTIFY
+    # trigger + archive index, mirroring this bare-name write path.
+    def send_stream_message(stream_name, payload, headers: nil, delay: 0)
+      target = config.queue_name(stream_name)
+      # Capture the produced msg_id — it is this method's return value (callers
+      # like Stream#broadcast rely on it), so the autoscale trigger below must NOT
+      # become the last expression.
+      msg_id = Instrumentation.instrument("pgbus.client.send_message", queue: target) do
+        with_stale_connection_retry do
+          ensure_stream_queue(stream_name)
+          # Publish through the dedicated streams pool (issue #315) so a
+          # saturated job pool can't block a broadcast on pool checkout. On the
+          # shared-AR path @streams_pgmq aliases @pgmq and synchronized still
+          # serializes on the mutex.
+          synchronized do
+            streams_pool.produce(target, serialize(payload), headers: headers && serialize(headers), delay: delay)
+          end
+        end
+      end
+      # Opportunistically autoscale the streams pool from the publish path so a
+      # pure-publisher process (no streamer) still grows under a broadcast storm
+      # (issue #323 follow-up). Throttled + fail-soft — never delays or breaks the
+      # broadcast; nil (a no-op) unless autoscale is on and the pool is dedicated.
+      streams_pool_trigger&.maybe_check
+      msg_id
+    end
+
     def send_batch(queue_name, payloads, headers: nil, delay: 0)
       full_name = config.queue_name(queue_name)
       serialized, serialized_headers = serialize_batch(payloads, headers)
@@ -446,6 +519,16 @@ module Pgbus
       {}
     end
 
+    # Same shape as #pool_stats but for the dedicated streams pool (issue #315).
+    # On the shared-AR path @streams_pgmq aliases @pgmq, so this reports the job
+    # pool's counters — accurate, since streams share that connection there.
+    def streams_pool_stats
+      streams_pool.stats.merge(pool_timeout: config.streams_pool_timeout)
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus::Client] streams_pool_stats unavailable: #{e.class}: #{e.message}" }
+      {}
+    end
+
     def list_queues
       with_stale_connection_retry do
         synchronized { @pgmq.list_queues }
@@ -642,7 +725,47 @@ module Pgbus
     end
 
     def close
-      synchronized { @pgmq.close }
+      # Stop the publisher autoscale executor (if one was ever built) so its
+      # background thread doesn't leak (issue #323). Outside `synchronized` — it
+      # takes no pool lock and shutdown waits on a possibly-running check.
+      @streams_pool_trigger.shutdown if defined?(@streams_pool_trigger) && @streams_pool_trigger
+      synchronized do
+        @pgmq.close
+        # Close the CURRENT streams pool too (issue #315) so its connections
+        # don't leak. close_current reads the live (possibly hot-swapped, #323)
+        # pool once under the swap mutex and skips it when it aliases @pgmq (the
+        # shared-AR path) so we don't double-close the same pool.
+        @streams_pool.close_current(job_pool: @pgmq)
+      end
+    end
+
+    # Opt-in hot-swap of the dedicated streams pool to a new size (issue #323
+    # spike). Builds a fresh PGMQ::Client at new_size with the SAME bounds-applied
+    # connection options, atomically swaps the live reference, then drains +
+    # closes the old pool (bounded, never Thread#kill). NOT called automatically —
+    # there is no control loop here; a caller triggers it explicitly.
+    #
+    # No-op on the shared-AR (Proc) path (the streams pool aliases the job pool,
+    # which is non-thread-safe and forced to pool_size 1 — swapping it would
+    # corrupt the job pool), and no-op when the size is unchanged.
+    #
+    # @return [ResizablePool::SwapStats] on a swap, or {swapped: false, reason:}
+    def resize_streams_pool(new_size)
+      raise ArgumentError, "new_size must be a positive integer" unless new_size.is_a?(Integer) && new_size.positive?
+      return { swapped: false, reason: :shared_connection } if @shared_connection
+      return { swapped: false, reason: :unchanged } if streams_pool.stats[:size] == new_size
+
+      from_size = streams_pool.stats[:size]
+      new_pgmq = PGMQ::Client.new(
+        @streams_conn_opts, pool_size: new_size, pool_timeout: config.streams_pool_timeout
+      )
+      @streams_pool.swap(new_pgmq, from_size: from_size, to_size: new_size)
+    end
+
+    # Accumulated streams-pool swap telemetry (issue #323) — for the bench and a
+    # future control loop. Zero-valued before any swap.
+    def streams_swap_stats
+      @streams_pool.stats_snapshot
     end
 
     private
@@ -776,6 +899,22 @@ module Pgbus
       conn&.close if owned
     end
 
+    # Yields a PG connection from the dedicated streams pool for the streamer's
+    # replay reads (read_after / stream_current_msg_id / stream_oldest_msg_id).
+    # On the dedicated (String/Hash) path this checks out a persistent pooled
+    # connection — no fresh PG.connect per call (issue #315). On the shared-AR
+    # (Proc) path there is no separate pool (@streams_pgmq aliases @pgmq and
+    # points at the non-thread-safe AR raw_connection), so we fall back to
+    # with_raw_connection, which reuses that same shared connection. Callers
+    # already wrap this in `synchronized`, so the shared path stays serialized.
+    def with_streams_connection(&)
+      if @shared_connection
+        with_raw_connection(&)
+      else
+        streams_pool.with_connection(&)
+      end
+    end
+
     def ensure_single_queue(full_name)
       return if @queues_created[full_name]
 
@@ -871,6 +1010,40 @@ module Pgbus
       end
     end
 
+    # The ResizablePool wrapping the streams pool. All streams-pool reads
+    # (produce / with_connection / stats) go through it so the underlying
+    # PGMQ::Client can be atomically hot-swapped to a new size (issue #323).
+    attr_reader :streams_pool
+
+    # Lazily-built publisher-side autoscale trigger (issue #323). nil (a no-op)
+    # unless streams_pool_autoscale is on AND this is the dedicated-connection
+    # path (resize is a no-op on the shared-AR path). Built once — on the first
+    # publish, then reused. Runs its headroom query through the job pool (@pgmq),
+    # so it never competes with the streams pool it resizes.
+    #
+    # Double-checked under @streams_trigger_mutex so concurrent first-publishers
+    # (the integration spec fires 8) can't each build their own trigger — that
+    # would give each thread a trigger with its own throttle, defeating the
+    # once-per-interval throttle on the first window. Steady-state publishes hit
+    # the fast `defined?` path with no lock.
+    def streams_pool_trigger
+      return @streams_pool_trigger if defined?(@streams_pool_trigger)
+
+      @streams_trigger_mutex.synchronize do
+        return @streams_pool_trigger if defined?(@streams_pool_trigger)
+
+        @streams_pool_trigger =
+          if config.streams_pool_autoscale && !@shared_connection
+            autoscaler = Streams::PoolAutoscaler.new(client: self, config: config)
+            Streams::PoolTrigger.new(
+              autoscaler: autoscaler, job_pool: @pgmq,
+              interval: config.streams_pool_autoscale_interval,
+              application_name_prefix: config.streams_application_name
+            )
+          end
+      end
+    end
+
     # Substrings that indicate the pooled PG::Connection was already dead
     # *before* pgmq-ruby tried to use it — typically killed by a connection
     # pooler (PgBouncer server_idle_timeout / client_idle_timeout), an admin
@@ -1100,6 +1273,32 @@ module Pgbus
     # read_timeout is already failing — and keeps a single server-side mechanism.
     #
     # Returns conn_opts unchanged when read_timeout is nil (bounding disabled).
+    # Stamp a per-process application_name on the streams-pool connection options
+    # so the autoscaler can count peer processes via
+    # `pg_stat_activity.application_name LIKE '<prefix>_%'` (issue #323 P1). The
+    # suffix is the pid so DISTINCT application_name is an exact process count.
+    # application_name is a cosmetic session GUC — appending it can't break the
+    # connection. The Proc (shared-AR) path never reaches here.
+    def tag_application_name(conn_opts)
+      name = "#{config.streams_application_name}_#{::Process.pid}"
+      case conn_opts
+      when Hash
+        conn_opts.merge(application_name: name)
+      when String
+        # Two libpq string forms (mirrors #append_connection_bounds): URI form
+        # carries params as `?key=value&…` query pairs; key=value conninfo form
+        # is space-separated. Appending wins over any earlier application_name.
+        if conn_opts.start_with?("postgres://", "postgresql://")
+          separator = conn_opts.include?("?") ? "&" : "?"
+          "#{conn_opts}#{separator}application_name=#{name}"
+        else
+          "#{conn_opts} application_name=#{name}"
+        end
+      else
+        conn_opts
+      end
+    end
+
     def apply_connection_bounds(conn_opts)
       timeout = config.read_timeout
       return conn_opts unless timeout&.positive?