pgbus 0.9.8 → 0.9.9

data/lib/pgbus/generators/config_converter.rb

@@ -11,7 +11,9 @@ module Pgbus
     #
     # Drops settings that:
     #   - match the gem default (no point restating it)
-    #   - are deprecated (e.g. pool_size, which is now auto-tuned)
+    #   - are deprecated (settings that no longer exist in the public API —
+    #     see DEPRECATED_SETTINGS; pool_size is NOT one of these, it's a
+    #     live accessor that overrides auto-tuning and is preserved)
     #
     # Converts seconds to durations when they evenly divide into a clean
     # unit (7 days, 30 days, 10 minutes). Falls back to the raw integer
@@ -28,7 +30,7 @@ module Pgbus
     # generator's CLI wrapper writes the new initializer and tells the
     # user to delete the YAML when ready.
     class ConfigConverter
-      class Error < StandardError; end
+      class Error < Pgbus::Error; end
 
       # Setters that accept ActiveSupport::Duration (PR 5).
       DURATION_SETTINGS = %w[
@@ -38,15 +40,15 @@ module Pgbus
 
       # Settings that no longer exist in the public API. The converter
       # silently drops these from the generated initializer so users on
-      # legacy YAML get a clean migration.
+      # legacy YAML get a clean migration. NOTE: pool_size is intentionally
+      # NOT here — it's a live Configuration#pool_size accessor users set to
+      # override auto-tuning, so it must survive the conversion unchanged.
       #
-      #   - pool_size              -> auto-tuned from worker thread counts
       #   - notify_throttle_ms     -> Pgbus::Client::NOTIFY_THROTTLE_MS
       #   - circuit_breaker_*      -> Pgbus::CircuitBreaker constants
       #   - archive_compaction_*   -> Pgbus::Process::Dispatcher constants
       #   - dead_letter_queue_suffix -> Pgbus::DEAD_LETTER_SUFFIX (frozen)
       DEPRECATED_SETTINGS = %w[
-        pool_size
         notify_throttle_ms
         circuit_breaker_threshold circuit_breaker_base_backoff circuit_breaker_max_backoff
         archive_compaction_interval archive_compaction_batch_size

data/lib/pgbus/generators/migration_detector.rb

@@ -35,9 +35,10 @@ module Pgbus
     #
     # 5. Indexes missing on existing tables → queued. Additive, safe.
     #
-    # 6. Modern replacements for legacy tables (e.g. pgbus_job_locks →
-    #    pgbus_uniqueness_keys) → queue the migration path only if the
-    #    legacy table still exists. Otherwise queue the fresh install.
+    # 6. Modern uniqueness table (pgbus_uniqueness_keys) missing → queue
+    #    add_uniqueness_keys unconditionally. A legacy pgbus_job_locks
+    #    table left over from an older install is not dropped by this
+    #    detector — run `pgbus:migrate_job_locks` by hand to retire it.
     class MigrationDetector
       # Sentinel returned when the database looks empty of pgbus tables.
       # The caller (pgbus:update generator) should redirect the user to
@@ -58,13 +59,14 @@ module Pgbus
 
       # generator_key → Rails generator name. Passed to Thor's invoke.
       #
-      # Note: uniqueness_keys uses the migrate_job_locks generator for
-      # both the fresh-install and upgrade-from-job_locks paths. The
-      # template is idempotent: `unless table_exists?(:pgbus_uniqueness_keys)`
-      # creates it, and `if table_exists?(:pgbus_job_locks)` drops the
-      # legacy table. One generator covers both cases.
+      # Note: uniqueness_keys invokes add_uniqueness_keys, which only
+      # creates the modern pgbus_uniqueness_keys table. If the legacy
+      # pgbus_job_locks table is also present (an install mid-migration),
+      # run `pgbus:migrate_job_locks` separately to drop it — that
+      # generator is not part of this detector's default flow since it
+      # requires the legacy table to already exist.
       GENERATOR_MAP = {
-        uniqueness_keys: "pgbus:migrate_job_locks",
+        uniqueness_keys: "pgbus:add_uniqueness_keys",
         add_job_stats: "pgbus:add_job_stats",
         add_job_stats_latency: "pgbus:add_job_stats_latency",
         add_job_stats_queue_index: "pgbus:add_job_stats_queue_index",
@@ -81,7 +83,7 @@ module Pgbus
       # Human-friendly description of each migration for the generator
       # output. Keeps the update generator's run log readable.
       DESCRIPTIONS = {
-        uniqueness_keys: "uniqueness keys table (job deduplication, also upgrades legacy job_locks if present)",
+        uniqueness_keys: "uniqueness keys table (job deduplication)",
         add_job_stats: "job stats table (Insights dashboard)",
         add_job_stats_latency: "job stats latency columns (enqueue_latency_ms, retry_count)",
         add_job_stats_queue_index: "job stats (queue_name, created_at) index",
@@ -128,10 +130,9 @@ module Pgbus
         CORE_INSTALL_TABLES.none? { |t| table_exists?(t) }
       end
 
-      # Legacy pgbus_job_locks → modern pgbus_uniqueness_keys.
-      # The migrate_job_locks template is idempotent: it creates
-      # uniqueness_keys if missing and drops job_locks if present.
-      # One symbol covers both cases; see GENERATOR_MAP.
+      # Queue add_uniqueness_keys whenever the modern table is missing.
+      # This does not touch a legacy pgbus_job_locks table — that is
+      # handled separately by `pgbus:migrate_job_locks`, see GENERATOR_MAP.
       def uniqueness_key_migrations
         return [] if table_exists?("pgbus_uniqueness_keys")
 
@@ -180,8 +181,11 @@ module Pgbus
       def recurring_migrations
         # pgbus_recurring_tasks + pgbus_recurring_executions are the two
         # tables the recurring generator creates. If BOTH exist, nothing
-        # to do. If either is missing, we need the generator (which is
-        # idempotent via if_not_exists on both tables).
+        # to do. If either is missing, we queue the generator. The
+        # add_recurring template uses plain create_table (no if_not_exists),
+        # so idempotency is provided by this detector, not the template:
+        # the migration is only queued while a table is absent, and never
+        # re-invoked once both tables are present.
         return [] if table_exists?("pgbus_recurring_tasks") && table_exists?("pgbus_recurring_executions")
 
         [:add_recurring]

data/lib/pgbus/instrumentation.rb

@@ -21,7 +21,8 @@ module Pgbus
   #   pgbus.stream.broadcast       — stream broadcast (sync or deferred)
   #   pgbus.outbox.publish         — outbox row created
   #   pgbus.recurring.enqueue      — scheduler enqueued a due recurring task
-  #   pgbus.worker.recycle         — worker hit a recycle threshold
+  #   pgbus.worker.recycle         — worker hit a recycle threshold (reason/jobs_processed/memory_mb/lifetime_seconds)
+  #   pgbus.consumer.recycle       — consumer hit a recycle threshold (same payload shape as pgbus.worker.recycle)
   #   pgbus.serializer.serialize   — job/event serialization
   #   pgbus.serializer.deserialize — job/event deserialization
   #

data/lib/pgbus/integrations/appsignal/subscriber.rb

@@ -41,7 +41,13 @@ module Pgbus
               subscribe("pgbus.stream.broadcast") { |event| on_stream_broadcast(event) },
               subscribe("pgbus.outbox.publish") { |event| on_outbox_publish(event) },
               subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
-              subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) }
+              subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) },
+              subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) }
+              # pgbus.client.pool is deliberately NOT subscribed here — the
+              # minutely Probe#track_pool already reports pgbus_pool_size /
+              # pgbus_pool_available gauges for AppSignal (see probe.rb).
+              # Subscribing here too would double-report on every heartbeat
+              # and skew the gauges.
             ]
             @installed = true
           end
@@ -250,7 +256,16 @@ module Pgbus
             ::Appsignal.increment_counter(
               "#{METRIC_PREFIX}worker_recycled",
               1,
-              { reason: payload[:reason] }
+              { reason: payload[:reason], kind: "worker" }
+            )
+          end
+
+          def on_consumer_recycle(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}worker_recycled",
+              1,
+              { reason: payload[:reason], kind: "consumer" }
             )
           end
 

data/lib/pgbus/metrics/subscriber.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "socket"
+
 module Pgbus
   module Metrics
     # Consumes Pgbus::Instrumentation events and forwards them to the configured
@@ -36,7 +38,9 @@ module Pgbus
             subscribe("pgbus.stream.broadcast") { |event| on_stream_broadcast(event) },
             subscribe("pgbus.outbox.publish") { |event| on_outbox_publish(event) },
             subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
-            subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) }
+            subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) },
+            subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) },
+            subscribe("pgbus.client.pool") { |event| on_client_pool(event) }
           ]
           @installed = true
         end
@@ -176,10 +180,30 @@ module Pgbus
         def on_worker_recycle(event)
           backend.increment(
             "#{METRIC_PREFIX}worker_recycled", 1,
-            compact(reason: event.payload[:reason])
+            compact(reason: event.payload[:reason], kind: "worker")
+          )
+        end
+
+        def on_consumer_recycle(event)
+          backend.increment(
+            "#{METRIC_PREFIX}worker_recycled", 1,
+            compact(reason: event.payload[:reason], kind: "consumer")
           )
         end
 
+        # ── Connection pool ───────────────────────────────────────────────
+
+        def on_client_pool(event)
+          payload = event.payload
+          tags = { hostname: hostname }
+          backend.gauge("#{METRIC_PREFIX}pool_size", payload[:size], tags)
+          backend.gauge("#{METRIC_PREFIX}pool_available", payload[:available], tags)
+        end
+
+        def hostname
+          Socket.gethostname
+        end
+
         # Drop nil-valued tags so backends don't emit empty labels.
         def compact(tags)
           tags.compact

data/lib/pgbus/metrics.rb

@@ -3,8 +3,9 @@
 module Pgbus
   # Backend-agnostic metrics adapter.
   #
-  # Pgbus emits ~16 `pgbus.*` ActiveSupport::Notifications events (see
-  # Pgbus::Instrumentation). The AppSignal integration is one consumer of those
+  # Pgbus emits a family of `pgbus.*` ActiveSupport::Notifications events;
+  # `Pgbus::Instrumentation` is the single source of truth for the catalog. The
+  # AppSignal integration is one consumer of those
   # events; this namespace is a second, vendor-neutral consumer that forwards the
   # same event→metric mapping to a configurable backend so teams on Prometheus,
   # Datadog, or plain StatsD get metrics without hand-writing subscribers.