pgbus 0.9.11 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56605f0cc86326e66b73d13d9090bbcdc522b9ee6e571dd19f62f02aadce3dac
-  data.tar.gz: e53deb0e75aec959f4c0bf54d2d969d52899d57c59ca59e0441f989d897745b2
+  metadata.gz: 44b8e6016eb94d129ba3f90831ee6e3f8eb213c928e61766c35fa4641f0a518b
+  data.tar.gz: d35475deb1eaaf59e893c7096b10bc85498482f5940fc099e5add48af54aecbd
 SHA512:
-  metadata.gz: 3bdbd54ebc2c5d414d5e85212adee43bea5645d4422397e1b5c41e41a63b19fb7695cbd32da7096c3455c3ff6f8a4afab2a7ad510d443d9b5cc561abdd01043a
-  data.tar.gz: 4cb472bbaad4c5052f732cfe452c07fc725ac739afceca8cd4e58a05a9785950e64b1efe050f6d97a245cd94fe0b85218ee1f616b753d552e113a498aa135289
+  metadata.gz: db2122fe97f2b77dd6812e5e9a5264850b4eb84ff3c6094cc2c0e11a148989fa3ae502664e040da26b1ea1bf11b764c2b1f9659a58f9d4a6b663be54c1027cba
+  data.tar.gz: 597210a0238131f0a7912b0cf135dc4d89ce66ab830354dca3b3805dbc70a9ccbd2106830dea85b17c68be73fb79868ff9c43d27813e84e6f457dfbe996107d3

data/CHANGELOG.md

@@ -2,11 +2,17 @@
 
 ### Breaking Changes
 
+- **`config.validate!` now rejects malformed values for 12 core config keys at boot instead of failing deep in a worker or silently misbehaving (issue #335).** Before the 1.0 surface freeze, these headline job-path keys had **zero** validation while streams keys had 14 checks — so a bad value surfaced as a crash inside a worker/dispatcher/poller/scheduler thread, per-enqueue, or by silently corrupting every derived queue name / leaving the dashboard open. `Pgbus.configure` (eager-validating by default) now raises `Pgbus::ConfigurationError` naming the key for: the worker-recycling trio `max_jobs_per_worker`/`max_memory_mb`/`max_worker_lifetime` (positive number or `nil` to disable); the intervals `dispatch_interval`/`outbox_poll_interval`/`recurring_schedule_interval` (positive number); `outbox_batch_size` (positive integer); `default_priority` (non-negative integer — `0` is a valid level); `queue_prefix`/`default_queue` (non-empty String — an empty prefix silently produced malformed queue names); `web_auth` (a callable or `nil` — a non-callable silently left the dashboard open); `error_reporters` (an Array); and `connects_to` (a Hash or `nil` — previously a malformed value raised a raw `TypeError` deep in engine boot). This only rejects configuration that was already broken; if a `Pgbus.configure` block set one of these to an invalid value it will now fail loudly at boot (the intended pre-freeze tightening). Set `config.eager_validation = false` to defer. Refs #335, #282.
+- **`config.streams_queue_prefix` is removed (issue #335).** It had been an inert no-op since #308 — stream queues are named like job queues (`#{queue_prefix}_<name>`) and identified via the `pgbus_stream_queues` registry, so the prefix affected nothing — yet it was still a writable accessor documented as "Prefix for stream queues" (false). Rather than carry a dead, misleadingly-documented key into the 1.0 semver promise, the accessor is **removed**: `c.streams_queue_prefix = ...` now raises `NoMethodError`. **Action:** delete the line from your initializer — it never did anything. Refs #335, #308.
+- **`ensures_uniqueness strategy: :until_executed` with no `key:` now raises when the job is enqueued *with arguments* — the class-name default silently collapsed per-record jobs (issue #333).** Without an explicit `key:`, the uniqueness key defaulted to the job class name. For a job that takes per-record arguments (`ImportOrderJob.perform_later(order_id)`), every distinct `order_id` resolved to the same class-name key and collapsed into ONE per-class singleton — order 1 and order 2 shared a lock, so the second was silently discarded/rejected — with no warning. The guard is at **resolve time, argument-aware**: a no-key `:until_executed` job enqueued **with arguments** now raises `ArgumentError` naming the collapse and pointing at the upgrade guide; **a no-argument job keeps the class-name default** (a legitimate "one logical instance at a time" — e.g. a recurring `CleanupJob` that must not overlap itself — is unaffected). `:while_executing` is unaffected (it acquires per-invocation at execution start, not by class-name identity at enqueue). Fix: pass `key: ->(*args) { "job-#{args.first}" }` on any argument-taking `:until_executed` job. Refs #333.
 - **YAML config (`config/pgbus.yml`) is removed for 1.0 — the Ruby initializer is the only config surface.** Ruby was always the real config surface (every production setup is a `Pgbus.configure` initializer); `config/pgbus.yml` was only ever a legacy convenience, and pre-1.0 is the last low-risk moment to drop it before the config shape becomes a compatibility promise. Concretely: the engine no longer loads `config/pgbus.yml` at boot (the `pgbus.configure` initializer and `Pgbus::ConfigLoader` are deleted); `rails generate pgbus:install` generates `config/initializers/pgbus.rb` (done for 1.0, see below); and `rails generate pgbus:update` no longer converts YAML → initializer (`Pgbus::Generators::ConfigConverter`, its `--source`/`--destination`/`--skip-config` options, and the `pgbus.yml.erb` template are deleted) — `pgbus:update` now only detects and installs missing migrations. **If you still have a `config/pgbus.yml`, it is no longer loaded** — the engine warns once at boot (pointing at the docs) so the inert file doesn't quietly diverge from your real config. Port its settings into `config/initializers/pgbus.rb` as a `Pgbus.configure` block and delete the YAML; the last release that auto-converts it via `pgbus:update` is 0.9.x, so run that conversion (or port by hand) **before** upgrading to 1.0. The recurring-tasks YAML (`config/recurring.yml`, `Pgbus::Recurring::ConfigLoader`) is a separate surface and is unchanged. Refs #317.
 - **The error hierarchy is unified under `Pgbus::Error` for the 1.0 API freeze.** Several call sites raised bare stdlib errors that no `rescue Pgbus::Error` could catch, freezing an inconsistent contract into 1.0. Now: **`Configuration#validate!` and every config setter raise `Pgbus::ConfigurationError`** (was `ArgumentError`) — this is the one that can break existing code: a `rescue ArgumentError` around `Pgbus.configure` or a boot-time config read will no longer catch config failures; switch to `rescue Pgbus::Error` (or `rescue Pgbus::ConfigurationError`). The ActiveJob adapter's `perform_all_later` msg_id-count mismatch now raises **`Pgbus::EnqueueError`** (new, was `RuntimeError`); `ExecutionPools::AsyncPool` shutdown/at-capacity raises now use **`Pgbus::ExecutionPoolError`** (new, was `RuntimeError`); `Serializer#locate_global_id` GlobalID rejections raise **`Pgbus::SerializationError`** (was `ArgumentError`). Three error classes that bypassed the base — `PgmqSchema::VersionNotFoundError` and `Streams::SignedName::InvalidSignedName`/`MissingSecret` — are re-parented under `Pgbus::Error`. Three classes that reject a malformed *argument shape* — `Configuration::CapsuleDSL::ParseError`, `Streams::Cursor::InvalidCursor`, `Streams::StreamNameTooLong` — **deliberately stay `ArgumentError` subclasses**; the policy ("argument-shape errors are `ArgumentError`, operational errors are `Pgbus::Error`") is documented in `lib/pgbus.rb` and pinned by `spec/pgbus/error_hierarchy_spec.rb`. Messages are unchanged. Refs #282.
 
 ### Added
 
+- **`Pgbus::Streams::PhlexHelpers` — a Phlex-includable `pgbus_stream_from`, and `Pgbus.stream_name_budget` (issue #334).** Two small helpers that stop consuming apps reimplementing pgbus glue. (1) `pgbus_stream_from` is a Rails view helper, so a Phlex component couldn't call it without hand-registering an output-helper macro (phlex-rails ships no `Phlex::Rails::Helpers::PgbusStreamFrom`). `include Pgbus::Streams::PhlexHelpers` now bridges it exactly like phlex-rails' own `TurboStreamFrom`. phlex-rails stays an **optional** dependency — the module references its `HelperMacros` and is loaded on demand (`require "pgbus/streams/phlex_helpers"`), never eagerly. (2) `Pgbus.stream_name_budget` exposes the maximum stream-name length (the pgmq queue-name cap minus the queue prefix) so apps size/truncate stream identifiers up front instead of hand-computing `MAX_QUEUE_NAME_LENGTH - queue_prefix.length - 1` at every call site. Refs #334.
+- **`EventBus::Registry#setup_all!(safe: true)` — a boot/rake-safe way to eagerly set up event subscribers (issue #334).** Calling `setup_all!` opens a PGMQ connection per subscriber (to create its queue + bind its topic), which is wrong during a `db:`/schema rake task (a live connection blocks `DROP DATABASE`) and crashes boot if the database isn't up yet — so apps wrapped it in a hand-rolled multi-class rescue plus a rake-task skip. `setup_all!(safe: true)` bakes that in: it skips entirely in a schema/asset rake context and swallows a connection error with a warning instead of raising. The default `setup_all!` is unchanged (raises). Refs #334.
+- **Connection-pooler safety (`config.require_primary`, `config.connection_guc_mode`) — pgbus is now correct-and-loud behind a transaction/read-write-splitting pooler instead of silently stalling (issue #332).** Three linked fixes. (1) **Primary affinity:** a read/write-splitting pooler (pgdog/pgcat) can route pgmq's VOLATILE `read`/`archive`/`delete` to a read replica, where workers read nothing (`read_ct=0`) and jobs stop with a **healthy heartbeat** — the supervisor watchdog keys on loop advancement, not read progress, so nothing surfaced the stall. The job read path had zero primary-affinity defense (only the LISTEN/streamer paths validated the primary via `PrimaryValidator`). Setting `config.require_primary = true` (default **false** — a single-primary deployment is byte-identical) makes `verify_connection!` reject a connection that lands on a replica (`pg_is_in_recovery() => t`) at supervisor boot, raising a clear `ConfigurationError` instead of forking children that read nothing. (2) **GUC forwarding:** pgbus's AR-config extraction dropped database.yml's `variables:` block, so `client_min_messages` (and any GUC) never reached pgmq's dedicated raw connections (NOTICE flooding that three consuming apps hand-patched via `connection_params`). GUCs are now forwarded, on both the AR-extracted and explicit-`connection_params` paths, by `config.connection_guc_mode`: `:options` (default) bakes them into the libpq `options` STARTUP param (byte-compatible with today for the read-timeout `statement_timeout`, now also carrying `variables:`), while `:session` applies them via post-connect `SET` on a fresh connection instead — for a transaction-mode PgBouncer that **rejects** the `options` startup param with a FATAL. `pgbus doctor` gains a ninth check ("Primary affinity") that warns (never fails) when the job connection is currently on a replica, naming the direct-port remediation. DB-gated integration tests prove both GUC modes round-trip a forwarded GUC and that `require_primary` verifies on a real primary. Refs #332.
 - **Job-burst tuning guidance + gate benchmark (`rake bench:job_burst`), and a decision NOT to autoscale the job pool (issue #323 phase 3).** Following the issue's measure-first mandate, `benchmarks/job_burst_bench.rb` sweeps worker thread count under a job burst in two connection regimes (pool matched to threads vs. pool fixed small). Measured finding: a job holds a pgmq connection only for the `read_batch` + `archive` round-trip (not the job body), so **the DB connection pool is the hard burst ceiling, not the thread count** — in the fixed-pool regime `peak_busy` never exceeds `pool_size` no matter how many threads run (extra threads just queue on checkout, latency climbs, throughput plateaus), while matching the pool to the thread count scales throughput ~linearly (≈8× from 2→16). The conclusion — issue #323's explicitly sanctioned outcome — is that **elastic job threads on a fixed connection pool cannot help**, so pgbus does *not* autoscale the job execution pool; the fix for job bursts is **static headroom**: raise `threads` (and let `pool_size` follow, or keep it ≥ `threads`). Documented in the Performance & tuning docs. The streams-pool autoscaling below stays the elastic story where it *does* pay off (the streams pool's connection cost genuinely scales with its size). Refs #323.
 - **Fan-out writer throughput gate benchmark (`writer_burst_bench.rb`), and a decision NOT to make the writer pool elastic (issue #323 phase 1).** Following the issue's measure-first mandate, `benchmarks/writer_burst_bench.rb` drives a sustained fan-out burst (a fleet of connections × many wakes) through the `OutboundPump` while sweeping `streams_writer_threads`, across fast/typical socket-write profiles. Measured finding: throughput scales ~linearly with writer count (≈6× from 2→16) — but that is generic parallelism (N workers finish N independent blocking writes ~N× faster), which argues for the **existing static `streams_writer_threads` knob**, not for elastic writers: a fixed-N sweep can't demonstrate the *spikiness* that would make a static count wasteful enough to justify dynamic resize, and the genuinely harmful case (a slow/congested client) is already **shed** by the #320/#322 fan-out deadline + mark-dead path rather than absorbed by scaling writers. Given the elastic-writer rewrite is the issue's highest-risk phase (it would touch the ordering/cursor invariant #321's whole review exists to protect — mis-sizing risks out-of-order SSE frames), the conclusion — issue #323's sanctioned outcome — is that pgbus does **not** autoscale the writer pool; the fan-out-throughput knob is **static `streams_writer_threads`, sized for your peak fan-out fleet**. Documented in the Performance & tuning docs. Refs #323.
 - **Self-tuning elastic streams-pool autoscaling (`config.streams_pool_autoscale`, opt-in, default off).** The dedicated streams pool (durable-broadcast publish + dispatcher replay reads) is a fixed `streams_pool_size` (default 5); under a genuine burst of SSE clients it saturates, and a saturated pool *serialises* replay reads (it doesn't error — the checkout waits; see #324), slowing fan-out. Setting `config.streams_pool_autoscale = true` runs a **periodic maintenance check** (default every 5 minutes, `config.streams_pool_autoscale_interval`) that **grows the streams pool into a fair share of live Postgres connection headroom** while it's saturated and **shrinks it back to `streams_pool_size`** when the burst passes — with no connection-count target to tune: every threshold derives from live `max_connections`. The check adds **no extra connection and no extra thread** — it's a lightweight `pg_stat_activity` query that runs on the streamer's *existing idle LISTEN connection* (a pghero-`capture_query_stats`-style periodic task, run on the listener thread in its health-check window). It counts peer stream processes by a per-process `application_name` tag (`config.streams_application_name`, default `"pgbus_streams"`), and each process grows only into its own fair share of free connections (`free / peers`, claiming ¼, bounded by a per-grow step and half the remaining headroom) so N forked processes provably can't collectively exhaust the database — even in a synchronized cold-boot herd. If the database runs *critically* low on free connections, every process **emergency-shrinks to baseline immediately**, overriding the saturation signal (protecting the DB wins). `config.streams_pool_max` is an **optional** hard per-process ceiling (`nil` = the dynamic fair share is the cap). No per-sample hysteresis or cooldown is needed — the slow cadence is itself the debounce: one grow (or shrink) step per check, and a sustained burst converges over a few checks. Built on the #325 hot-swap primitive; the decision object is a pure function (no thread, no connection), DB-free unit-tested (scripted headroom, incl. convergence-across-checks and emergency-shrink), with a DB-gated integration test proving real grow/shrink/emergency and a `rake bench:pool_autoscale` benchmark (check cost ~0.3 ms; grow-under-saturation `3→7→10`). **Two prerequisite fixes ship with it:** streams-pool connections are now tagged with a per-process `application_name`, and the streams pool is now built from `streams_connection_options` (honoring `streams_database_url`/host/port) rather than the job-database options — the latter a latent wrong-DB bug in the existing streams pool that only surfaced with a separate streams database. Default-off = byte-identical (the Listener runs no maintenance). A pure-*publisher* worker process (no streamer, only `send_stream_message`) autoscales too: each publish opportunistically triggers the same check, throttled to at most once per `streams_pool_autoscale_interval` across all publisher threads (a lock-free compare-and-set claims the window). The publish thread does only that CAS and then hands the work to a background single-worker executor — it never runs the `pg_stat_activity` query or the resize inline (off the hot path), and a quiet process spawns no thread. The query runs through the *job* pool (so it never competes with the streams pool it grows), and the publisher decision is **grow-only**: it grows under its own publish pressure and emergency-shrinks on DB exhaustion, but leaves normal idle shrink to the streamer/consumer that sees the sustained-idle picture. Fail-soft throughout, so a broadcast never fails on a telemetry query. For steady load, a larger static `streams_pool_size` remains the simpler choice — autoscaling earns its keep under genuinely bursty streams traffic. `PoolAutoscaler` lives in `Pgbus::Streams::` (it is a streams-pool controller, not web-specific). Refs #323.
@@ -26,6 +32,11 @@
 
 ### Fixed
 
+- **`config.log_format` no longer breaks `ActiveSupport::TaggedLogging` — tags are preserved instead of dropped, and `logger.tagged` no longer raises (issue #334).** TaggedLogging works by extending the logger's formatter instance with a module that prepends the current tags. Installing a fresh pgbus formatter (`LogFormatter::JSON`/`Text`) stripped that extension, so `logger.tagged("req-42") { ... }` dropped the tag — and, worse, raised `NoMethodError: undefined method 'tagged'` on the pgbus formatter (a deploy-breaker several apps hit, then worked around with a dedicated `$stdout` logger). `log_format=` now re-extends the replacement formatter with `ActiveSupport::TaggedLogging::Formatter` when the previous one carried it, so tagging keeps working. Refs #334.
+- **The "Dashboard is accessible without authentication" warning is no longer a false positive when a gating `base_controller_class` is set (issue #334).** The warning fired whenever `web_auth` was nil, ignoring that a non-default `base_controller_class` (e.g. an `AdminController` with its own `before_action`) already gates the dashboard — so apps set a redundant `web_auth` lambda purely to silence the log line. The warning now stays quiet when `base_controller_class` is anything other than the default `::ActionController::Base`. Refs #334.
+- **`retry_on` on an `:until_executed` job no longer dead-letters the job instead of retrying (issue #333).** The uniqueness key is released only on success or DLQ, but ActiveJob's `retry_on` re-enqueues from *inside* `perform_now` (after incrementing `executions`), while the executor still holds the key. That retry re-enqueue hit the job's own still-held key, was rejected as a duplicate (`JobNotUnique` under `on_conflict: :reject`), and the original message dead-lettered — so a job with both `ensures_uniqueness :until_executed` and `retry_on` lost its retry and DLQ'd on the first transient failure. A retry re-enqueue (`executions > 0`) is now recognized as the same logical job re-acquiring its own key and is allowed through; the existing key row correctly stays held until the job finally succeeds or dead-letters. Cross-job uniqueness (a genuine fresh duplicate, `executions == 0`) is still rejected. Proven end-to-end with a DB-gated integration test (fail-once-then-succeed runs to success exactly once, no `JobNotUnique`, no DLQ, key cleaned up). Refs #333.
+- **A wildcard (`queues: ['*']`) worker no longer adopts event-bus subscriber queues and dead-letters the events (issue #333).** Event-subscriber queues share the job namespace (`#{queue_prefix}_<handler>`) but carry event payloads, not ActiveJob jobs. `resolve_wildcard_queues` excluded only `_dlq` and stream queues, so a wildcard worker claimed event queues too, handed each event to the ActiveJob executor, failed to deserialize it, and DLQ-moved it out of the consumer's reach — forcing apps that run the event bus to hand-maintain an explicit queue list. Wildcard resolution now also excludes every registered event-subscriber queue (new `EventBus::Registry#event_queue_names`), mirroring the existing stream-queue exclusion. Refs #333.
+- **A pooler-deaf NOTIFY listener no longer raises the worker poll floor to 15s — worse latency than a plain no-NOTIFY deployment (issue #332).** pgbus already detects a transaction-mode pooler / replica LISTEN connection with a self-NOTIFY probe (`NotifyProbe`) and logs a loud, actionable error, but the probe's boolean result was **discarded**: a live-but-deaf listener still reported `running? == true`, so `Worker#wake_timeout` treated it as a healthy NOTIFY source and raised the empty-fetch poll floor to `NOTIFY_FALLBACK_POLL_SECONDS` (15s) — behind a pooler the loop would then sleep up to 15s between polls while jobs sat ready. `NotifyListener` now records the probe result and exposes `delivering?`; `wake_timeout` treats a non-delivering listener as absent and keeps polling at the fast `polling_interval` until a direct-port connection is configured. The streamer path needed no change — its listener already waits on the short `streams_listen_health_check_ms` and has no equivalent 15s ceiling. Refs #332.
 - **The dispatcher no longer logs a scary `Concurrency cleanup failed: ... terminating connection due to administrator command` WARN when an idle DB connection is killed between maintenance cycles.** The dispatcher is a long-lived loop that queries the DB on coarse intervals (concurrency cleanup every 300s, most tasks hourly) and, until now, kept its pooled ActiveRecord connection leased across the idle sleep. When the server terminated that idle backend — routine in **local development** (a Postgres restart, `rails db:migrate` calling `pg_terminate_backend` on idle backends, foreman/overmind restarting the DB) — the next cycle reused the dead socket and *every* maintenance task raised `PG::ConnectionBad` with PostgreSQL's `terminating connection due to administrator command` text, surfaced as an alarming WARN even though the process was healthy and self-heals on the next tick. Two changes: (1) `run_maintenance` now returns every leased AR connection to the pool after each cycle (`clear_active_connections!`, mirroring the Streamer's existing `release_ar_connections`), so an idle backend is never reused — the next cycle checks out afresh and AR's `verify!`-on-checkout transparently discards a dead socket and reconnects; (2) every maintenance task's failure log now routes through `log_maintenance_failure`, which recognizes the terminated-idle-connection signal and logs a calm INFO ("reconnecting on the next cycle") instead of a WARN. Non-connection failures still WARN unchanged, and maintenance backoff is unaffected (a self-healing cycle resets the failure streak on the next successful reconnect).
 - **`priority_levels > 1` no longer silently breaks durable streams.** With job priority enabled, `QueueFactory.for` selects `PriorityStrategy`, and `Client#send_message` routes *every* send — including durable stream broadcasts (which pass no `priority:`) — to a `_p<default_priority>` sub-queue. But the streamer LISTENs and replays exclusively on the **bare** `pgmq.q_<stream>` queue (`read_after`, `notify_stream`), so the broadcast never reached the browser; on a fresh DB, `ensure_stream_queue` also raised `PG::UndefinedTable` because `ensure_queue` created only `_p0.._pN`, never the bare table the NOTIFY trigger and archive index attach to. Durable broadcasts now go through a dedicated `Client#send_stream_message` that always targets the bare queue, and `ensure_stream_queue` creates the bare queue directly via `ensure_single_queue` — both independent of the priority strategy, mirroring the bare-name read path. Streams are delivered by a non-consuming peek; priority sub-queues are meaningless for them. Ephemeral broadcasts (the default mode) were never affected. Refs #310.
 - **Stream maintenance and wildcard workers now correctly identify stream queues (finishes the #306/#307 orphan-sweep fix and closes a durable-stream data-loss bug).** `streams_queue_prefix` (default `pgbus_stream`) was consulted only by the dispatcher's `prune_stream_archives` and `sweep_orphan_streams`, but no code ever *named* a queue with it — real stream queues are `#{queue_prefix}_<name>` (`pgbus_<name>`). So both filters matched **zero** real stream queues: per-stream retention never ran, and the age-based orphan drop shipped in #307 was inert. Worse, a *job* queue whose logical name started with `stream_` (physical `pgbus_stream_x`) *did* match and could be dropped. All stream detection now goes through the new `pgbus_stream_queues` registry (see Added): `prune_stream_archives` and `sweep_orphan_streams` iterate registered streams (reviving #306/#307), `compact_archives` skips registered streams so each stream archive is compacted by exactly one path at its per-stream retention (not the 7-day job default), and — closing #309 — a `queues: ['*']` worker's `resolve_wildcard_queues` now excludes registered stream queues, so wildcard workers no longer claim durable broadcasts, fail to deserialize them, and DLQ-move them out of the stream's replay history. `streams_queue_prefix` is retained for backward compatibility but is now inert (documented). Refs #308, #309.

data/Rakefile

@@ -209,17 +209,62 @@ task :release, %i[version force] do |_t, args|
     success "Updated #{version_file}"
   end
 
+  # Step 1b: Regenerate the frozen lockfiles that pin the pgbus path gem, so the
+  # bump ships with them in sync. These are installed with `--frozen`/deployment
+  # in CI, so if they still name the OLD version they instant-fail (the Rails 7.1
+  # leg with exit 16, and docs-CI on any docs change). Regenerating here keeps the
+  # version-pin drift out of the release commit instead of surfacing on the next PR.
+  header "Frozen lockfiles"
+  # The ONLY thing a version bump changes in these frozen lockfiles is the pgbus
+  # path-gem pin — so bump exactly that line, in place, with a string edit.
+  #
+  # We deliberately do NOT run `bundle lock` here: a full re-resolve trips over
+  # constraints that have nothing to do with pgbus. Concretely, docs/Gemfile.lock
+  # carries a broad PLATFORMS list (…-gnu / …-musl / arm-linux) for which a
+  # platform gem like `thruster` ships no variant, so `bundle lock` fails with
+  # "Could not find gems matching 'thruster' valid for all resolution platforms"
+  # on any machine whose cache doesn't already hold those exact gems — aborting
+  # the release. `bundle lock --local` was even worse (wrong-file write + no
+  # fetch). A targeted pin edit sidesteps all of it, is deterministic on any
+  # machine, and produces the minimal 2-line diff (the PATH spec + the
+  # DEPENDENCIES pin). See #338/#341 and the surgical-bump fix.
+  frozen_lockfiles = %w[gemfiles/rails_7_1.gemfile.lock docs/Gemfile.lock]
+  regenerated_lockfiles = []
+  frozen_lockfiles.each do |lockfile|
+    unless File.exist?(lockfile)
+      skip "#{lockfile} not present"
+      next
+    end
+
+    content = File.read(lockfile)
+    # Matches both the PATH-source spec ("    pgbus (X.Y.Z)") and the
+    # DEPENDENCIES pin ("  pgbus (X.Y.Z)"), leaving everything else untouched.
+    bumped = content.gsub(/^(\s+pgbus) \([^)]*\)$/, "\\1 (#{new_version})")
+
+    if bumped == content
+      skip "#{lockfile} — no pgbus pin to bump"
+      next
+    end
+
+    File.write(lockfile, bumped)
+    regenerated_lockfiles << lockfile
+    success "Bumped pgbus pin in #{lockfile}"
+  end
+
   # Step 2: Verify gem builds cleanly
   header "Build verification"
   sh("gem build pgbus.gemspec --strict")
   sh("rm -f pgbus-*.gem")
   success "Gem builds cleanly"
 
-  # Step 3: Commit version bump
+  # Step 3: Commit version bump (+ any re-synced lockfiles)
   header "Git commit"
-  version_changed = !`git diff #{version_file}`.strip.empty? || !`git diff --cached #{version_file}`.strip.empty?
-  if version_changed
-    sh("git add #{version_file}")
+  paths_to_stage = [version_file, *regenerated_lockfiles]
+  staged_changes = paths_to_stage.any? do |path|
+    !`git diff #{path}`.strip.empty? || !`git diff --cached #{path}`.strip.empty?
+  end
+  if staged_changes
+    paths_to_stage.each { |path| sh("git add #{path}") }
     sh("git commit -m 'chore: bump version to #{new_version}'")
     success "Committed version bump"
   else

data/lib/pgbus/active_job/adapter.rb

@@ -112,6 +112,17 @@ module Pgbus
         uniqueness_key = Uniqueness.extract_key(payload_hash)
         return false unless uniqueness_key
 
+        # A retry re-enqueue is the SAME logical job re-acquiring its OWN key.
+        # ActiveJob increments `executions` at the start of perform_now (before
+        # the body), then retry_on re-enqueues from inside perform_now — while
+        # the executor still holds the key (it releases only on success/DLQ). So
+        # a re-enqueue with executions > 0 would otherwise hit its own held key,
+        # be rejected as a duplicate (JobNotUnique), and dead-letter the original
+        # while losing the retry. Let the retry through; the existing key row
+        # correctly stays held until the job finally succeeds or dead-letters.
+        # See issue #333.
+        return false if active_job.executions.to_i.positive?
+
         result = Uniqueness.acquire_enqueue_lock(uniqueness_key, active_job)
 
         # :no_lock means no enqueue-time lock needed (e.g. :while_executing strategy)

data/lib/pgbus/client.rb

@@ -79,7 +79,7 @@ module Pgbus
         # Both raise clean PG errors — no Ruby Timeout, no Thread#raise. Only
         # safe on this dedicated-connection branch — never on the shared-AR Proc
         # path, where statement_timeout would leak into application queries.
-        conn_opts = apply_connection_bounds(conn_opts)
+        conn_opts = wrap_session_gucs(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
@@ -95,8 +95,10 @@ module Pgbus
         # 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_conn_opts = wrap_session_gucs(
+          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)
@@ -163,9 +165,22 @@ module Pgbus
     # carries the underlying error plus which config source was in use.
     def verify_connection!
       synchronized do
-        @pgmq.with_connection { |conn| conn.exec("SELECT 1") }
+        @pgmq.with_connection do |conn|
+          conn.exec("SELECT 1")
+          # When require_primary is set, reject a connection that landed on a
+          # read-only replica at boot rather than letting a read/write-splitting
+          # pooler silently route pgmq's VOLATILE read/archive to a standby,
+          # where workers read nothing and jobs stop with a healthy heartbeat
+          # (issue #332). Off by default, so a single-primary deployment is
+          # unaffected.
+          Process::PrimaryValidator.validate_primary!(conn) if config.require_primary
+        end
       end
       true
+    rescue Process::ReplicaConnectionError => e
+      raise ConfigurationError,
+            "Database connection via #{connection_source} landed on a read-only replica " \
+            "(require_primary is set): #{e.message}"
     rescue PGMQ::Errors::ConnectionError, PG::Error => e
       raise ConfigurationError, "Database connection failed via #{connection_source}: #{e.message}"
     end
@@ -182,6 +197,17 @@ module Pgbus
       true
     end
 
+    # Whether the job connection currently lands on a read-only replica
+    # (pg_is_in_recovery() => t). Used by the doctor to warn about a
+    # read/write-splitting pooler that could route pgmq's VOLATILE read/archive
+    # to a standby, silently stalling job processing (issue #332). Raw PG error
+    # propagates so the caller can render the reason.
+    def in_recovery?
+      with_raw_connection do |conn|
+        conn.exec(Process::PrimaryValidator::RECOVERY_QUERY).getvalue(0, 0) == "t"
+      end
+    end
+
     # The logical queue names pgbus expects to exist based on the configuration
     # (default queue + worker capsules + recurring tasks). Public wrapper around
     # collect_configured_queues so the doctor can diff configured-vs-existing
@@ -890,7 +916,14 @@ module Pgbus
                PG.connect(opts)
              when Hash
                owned = true
-               PG.connect(**opts)
+               # :variables is a database.yml convention, not a libpq keyword —
+               # strip it before PG.connect and apply the GUCs via SET so this
+               # raw bootstrap/DDL connection matches the pooled connections
+               # (issue #332). Empty/absent variables is a plain connect.
+               variables = opts[:variables]
+               conn = PG.connect(**opts.except(:variables))
+               variables&.each { |name, value| conn.exec("SET #{name} = '#{value}'") }
+               conn
              else
                raise ConfigurationError, "Cannot resolve raw PG connection from #{opts.class}"
              end
@@ -1299,6 +1332,31 @@ module Pgbus
       end
     end
 
+    # In :session GUC mode, a Hash conn_opts carrying database.yml `:variables`
+    # must apply those GUCs via post-connect `SET` rather than the libpq
+    # `options` STARTUP param (which a transaction-mode PgBouncer rejects). We
+    # can't pass `:variables` to PG.connect (not a libpq keyword), so wrap the
+    # opts in a fresh-connect factory Proc: pgmq-ruby natively accepts a callable
+    # per pool slot (pgmq connection.rb), and it must return a UNIQUE
+    # PG::Connection each call (pgmq guards against a shared object). Applies to
+    # a Hash with `:variables` only — a String URL or no variables passes through
+    # unchanged, as does :options mode (where forward_connection_variables
+    # already baked the GUCs into `options`). See issue #332.
+    def wrap_session_gucs(conn_opts)
+      return conn_opts unless config.connection_guc_mode == :session
+      return conn_opts unless conn_opts.is_a?(Hash)
+
+      variables = conn_opts[:variables]
+      return conn_opts if variables.nil? || variables.empty?
+
+      pg_opts = conn_opts.except(:variables)
+      lambda do
+        conn = PG.connect(pg_opts)
+        variables.each { |name, value| conn.exec("SET #{name} = '#{value}'") }
+        conn
+      end
+    end
+
     def apply_connection_bounds(conn_opts)
       timeout = config.read_timeout
       return conn_opts unless timeout&.positive?

data/lib/pgbus/configuration.rb

@@ -102,6 +102,27 @@ module Pgbus
     # Requires a matching entry in config/database.yml under the "pgbus" key.
     attr_accessor :connects_to
 
+    # Reject a job-pool connection that landed on a read-only replica
+    # (pg_is_in_recovery() => t). Default false — a correctly-configured
+    # single-primary deployment sees no change. Set true when a read/write
+    # splitting pooler (pgdog/pgcat) could route pgmq's VOLATILE read/archive
+    # to a replica, which otherwise makes workers silently read nothing.
+    # See issue #332.
+    attr_accessor :require_primary
+
+    # How pgbus forwards database.yml GUCs (`variables:` such as
+    # client_min_messages, and the read-timeout statement_timeout) onto its
+    # dedicated pgmq connections:
+    #   :options (default) — bake them into the libpq `options` STARTUP param
+    #                        (-c key=value). Works everywhere EXCEPT a
+    #                        transaction-mode PgBouncer, which rejects the
+    #                        `options` startup param with a FATAL.
+    #   :session           — apply them via post-connect `SET` statements on a
+    #                        fresh connection instead, so a transaction-mode
+    #                        pooler accepts them. Dedicated-connection path only.
+    # See issue #332.
+    attr_reader :connection_guc_mode
+
     # Zombie message detection — logs a warning when a message is redelivered
     # (read_ct > 1) without any prior failure recorded in pgbus_failed_events.
     attr_accessor :zombie_detection
@@ -124,7 +145,7 @@ module Pgbus
     attr_accessor :health_port, :health_bind
 
     # Streams (turbo-rails replacement, SSE-based)
-    attr_accessor :streams_enabled, :streams_path, :streams_queue_prefix, :streams_signed_name_secret,
+    attr_accessor :streams_enabled, :streams_path, :streams_signed_name_secret,
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
                   :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
@@ -248,6 +269,8 @@ module Pgbus
       @stats_flush_interval = StatBuffer::DEFAULT_FLUSH_INTERVAL
 
       @connects_to = nil
+      @require_primary = false
+      @connection_guc_mode = :options
 
       @web_auth = nil
       @web_refresh_interval = 5000
@@ -268,12 +291,11 @@ module Pgbus
 
       @streams_enabled = true
       @streams_path = nil
-      # Retained for backward compatibility only — NO LONGER USED for queue
-      # naming or stream detection. Stream queues are named like job queues
-      # (`#{queue_prefix}_<name>`, see #queue_name) and are identified via the
-      # `pgbus_stream_queues` registry (Pgbus::StreamQueue), not by this prefix.
-      # Setting it has no effect. See issue #308.
-      @streams_queue_prefix = "pgbus_stream"
+      # streams_queue_prefix was removed in 1.0 (issue #335): it had been an
+      # inert no-op since #308 (stream queues are named like job queues,
+      # `#{queue_prefix}_<name>`, and identified via the pgbus_stream_queues
+      # registry). Setting it now raises NoMethodError — remove it from your
+      # initializer.
       # Streamer-only connection overrides. The Streamer's Listener owns a
       # dedicated long-lived `wait_for_notify` PG connection that can't go
       # through a PgBouncer in transaction mode (LISTEN/NOTIFY don't survive
@@ -472,12 +494,23 @@ module Pgbus
       # pgbus-installed formatter. A user who set a custom logger with a custom
       # formatter keeps it — log_format only records the intended format for
       # pgbus's own defaults, it must not silently clobber their formatting.
-      return unless pgbus_installable_formatter?(@logger&.formatter)
-
-      @logger.formatter = case format
-                          when :json then LogFormatter::JSON.new
-                          when :text then LogFormatter::Text.new
-                          end
+      old_formatter = @logger&.formatter
+      return unless pgbus_installable_formatter?(old_formatter)
+
+      new_formatter = case format
+                      when :json then LogFormatter::JSON.new
+                      when :text then LogFormatter::Text.new
+                      end
+
+      # ActiveSupport::TaggedLogging works by extending the logger's formatter
+      # instance with a module that prepends the current tags (and adds a
+      # #tagged method the logger delegates to). Installing a fresh pgbus
+      # formatter would strip that, so `logger.tagged { ... }` would drop tags —
+      # and, worse, raise NoMethodError: undefined method `tagged` on our
+      # formatter. Re-extend the new formatter with the same module when the old
+      # one carried it, so tagging keeps working (issue #334).
+      preserve_tagged_logging(old_formatter, new_formatter)
+      @logger.formatter = new_formatter
     end
 
     VALID_BROADCAST_MODES = %i[ephemeral durable].freeze
@@ -510,6 +543,18 @@ module Pgbus
       @group_mode = coerced
     end
 
+    VALID_CONNECTION_GUC_MODES = %i[options session].freeze
+
+    def connection_guc_mode=(mode)
+      mode = mode.to_sym
+      unless VALID_CONNECTION_GUC_MODES.include?(mode)
+        raise Pgbus::ConfigurationError,
+              "Invalid connection_guc_mode: #{mode}. Must be one of: #{VALID_CONNECTION_GUC_MODES.join(", ")}"
+      end
+
+      @connection_guc_mode = mode
+    end
+
     VALID_PGMQ_SCHEMA_MODES = %i[auto extension embedded].freeze
 
     def pgmq_schema_mode=(mode)
@@ -594,12 +639,65 @@ module Pgbus
         raise Pgbus::ConfigurationError, "insights_default_minutes must be a positive integer"
       end
 
+      raise Pgbus::ConfigurationError, "require_primary must be true or false" unless [true, false].include?(require_primary)
+
+      validate_job_path_gaps!
       validate_streams!
       validate_metrics_backend!
 
       self
     end
 
+    # Pre-1.0 surface-freeze: reject malformed values for core job-path keys at
+    # boot rather than failing deep in a worker/dispatcher/poller/scheduler
+    # thread, per-enqueue, or by silently corrupting queue names / leaving the
+    # dashboard open. Mirrors the idioms already used above (issue #335).
+    def validate_job_path_gaps!
+      # Worker recycling trio: nil disables the limit; a set value must be a
+      # positive Numeric (mirror stall_threshold).
+      { max_jobs_per_worker: max_jobs_per_worker, max_memory_mb: max_memory_mb,
+        max_worker_lifetime: max_worker_lifetime }.each do |name, value|
+        next if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+        raise Pgbus::ConfigurationError, "#{name} must be a positive number or nil to disable"
+      end
+
+      # Interval knobs: positive Numeric, never nil (mirror polling_interval).
+      { dispatch_interval: dispatch_interval, outbox_poll_interval: outbox_poll_interval,
+        recurring_schedule_interval: recurring_schedule_interval }.each do |name, value|
+        raise Pgbus::ConfigurationError, "#{name} must be > 0" unless value.is_a?(Numeric) && value.positive?
+      end
+
+      unless outbox_batch_size.is_a?(Integer) && outbox_batch_size.positive?
+        raise Pgbus::ConfigurationError, "outbox_batch_size must be a positive integer"
+      end
+
+      # 0 is a valid priority level (queue_factory clamps to 0..priority_levels-1).
+      unless default_priority.is_a?(Integer) && default_priority >= 0
+        raise Pgbus::ConfigurationError, "default_priority must be a non-negative integer"
+      end
+
+      # Queue-name components: a nil/empty/non-String prefix silently corrupts
+      # every derived queue name (mirror health_bind).
+      { 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
+
+      # web_auth gates the dashboard; a non-callable value silently leaves it
+      # open (mirror streams_presence_member).
+      unless web_auth.nil? || web_auth.respond_to?(:call)
+        raise Pgbus::ConfigurationError, "web_auth must respond to #call (a Proc/lambda) or be nil"
+      end
+
+      raise Pgbus::ConfigurationError, "error_reporters must be an Array" unless error_reporters.is_a?(Array)
+
+      # connects_to is splatted into ActiveRecord's connects_to at engine boot;
+      # a non-Hash raises a raw TypeError there — surface a clean message here.
+      return if connects_to.nil? || connects_to.is_a?(Hash)
+
+      raise Pgbus::ConfigurationError, "connects_to must be a Hash or nil"
+    end
+
     def validate_streams!
       unless streams_default_retention.is_a?(Numeric) && streams_default_retention >= 0
         raise Pgbus::ConfigurationError, "streams_default_retention must be a non-negative number"
@@ -1039,7 +1137,17 @@ module Pgbus
       if database_url
         database_url
       elsif connection_params
-        connection_params
+        # An explicit connection_params Hash may carry a database.yml-style
+        # `:variables` block; forward it the same way the AR-extracted path does
+        # so client_min_messages etc. actually reach pgmq's connections and a
+        # non-libpq :variables key never reaches PG.connect (issue #332). A
+        # non-Hash connection_params (e.g. a Proc returning a raw connection)
+        # passes through untouched.
+        if connection_params.is_a?(Hash)
+          forward_connection_variables(connection_params.except(:variables), connection_params[:variables])
+        else
+          connection_params
+        end
       elsif defined?(ActiveRecord::Base)
         # Extract connection config from ActiveRecord so pgmq-ruby creates its
         # own dedicated PG connections. Sharing AR's raw_connection via a Proc
@@ -1067,28 +1175,7 @@ module Pgbus
     #
     # Precedence: streams_database_url > streams_host/port override > base.
     def streams_connection_options
-      return streams_database_url if streams_database_url
-
-      base = connection_options
-      return base unless streams_host || streams_port
-
-      case base
-      when Hash
-        result = base.dup
-        result[:host] = streams_host if streams_host
-        result[:port] = streams_port if streams_port
-        result
-      when String
-        # libpq's conninfo parser takes later key=value pairs as overrides
-        # for earlier ones, so we just append. Handles both URI form
-        # (postgres://...) and key=value form.
-        parts = [base]
-        parts << "host=#{streams_host}" if streams_host
-        parts << "port=#{streams_port}" if streams_port
-        parts.join(" ")
-      else
-        base
-      end
+      override_connection_options(url: streams_database_url, host: streams_host, port: streams_port)
     end
 
     # Connection options for the Worker's dedicated NotifyListener connection.
@@ -1096,38 +1183,64 @@ module Pgbus
     # overridable via worker_notify_database_url / worker_notify_host /
     # worker_notify_port so the LISTEN connection can bypass PgBouncer.
     def worker_notify_connection_options
-      return worker_notify_database_url if worker_notify_database_url
+      override_connection_options(url: worker_notify_database_url, host: worker_notify_host, port: worker_notify_port)
+    end
+
+    # Resolved notify wakeup flag: defaults to listen_notify when nil.
+    def worker_notify_wakeup?
+      if @worker_notify_wakeup.nil?
+        listen_notify
+      else
+        @worker_notify_wakeup
+      end
+    end
+
+    private
+
+    # Shared resolver for a dedicated connection (streamer LISTEN / worker
+    # NotifyListener) that can override the base `connection_options` to bypass a
+    # pooler. Precedence: a full `url` wins outright; otherwise `host`/`port`
+    # surgically override the base (a Hash gets dup+merge, a String URL/conninfo
+    # gets appended key=value pairs libpq treats as later-wins overrides); with
+    # no override, or a base that is neither Hash nor String, the base passes
+    # through unchanged. Extracted from the byte-identical
+    # streams_connection_options / worker_notify_connection_options (issue #335).
+    def override_connection_options(url:, host:, port:)
+      return url if url
 
       base = connection_options
-      return base unless worker_notify_host || worker_notify_port
+      return base unless host || port
 
       case base
       when Hash
         result = base.dup
-        result[:host] = worker_notify_host if worker_notify_host
-        result[:port] = worker_notify_port if worker_notify_port
+        result[:host] = host if host
+        result[:port] = port if port
         result
       when String
         parts = [base]
-        parts << "host=#{worker_notify_host}" if worker_notify_host
-        parts << "port=#{worker_notify_port}" if worker_notify_port
+        parts << "host=#{host}" if host
+        parts << "port=#{port}" if port
         parts.join(" ")
       else
         base
       end
     end
 
-    # Resolved notify wakeup flag: defaults to listen_notify when nil.
-    def worker_notify_wakeup?
-      if @worker_notify_wakeup.nil?
-        listen_notify
-      else
-        @worker_notify_wakeup
-      end
+    # When the logger's previous formatter was extended with
+    # ActiveSupport::TaggedLogging::Formatter (the case for a Rails
+    # Rails.logger), extend the replacement pgbus formatter with the same module
+    # so `logger.tagged`/`push_tags` keep prepending tags instead of dropping
+    # them (and calling #tagged on our formatter stops raising NoMethodError).
+    # No-op when TaggedLogging isn't loaded or the old formatter wasn't tagged.
+    def preserve_tagged_logging(old_formatter, new_formatter)
+      return unless new_formatter
+      return unless defined?(::ActiveSupport::TaggedLogging::Formatter)
+      return unless old_formatter.is_a?(::ActiveSupport::TaggedLogging::Formatter)
+
+      new_formatter.extend(::ActiveSupport::TaggedLogging::Formatter)
     end
 
-    private
-
     # True when log_format= may install its own formatter: no formatter set yet
     # (nil), a pgbus formatter we installed, or a framework DEFAULT formatter
     # (Ruby's Logger::Formatter, Rails' SimpleFormatter) that the app didn't
@@ -1326,13 +1439,15 @@ module Pgbus
       # Rails 7.1+ db_config.configuration_hash returns the full config
       config_hash = db_config.configuration_hash
 
-      {
+      base = {
         host: config_hash[:host] || "localhost",
         port: (config_hash[:port] || 5432).to_i,
         dbname: config_hash[:database],
         user: config_hash[:username],
         password: config_hash[:password]
       }.compact
+
+      forward_connection_variables(base, config_hash[:variables])
     rescue StandardError => e
       # Fallback to Proc path if AR config extraction fails (e.g., adapter
       # doesn't expose standard config keys). Log a warning since this path
@@ -1348,5 +1463,28 @@ module Pgbus
         -> { ActiveRecord::Base.connection.raw_connection }
       end
     end
+
+    # database.yml's `variables:` block (e.g. client_min_messages) is a Rails
+    # convention, not a libpq keyword — pgmq-ruby passes the hash straight to
+    # PG.connect, which would ignore/reject a `:variables` key. So carry the GUCs
+    # forward by the mechanism the operator's pooler tolerates:
+    #   :options — bake them into the libpq `options` STARTUP param
+    #              (-c key=value), appended to any existing options. A
+    #              transaction-mode PgBouncer rejects this param.
+    #   :session — leave the raw `:variables` hash on the returned options so the
+    #              Client applies them via post-connect `SET` (pooler-safe).
+    # Empty/absent variables is a no-op on both paths. See issue #332.
+    def forward_connection_variables(base, variables)
+      return base if variables.nil? || variables.empty?
+
+      case connection_guc_mode
+      when :session
+        base.merge(variables: variables)
+      else
+        gucs = variables.map { |k, v| "-c #{k}=#{v}" }.join(" ")
+        options = [base[:options], gucs].compact.reject(&:empty?).join(" ")
+        base.merge(options: options)
+      end
+    end
   end
 end

data/lib/pgbus/doctor.rb

@@ -5,7 +5,7 @@ require "pgbus/mcp/health_analyzer"
 
 module Pgbus
   # Preflight diagnostics for a pgbus deployment — the single command that
-  # answers "is this environment healthy enough to run?". Runs eight checks and
+  # answers "is this environment healthy enough to run?". Runs nine checks and
   # returns a machine-readable result plus a human report, so `pgbus doctor`
   # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
   # 1 on any failure).
@@ -42,7 +42,8 @@ module Pgbus
         check_notify,
         check_processes,
         check_allowed_global_id_models,
-        check_broadcast_queue
+        check_broadcast_queue,
+        check_primary
       ].map(&:to_h)
     end
 
@@ -248,6 +249,29 @@ module Pgbus
       Check.new(name: "Broadcast queue", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # 9. Primary affinity — pooler safety (issue #332). A read/write-splitting
+    # pooler (pgdog/pgcat) can route pgmq's VOLATILE read/archive to a read
+    # replica, where workers read nothing and jobs stop with a healthy
+    # heartbeat. If the job connection currently lands on a replica
+    # (pg_is_in_recovery() => t), warn with the direct-port remediation. A
+    # warning, never a failure: a deliberate replica-read setup is rare but
+    # possible, and require_primary is the enforcement knob for those who want a
+    # hard stop.
+    def check_primary
+      if @client.in_recovery?
+        return Check.new(name: "Primary affinity", status: :warn,
+                         detail: "job connection is on a read-only replica (pg_is_in_recovery() => t) — " \
+                                 "a read/write-splitting pooler may be routing pgmq reads to a standby, " \
+                                 "silently stalling jobs. Point the connection at the DIRECT primary port " \
+                                 "(worker_notify_* / streams_* overrides) and set require_primary to reject " \
+                                 "a replica at boot")
+      end
+
+      Check.new(name: "Primary affinity", status: :ok, detail: "on primary")
+    rescue StandardError => e
+      Check.new(name: "Primary affinity", status: :warn, detail: "could not determine (#{e.class}: #{e.message})")
+    end
+
     # True when some configured worker capsule drains the given queue — either
     # by naming it explicitly or via a "*" wildcard (which drains every queue).
     def worker_drains?(queue)

data/lib/pgbus/event_bus/registry.rb

@@ -28,20 +28,79 @@ module Pgbus
         subscriber
       end
 
-      def setup_all!
-        @subscribers.each(&:setup!)
+      # Set up every registered subscriber (creates its queue + binds its topic
+      # via Pgbus.client, which opens a PGMQ connection).
+      #
+      # safe: false (default) — set up unconditionally; a connection error
+      #   propagates. Use when you know the database is up.
+      # safe: true — boot/rake-safe: skip entirely in a schema/db: rake context
+      #   (opening a PGMQ connection there would block DROP DATABASE and isn't
+      #   wanted during schema load / asset precompile), and swallow a connection
+      #   error with a warning instead of crashing boot when the DB isn't ready.
+      #   This is the path host apps should call from an initializer so they stop
+      #   hand-wrapping setup_all! in a multi-class rescue (issue #334).
+      def setup_all!(safe: false)
+        return if safe && schema_task_context?
+
+        # Snapshot under the mutex — subscribe/clear! mutate @subscribers under
+        # @mutex, and setup! does DB I/O we must NOT hold the lock across, so
+        # iterate a copy taken atomically.
+        subscribers = @mutex.synchronize { @subscribers.dup }
+
+        subscribers.each do |subscriber|
+          subscriber.setup!
+        rescue PGMQ::Errors::ConnectionError, PG::ConnectionBad => e
+          # Only a genuine CONNECTION failure ("database isn't up yet") is
+          # tolerable under safe:; a PG::Error subclass like a syntax/permission/
+          # missing-table error is a real setup bug and must still surface.
+          raise unless safe
+
+          Pgbus.logger.warn do
+            "[Pgbus] EventBus subscriber setup skipped (#{e.class}: #{e.message}) — " \
+              "the database isn't reachable yet; subscribers set up on the next attempt."
+          end
+        end
       end
 
       def handlers_for(routing_key)
         @subscribers.select { |s| matches?(s.pattern, routing_key) }
       end
 
+      # Physical PGMQ queue names for every registered event subscriber, so a
+      # wildcard (`queues: ['*']`) worker can exclude them — an event queue
+      # carries event payloads, not ActiveJob jobs, and a job worker that adopts
+      # one fails to deserialize and DLQ-moves the event (issue #333). Returns a
+      # Set of prefixed names (`#{queue_prefix}_<subscriber>`), matching the
+      # pgmq.meta rows the wildcard resolver diffs against.
+      def event_queue_names
+        @subscribers.to_set { |s| Pgbus.configuration.queue_name(s.queue_name) }
+      end
+
       def clear!
         @mutex.synchronize { @subscribers.clear }
       end
 
       private
 
+      # Rake task-name prefixes during which pgbus must NOT open a PGMQ
+      # connection: creating/dropping/migrating/loading the schema (a live
+      # connection blocks DROP DATABASE) and asset precompile (no DB expected).
+      SCHEMA_TASK_PREFIXES = %w[db: db_test: assets: webpacker: yarn:].freeze
+      private_constant :SCHEMA_TASK_PREFIXES
+
+      # True when running inside a rake schema/asset task, where setup_all!(safe:)
+      # should skip rather than open a connection. Detected from the invoked rake
+      # task names; false outside a Rake run.
+      def schema_task_context?
+        return false unless defined?(::Rake) && ::Rake.respond_to?(:application)
+
+        tasks = ::Rake.application.top_level_tasks
+        tasks.any? { |t| SCHEMA_TASK_PREFIXES.any? { |prefix| t.to_s.start_with?(prefix) } }
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] schema_task_context? detection failed, assuming non-schema: #{e.class}: #{e.message}" }
+        false
+      end
+
       def matches?(pattern, routing_key)
         regex = pattern
                 .gsub(".", "\\.")

data/lib/pgbus/process/notify_listener.rb

@@ -49,12 +49,25 @@ module Pgbus
         @running = false
         @thread = nil
         @conn = nil
+        # Optimistic until the start-time self-probe runs: assume NOTIFY delivery
+        # works so a not-yet-probed listener isn't mistaken for a pooler-deaf one.
+        @delivering = true
       end
 
       def listening_to
         @state_mutex.synchronize { @listening_to.dup }
       end
 
+      # Whether the start-time self-probe confirmed this connection can actually
+      # receive a NOTIFY. False when a transaction-mode pooler or replica
+      # silently drops LISTEN: the thread is still alive (running? == true) but
+      # will never wake the loop. The Worker/Consumer consult this so a
+      # live-but-deaf listener is treated as absent for wake-timeout purposes —
+      # fast polling, not the 15s NOTIFY ceiling (issue #332).
+      def delivering?
+        @state_mutex.synchronize { @delivering }
+      end
+
       def start
         @state_mutex.synchronize do
           return self if @running
@@ -116,8 +129,11 @@ module Pgbus
         # One-shot delivery self-probe on the initial connection only. A pooler
         # or replica that silently breaks LISTEN/NOTIFY is surfaced here with an
         # actionable error; the listener still runs and degrades to polling.
-        # Reconnects skip the probe to stay cheap.
-        NotifyProbe.probe_notify_delivery!(conn, logger: @logger)
+        # Reconnects skip the probe to stay cheap. Record the result so the
+        # owning worker can drop back to fast polling instead of the 15s NOTIFY
+        # ceiling when this connection can't actually deliver (issue #332).
+        delivering = NotifyProbe.probe_notify_delivery!(conn, logger: @logger)
+        @state_mutex.synchronize { @delivering = delivering }
         @state_mutex.synchronize { @conn = conn }
         drain_commands
 

data/lib/pgbus/process/worker.rb

@@ -415,11 +415,20 @@ module Pgbus
         Pgbus::StreamQueue.reset_cache!
         stream_names = Pgbus::StreamQueue.all_names
 
+        # Event-bus subscriber queues also share the job namespace (pgbus_<handler>)
+        # but carry event payloads, not ActiveJob jobs. A wildcard worker that
+        # adopts one hands the event to the executor, which fails to deserialize
+        # it and DLQ-moves it out of the consumer's reach — so an app running the
+        # event bus had to hand-maintain an explicit queue list. Exclude them,
+        # like stream queues (issue #333).
+        event_names = Pgbus::EventBus::Registry.instance.event_queue_names
+
         conn = Pgbus.configuration.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
         all_queues = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
         resolved = all_queues
                    .reject { |q| q.end_with?(dlq_suffix) }
                    .reject { |q| stream_names.include?(q) }
+                   .reject { |q| event_names.include?(q) }
                    .map { |q| q.delete_prefix(prefix) }
 
         if resolved.empty?
@@ -605,13 +614,20 @@ module Pgbus
       def wake_timeout
         # A dead listener (running? false) will never wake the loop, so treat
         # it as absent and keep polling at the short interval until
-        # ensure_notify_listener restarts it. Only a live listener earns the
-        # long NOTIFY-mode ceiling.
-        return effective_polling_interval unless notify_wakeup? && @notify_listener&.running?
+        # ensure_notify_listener restarts it. A live-but-deaf listener
+        # (delivering? false — a transaction-mode pooler or replica that drops
+        # LISTEN) is the same story: it will never wake us, so don't raise the
+        # poll floor to the 15s ceiling behind it (issue #332). Only a live,
+        # delivering listener earns the long NOTIFY-mode ceiling.
+        return effective_polling_interval unless notify_wakeup? && listener_delivering?
 
         [effective_polling_interval, config.polling_interval, NOTIFY_FALLBACK_POLL_SECONDS].max
       end
 
+      def listener_delivering?
+        @notify_listener&.running? && @notify_listener.delivering?
+      end
+
       def effective_polling_interval
         return config.polling_interval if @consumer_priority.zero?
 

data/lib/pgbus/streams/phlex_helpers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Streams
+    # Phlex-includable version of the +pgbus_stream_from+ Rails view helper, so
+    # a Phlex component can subscribe a page to a pgbus stream the same way it
+    # would with turbo-rails' +turbo_stream_from+:
+    #
+    #   class ChatRoom < Phlex::HTML
+    #     include Pgbus::Streams::PhlexHelpers
+    #
+    #     def view_template
+    #       pgbus_stream_from(@room)
+    #     end
+    #   end
+    #
+    # phlex-rails doesn't ship a +Phlex::Rails::Helpers::PgbusStreamFrom+, so
+    # apps used to hand-register this module locally. It is defined exactly like
+    # phlex-rails' own +Phlex::Rails::Helpers::TurboStreamFrom+ (register the
+    # method as an output helper resolved against the Rails view context).
+    #
+    # This file is NOT autoloaded — phlex-rails is an OPTIONAL dependency, so the
+    # module references +Phlex::Rails::HelperMacros+, which only exists when the
+    # app has phlex-rails. Require it explicitly from a Phlex component or an
+    # initializer:  require "pgbus/streams/phlex_helpers".
+    module PhlexHelpers
+      extend Phlex::Rails::HelperMacros
+
+      register_output_helper def pgbus_stream_from(...) = nil
+    end
+  end
+end

data/lib/pgbus/uniqueness.rb

@@ -62,9 +62,18 @@ module Pgbus
         raise ArgumentError, "on_conflict must be one of: #{VALID_CONFLICTS.join(", ")}" unless VALID_CONFLICTS.include?(on_conflict)
         raise ArgumentError, "key must be callable (Proc or lambda)" if key && !key.respond_to?(:call)
 
+        # Record whether an explicit key was given. With NO explicit key the key
+        # defaults to the class name; that is safe for a no-argument job (one
+        # logical instance — e.g. a recurring CleanupJob that must not overlap
+        # itself) but a silent-correctness footgun for a job that takes per-record
+        # arguments: `ImportOrderJob.perform_later(order_id)` would collapse every
+        # order into ONE per-class singleton. resolve_key raises at resolve time
+        # when the class-name default meets non-empty arguments (see #333); the
+        # no-arg case keeps working. explicit_key marks which is which.
         @pgbus_uniqueness = {
           strategy: strategy,
           key: key || ->(*) { name },
+          explicit_key: !key.nil?,
           on_conflict: on_conflict
         }.freeze
       end
@@ -80,6 +89,7 @@ module Pgbus
         return nil unless config
 
         args = active_job.arguments
+        guard_class_name_default!(active_job, config, args)
         last = args.last
         key = if last.is_a?(Hash) && last.each_key.all?(Symbol)
                 config[:key].call(*args[...-1], **last)
@@ -93,6 +103,27 @@ module Pgbus
         key
       end
 
+      # Guards the class-name default key against the per-record collapse
+      # footgun (#333). When an :until_executed job was declared with NO explicit
+      # key (so the key is the class name) AND is enqueued WITH arguments, every
+      # distinct argument set would resolve to the same class-name key and
+      # collapse into one per-class singleton — almost never what the caller
+      # wants. Raise with an actionable message. A no-argument job keeps the
+      # class-name default (one logical instance, e.g. a recurring task that must
+      # not overlap itself), and :while_executing is unaffected (it acquires
+      # per-invocation at execution start, not by class-name identity at enqueue).
+      def guard_class_name_default!(active_job, config, args)
+        return if config[:explicit_key]
+        return unless config[:strategy] == :until_executed
+        return if args.nil? || args.empty?
+
+        raise ArgumentError,
+              "#{active_job.class.name} uses ensures_uniqueness strategy: :until_executed with no key: " \
+              "but is enqueued with arguments — the default key is the class name, which would collapse " \
+              "every distinct argument set into one per-class singleton. Pass an explicit " \
+              "key: ->(*args) { ... } that includes the arguments. See https://pgbus.dev/docs/upgrading-pgbus"
+      end
+
       def inject_metadata(active_job, payload_hash)
         config = uniqueness_config(active_job)
         return payload_hash unless config

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.9.11"
+  VERSION = "0.11.0"
 end

data/lib/pgbus/web/authentication.rb

@@ -13,6 +13,12 @@ module Pgbus
         attr_accessor :auth_warned
       end
 
+      # Default base controller — anything else means the app deliberately
+      # chose a controller (e.g. an AdminController) that already gates access,
+      # so the dashboard isn't actually open and the warning is a false positive.
+      DEFAULT_BASE_CONTROLLER = "::ActionController::Base"
+      private_constant :DEFAULT_BASE_CONTROLLER
+
       private
 
       def authenticate_pgbus!
@@ -30,6 +36,10 @@ module Pgbus
 
       def warn_unauthenticated_dashboard
         return if Pgbus::Web::Authentication.auth_warned
+        # A non-default base_controller_class signals host-level auth is in
+        # place; don't nag apps that gate the dashboard via a custom controller
+        # (they had to set a redundant web_auth lambda just to silence us — #334).
+        return unless default_base_controller?
 
         Pgbus.logger.warn do
           "[Pgbus] Dashboard is accessible without authentication. " \
@@ -38,6 +48,19 @@ module Pgbus
         end
         Pgbus::Web::Authentication.auth_warned = true
       end
+
+      # True when base_controller_class is (still) the default ActionController::Base.
+      # Normalizes both sides so a Class value, the "::"-prefixed string, and the
+      # bare "ActionController::Base" string all compare equal — otherwise the
+      # warning would wrongly fire for an app that set the default in another form.
+      def default_base_controller?
+        normalize_controller_name(Pgbus.configuration.base_controller_class) ==
+          normalize_controller_name(DEFAULT_BASE_CONTROLLER)
+      end
+
+      def normalize_controller_name(value)
+        value.to_s.delete_prefix("::")
+      end
     end
   end
 end

data/lib/pgbus.rb

@@ -103,6 +103,11 @@ module Pgbus
         # the gem and loads the subsystem explicitly.
         loader.ignore("#{__dir__}/pgbus/mcp")
         loader.ignore("#{__dir__}/pgbus/mcp.rb")
+        # The Phlex stream helper references Phlex::Rails::HelperMacros from the
+        # optional `phlex-rails` gem. Keep it out of Zeitwerk so eager_load never
+        # touches those constants; a Phlex app requires it explicitly via
+        # `require "pgbus/streams/phlex_helpers"`.
+        loader.ignore("#{__dir__}/pgbus/streams/phlex_helpers.rb")
         # Vendor integrations are loaded conditionally (when the vendor gem
         # is present) by lib/pgbus/engine.rb. Keeping them out of Zeitwerk
         # means we don't reference vendor constants at autoload time.
@@ -209,6 +214,19 @@ module Pgbus
       Streams::Key.stream_key!(key)
     end
 
+    # The maximum length (in characters) a stream name may be before it
+    # overflows the pgbus queue-name budget. A stream name becomes the physical
+    # queue `#{queue_prefix}_<name>`, and PGMQ caps queue names, so the usable
+    # budget is `QueueNameValidator::MAX_QUEUE_NAME_LENGTH - queue_prefix.length
+    # - 1`. Depends on `config.queue_prefix`. Use it to size or truncate stream
+    # identifiers up front instead of hand-computing the budget at every call
+    # site.
+    #
+    #   name = candidate.length > Pgbus.stream_name_budget ? Pgbus.stream_key(record) : candidate
+    def stream_name_budget
+      Streams::Key.queue_name_budget
+    end
+
     # Publish an event to the bus — the top-level shortcut for
     # `Pgbus::EventBus::Publisher.publish`, symmetric with `Pgbus.stream`.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.9.11
+  version: 0.11.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -352,6 +352,7 @@ files:
 - lib/pgbus/streams/envelope.rb
 - lib/pgbus/streams/filters.rb
 - lib/pgbus/streams/key.rb
+- lib/pgbus/streams/phlex_helpers.rb
 - lib/pgbus/streams/pool_autoscaler.rb
 - lib/pgbus/streams/pool_trigger.rb
 - lib/pgbus/streams/presence.rb