pgbus 0.6.6 → 0.6.8

data/config/locales/it.yml

@@ -10,6 +10,28 @@ it:
           pid: PID
           status: Stato
         title: Processi attivi
+      queue_health:
+        dead_tuples: Tuple morte
+        headers:
+          bloat: Bloat
+          dead: Morte
+          kind: Tipo
+          last_vacuum: Ultimo Vacuum
+          live: Attive
+          table: Tabella
+        kinds:
+          archive: Archivio
+          queue: Coda
+        last_vacuum: Ultimo Vacuum
+        live: Attive
+        mvcc_horizon: Orizzonte MVCC
+        oldest_open_txn: Transazione aperta più vecchia
+        oldest_vacuum_ago: Vacuum tabella più vecchio
+        tables_need_vacuum:
+          one: "%{count} tabella necessita di vacuum"
+          other: "%{count} tabelle necessitano di vacuum"
+        title: Salute delle Code
+        worst_bloat: Peggior Bloat
       queues_table:
         empty: Nessuna coda trovata
         headers:
@@ -337,6 +359,15 @@ it:
         resume: Riprendi
         retry: Riprova
         retry_confirm: Reimpostare il timeout di visibilità e riprovare?
+        table_health:
+          headers:
+            bloat: Bloat
+            dead: Morte
+            last_vacuum: Ultimo Vacuum
+            live: Attive
+            table: Tabella
+          oldest_txn: 'Transazione aperta più vecchia:'
+          title: Salute delle Tabelle
         total: 'Totale:'
         visible: 'Visibile:'
     recurring_tasks:
@@ -345,10 +376,6 @@ it:
           one: "%{count} attività configurata"
           other: "%{count} attività configurate"
         title: Attività ricorrenti
-      toggle:
-        disabled: Attività disabilitata
-        enabled: Attività abilitata
-        failed: Impossibile cambiare lo stato dell'attività
       show:
         back: Indietro
         configuration: Configurazione
@@ -392,3 +419,7 @@ it:
           task: Attività
         never: Mai
         run_now: Esegui ora
+      toggle:
+        disabled: Attività disabilitata
+        enabled: Attività abilitata
+        failed: Impossibile cambiare lo stato dell'attività

data/config/locales/ja.yml

@@ -10,6 +10,28 @@ ja:
           pid: PID
           status: ステータス
         title: アクティブなプロセス
+      queue_health:
+        dead_tuples: デッドタプル
+        headers:
+          bloat: Bloat
+          dead: デッド
+          kind: 種類
+          last_vacuum: 最終Vacuum
+          live: ライブ
+          table: テーブル
+        kinds:
+          archive: アーカイブ
+          queue: キュー
+        last_vacuum: 最終Vacuum
+        live: ライブ
+        mvcc_horizon: MVCCホライズン
+        oldest_open_txn: 最も古い未完了トランザクション
+        oldest_vacuum_ago: 最も古いテーブルvacuum
+        tables_need_vacuum:
+          one: "%{count} テーブルがvacuumを必要としています"
+          other: "%{count} テーブルがvacuumを必要としています"
+        title: キューの健全性
+        worst_bloat: 最悪のBloat
       queues_table:
         empty: キューが見つかりません
         headers:
@@ -337,6 +359,15 @@ ja:
         resume: 再開
         retry: リトライ
         retry_confirm: 可視性タイムアウトをリセットしてリトライしますか？
+        table_health:
+          headers:
+            bloat: Bloat
+            dead: デッド
+            last_vacuum: 最終Vacuum
+            live: ライブ
+            table: テーブル
+          oldest_txn: '最も古い未完了トランザクション:'
+          title: テーブルの健全性
         total: 合計：
         visible: 表示中：
     recurring_tasks:
@@ -345,10 +376,6 @@ ja:
           one: "%{count} タスクが設定されています"
           other: "%{count} タスクが設定されています"
         title: 定期タスク
-      toggle:
-        disabled: タスクが無効になりました
-        enabled: タスクが有効になりました
-        failed: タスクの切り替えに失敗しました
       show:
         back: 戻る
         configuration: 設定
@@ -392,3 +419,7 @@ ja:
           task: タスク
         never: なし
         run_now: 今すぐ実行
+      toggle:
+        disabled: タスクが無効になりました
+        enabled: タスクが有効になりました
+        failed: タスクの切り替えに失敗しました

data/config/locales/nb.yml

@@ -10,6 +10,28 @@ nb:
           pid: PID
           status: Status
         title: Aktive prosesser
+      queue_health:
+        dead_tuples: Døde tupler
+        headers:
+          bloat: Bloat
+          dead: Døde
+          kind: Type
+          last_vacuum: Siste Vacuum
+          live: Levende
+          table: Tabell
+        kinds:
+          archive: Arkiv
+          queue: Kø
+        last_vacuum: Siste Vacuum
+        live: Levende
+        mvcc_horizon: MVCC-horisont
+        oldest_open_txn: Eldste åpne transaksjon
+        oldest_vacuum_ago: Eldste tabell-vacuum
+        tables_need_vacuum:
+          one: "%{count} tabell trenger vacuum"
+          other: "%{count} tabeller trenger vacuum"
+        title: Køhelse
+        worst_bloat: Verste Bloat
       queues_table:
         empty: Ingen køer funnet
         headers:
@@ -337,6 +359,15 @@ nb:
         resume: Gjenoppta
         retry: Prøv igjen
         retry_confirm: Tilbakestill synlighetstidsavbrudd og prøv igjen?
+        table_health:
+          headers:
+            bloat: Bloat
+            dead: Døde
+            last_vacuum: Siste Vacuum
+            live: Levende
+            table: Tabell
+          oldest_txn: 'Eldste åpne transaksjon:'
+          title: Tabellhelse
         total: 'Totalt:'
         visible: 'Synlig:'
     recurring_tasks:
@@ -345,10 +376,6 @@ nb:
           one: "%{count} oppgave konfigurert"
           other: "%{count} oppgaver konfigurert"
         title: Gjentakende oppgaver
-      toggle:
-        disabled: Oppgave deaktivert
-        enabled: Oppgave aktivert
-        failed: Kunne ikke endre oppgave
       show:
         back: Tilbake
         configuration: Konfigurasjon
@@ -392,3 +419,7 @@ nb:
           task: Oppgave
         never: Aldri
         run_now: Kjør nå
+      toggle:
+        disabled: Oppgave deaktivert
+        enabled: Oppgave aktivert
+        failed: Kunne ikke endre oppgave

data/config/locales/nl.yml

@@ -10,6 +10,28 @@ nl:
           pid: PID
           status: Status
         title: Actieve processen
+      queue_health:
+        dead_tuples: Dode tupels
+        headers:
+          bloat: Bloat
+          dead: Dood
+          kind: Type
+          last_vacuum: Laatste Vacuum
+          live: Actief
+          table: Tabel
+        kinds:
+          archive: Archief
+          queue: Wachtrij
+        last_vacuum: Laatste Vacuum
+        live: Actief
+        mvcc_horizon: MVCC-horizon
+        oldest_open_txn: Oudste open transactie
+        oldest_vacuum_ago: Oudste tabel-vacuum
+        tables_need_vacuum:
+          one: "%{count} tabel heeft vacuum nodig"
+          other: "%{count} tabellen hebben vacuum nodig"
+        title: Wachtrijgezondheid
+        worst_bloat: Ergste Bloat
       queues_table:
         empty: Geen wachtrijen gevonden
         headers:
@@ -337,6 +359,15 @@ nl:
         resume: Hervatten
         retry: Opnieuw proberen
         retry_confirm: Zichtbaarheidstimeout resetten en opnieuw proberen?
+        table_health:
+          headers:
+            bloat: Bloat
+            dead: Dood
+            last_vacuum: Laatste Vacuum
+            live: Actief
+            table: Tabel
+          oldest_txn: 'Oudste open transactie:'
+          title: Tabelgezondheid
         total: 'Totaal:'
         visible: 'Zichtbaar:'
     recurring_tasks:
@@ -345,10 +376,6 @@ nl:
           one: "%{count} taak geconfigureerd"
           other: "%{count} taken geconfigureerd"
         title: Terugkerende taken
-      toggle:
-        disabled: Taak uitgeschakeld
-        enabled: Taak ingeschakeld
-        failed: Kon taak niet omschakelen
       show:
         back: Terug
         configuration: Configuratie
@@ -392,3 +419,7 @@ nl:
           task: Taak
         never: Nooit
         run_now: Nu uitvoeren
+      toggle:
+        disabled: Taak uitgeschakeld
+        enabled: Taak ingeschakeld
+        failed: Kon taak niet omschakelen

data/config/locales/pt.yml

@@ -10,6 +10,28 @@ pt:
           pid: PID
           status: Status
         title: Processos Ativos
+      queue_health:
+        dead_tuples: Tuplas mortas
+        headers:
+          bloat: Bloat
+          dead: Mortas
+          kind: Tipo
+          last_vacuum: Último Vacuum
+          live: Ativas
+          table: Tabela
+        kinds:
+          archive: Arquivo
+          queue: Fila
+        last_vacuum: Último Vacuum
+        live: Ativas
+        mvcc_horizon: Horizonte MVCC
+        oldest_open_txn: Transação aberta mais antiga
+        oldest_vacuum_ago: Vacuum de tabela mais antigo
+        tables_need_vacuum:
+          one: "%{count} tabela precisa de vacuum"
+          other: "%{count} tabelas precisam de vacuum"
+        title: Saúde das Filas
+        worst_bloat: Pior Bloat
       queues_table:
         empty: Nenhuma fila encontrada
         headers:
@@ -337,6 +359,15 @@ pt:
         resume: Retomar
         retry: Tentar novamente
         retry_confirm: Redefinir tempo de visibilidade e tentar novamente?
+        table_health:
+          headers:
+            bloat: Bloat
+            dead: Mortas
+            last_vacuum: Último Vacuum
+            live: Ativas
+            table: Tabela
+          oldest_txn: 'Transação aberta mais antiga:'
+          title: Saúde das Tabelas
         total: 'Total:'
         visible: 'Visível:'
     recurring_tasks:
@@ -345,10 +376,6 @@ pt:
           one: "%{count} tarefa configurada"
           other: "%{count} tarefas configuradas"
         title: Tarefas Recorrentes
-      toggle:
-        disabled: Tarefa desativada
-        enabled: Tarefa ativada
-        failed: Falha ao alternar tarefa
       show:
         back: Voltar
         configuration: Configuração
@@ -392,3 +419,7 @@ pt:
           task: Tarefa
         never: Nunca
         run_now: Executar Agora
+      toggle:
+        disabled: Tarefa desativada
+        enabled: Tarefa ativada
+        failed: Falha ao alternar tarefa

data/config/locales/sv.yml

@@ -10,6 +10,28 @@ sv:
           pid: PID
           status: Status
         title: Aktiva processer
+      queue_health:
+        dead_tuples: Döda tuplar
+        headers:
+          bloat: Bloat
+          dead: Döda
+          kind: Typ
+          last_vacuum: Senaste Vacuum
+          live: Levande
+          table: Tabell
+        kinds:
+          archive: Arkiv
+          queue: Kö
+        last_vacuum: Senaste Vacuum
+        live: Levande
+        mvcc_horizon: MVCC-horisont
+        oldest_open_txn: Äldsta öppna transaktion
+        oldest_vacuum_ago: Äldsta tabell-vacuum
+        tables_need_vacuum:
+          one: "%{count} tabell behöver vacuum"
+          other: "%{count} tabeller behöver vacuum"
+        title: Köhälsa
+        worst_bloat: Värsta Bloat
       queues_table:
         empty: Inga köer hittades
         headers:
@@ -337,6 +359,15 @@ sv:
         resume: Återuppta
         retry: Försök igen
         retry_confirm: Återställ synlighetstimeout och försök igen?
+        table_health:
+          headers:
+            bloat: Bloat
+            dead: Döda
+            last_vacuum: Senaste Vacuum
+            live: Levande
+            table: Tabell
+          oldest_txn: 'Äldsta öppna transaktion:'
+          title: Tabellhälsa
         total: 'Totalt:'
         visible: 'Synliga:'
     recurring_tasks:
@@ -345,10 +376,6 @@ sv:
           one: "%{count} uppgift konfigurerad"
           other: "%{count} uppgifter konfigurerade"
         title: Återkommande uppgifter
-      toggle:
-        disabled: Uppgift inaktiverad
-        enabled: Uppgift aktiverad
-        failed: Kunde inte ändra uppgift
       show:
         back: Tillbaka
         configuration: Konfiguration
@@ -392,3 +419,7 @@ sv:
           task: Uppgift
         never: Aldrig
         run_now: Kör nu
+      toggle:
+        disabled: Uppgift inaktiverad
+        enabled: Uppgift aktiverad
+        failed: Kunde inte ändra uppgift

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -150,6 +150,12 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     # Create default queues via PGMQ
     execute "SELECT pgmq.create('pgbus_default')"
     execute "SELECT pgmq.create('pgbus_default_dlq')"
+
+    # Tune autovacuum for queue/archive tables and high-churn pgbus tables.
+    # Default settings are too conservative for the insert/delete churn of
+    # queue processing and concurrency lock management.
+    execute Pgbus::AutovacuumTuning.sql_for_all_queues
+    execute Pgbus::AutovacuumTuning.sql_for_high_churn_tables
   end
 
   def down

data/lib/generators/pgbus/templates/tune_autovacuum.rb.erb

@@ -0,0 +1,38 @@
+class TunePgbusAutovacuum < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # Apply aggressive autovacuum settings to all existing PGMQ queue and
+    # archive tables. Queue tables have very high insert/delete churn from
+    # the read→process→archive cycle; default autovacuum settings (vacuum
+    # at 20% dead tuples) allow dead tuple accumulation that bloats indexes
+    # and degrades lock acquisition times.
+    #
+    # New queues created after this migration automatically receive these
+    # settings via Pgbus::Client at queue creation time.
+    execute Pgbus::AutovacuumTuning.sql_for_all_queues
+
+    # Also tune pgbus-owned tables with high write churn:
+    # - pgbus_semaphores: rapid upsert+increment per job, periodic expiry
+    # - pgbus_uniqueness_keys: INSERT on enqueue, DELETE on completion
+    # - pgbus_processed_events: INSERT per event, bulk DELETE on TTL expiry
+    execute Pgbus::AutovacuumTuning.sql_for_high_churn_tables
+  end
+
+  def down
+    # Reset to PostgreSQL defaults
+    execute <<~SQL
+      DO $$
+      DECLARE
+        q RECORD;
+      BEGIN
+        FOR q IN SELECT queue_name FROM pgmq.meta LOOP
+          EXECUTE format('ALTER TABLE pgmq.q_%I RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)', q.queue_name);
+          EXECUTE format('ALTER TABLE pgmq.a_%I RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)', q.queue_name);
+        END LOOP;
+      END $$;
+    SQL
+
+    Pgbus::AutovacuumTuning::HIGH_CHURN_TABLES.each do |table|
+      execute "ALTER TABLE #{table} RESET (autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_analyze_scale_factor)"
+    end
+  end
+end

data/lib/generators/pgbus/tune_autovacuum_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class TuneAutovacuumGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Tune autovacuum settings on PGMQ queue and archive tables for optimal queue health"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        if separate_database?
+          migration_template "tune_autovacuum.rb.erb",
+                             "db/pgbus_migrate/tune_pgbus_autovacuum.rb"
+        else
+          migration_template "tune_autovacuum.rb.erb",
+                             "db/migrate/tune_pgbus_autovacuum.rb"
+        end
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus autovacuum tuning migration created!", :green
+        say ""
+        say "This migration applies aggressive autovacuum settings to all existing"
+        say "PGMQ queue and archive tables. New queues created at runtime will"
+        say "automatically receive these settings."
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Restart pgbus: bin/pgbus start"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

data/lib/pgbus/autovacuum_tuning.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Shared autovacuum storage parameters for tables with high write churn.
+  #
+  # Queue tables (q_*) have high insert/delete churn: every read + archive
+  # cycle deletes from q_ and inserts into a_. Default autovacuum settings
+  # (vacuum at 20% dead tuples) are far too conservative — dead tuples
+  # accumulate, bloat B-tree indexes, and eventually degrade lock acquisition
+  # times. See: https://planetscale.com/blog/keeping-a-postgres-queue-healthy
+  #
+  # Several pgbus-owned tables share similar churn patterns:
+  # - pgbus_semaphores: rapid upsert+increment per job, periodic expiry
+  # - pgbus_uniqueness_keys: INSERT on enqueue, DELETE on completion
+  # - pgbus_processed_events: INSERT per event, bulk DELETE on TTL expiry
+  #
+  # Used by:
+  # - Client#ensure_single_queue (runtime, on queue creation)
+  # - CreatePgbusTables migration (fresh install)
+  # - TunePgbusAutovacuum migration (upgrade for existing installations)
+  module AutovacuumTuning
+    # Queue tables: very aggressive — high delete rate from read+archive.
+    QUEUE_SETTINGS = {
+      "autovacuum_vacuum_scale_factor" => "0.01",
+      "autovacuum_vacuum_cost_delay" => "2",
+      "autovacuum_analyze_scale_factor" => "0.05"
+    }.freeze
+
+    # Archive tables: moderately aggressive — append-heavy with periodic purge.
+    ARCHIVE_SETTINGS = {
+      "autovacuum_vacuum_scale_factor" => "0.05",
+      "autovacuum_vacuum_cost_delay" => "5",
+      "autovacuum_analyze_scale_factor" => "0.05"
+    }.freeze
+
+    # High-churn pgbus tables: rapid INSERT/DELETE or upsert cycles.
+    # - semaphores: upsert + increment per job acquire, decrement on release, periodic expiry
+    # - uniqueness_keys: INSERT on enqueue, DELETE on job completion (fast lifecycle)
+    # - processed_events: INSERT per event handler, bulk DELETE on idempotency TTL expiry
+    HIGH_CHURN_SETTINGS = {
+      "autovacuum_vacuum_scale_factor" => "0.02",
+      "autovacuum_vacuum_cost_delay" => "2",
+      "autovacuum_analyze_scale_factor" => "0.05"
+    }.freeze
+
+    HIGH_CHURN_TABLES = %w[
+      pgbus_semaphores
+      pgbus_uniqueness_keys
+      pgbus_processed_events
+    ].freeze
+
+    class << self
+      # Generate ALTER TABLE SQL for a single queue's tables.
+      def sql_for_queue(queue_name)
+        [
+          alter_table_sql("pgmq.q_#{queue_name}", QUEUE_SETTINGS),
+          alter_table_sql("pgmq.a_#{queue_name}", ARCHIVE_SETTINGS)
+        ].join("\n")
+      end
+
+      # Generate ALTER TABLE SQL for all queues discovered via pgmq.meta.
+      def sql_for_all_queues
+        <<~SQL
+          DO $$
+          DECLARE
+            q RECORD;
+          BEGIN
+            FOR q IN SELECT queue_name FROM pgmq.meta LOOP
+              EXECUTE format('ALTER TABLE pgmq.q_%I SET (#{settings_clause(QUEUE_SETTINGS)})', q.queue_name);
+              EXECUTE format('ALTER TABLE pgmq.a_%I SET (#{settings_clause(ARCHIVE_SETTINGS)})', q.queue_name);
+            END LOOP;
+          END $$;
+        SQL
+      end
+
+      # Generate ALTER TABLE SQL for pgbus-owned high-churn tables.
+      def sql_for_high_churn_tables
+        HIGH_CHURN_TABLES.map { |table| alter_table_sql(table, HIGH_CHURN_SETTINGS, if_exists: true) }.join("\n")
+      end
+
+      private
+
+      def alter_table_sql(table, settings, if_exists: false)
+        prefix = if_exists ? "ALTER TABLE IF EXISTS" : "ALTER TABLE"
+        "#{prefix} #{table} SET (#{settings_clause(settings)});"
+      end
+
+      def settings_clause(settings)
+        settings.map { |k, v| "#{k} = #{v}" }.join(", ")
+      end
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -75,7 +75,10 @@ module Pgbus
       return if @queues_created[dlq_name]
 
       @queues_created.compute_if_absent(dlq_name) do
-        synchronized { @pgmq.create(dlq_name) }
+        synchronized do
+          @pgmq.create(dlq_name)
+          tune_autovacuum(dlq_name)
+        end
         true
       end
     end
@@ -446,12 +449,21 @@ module Pgbus
       @queues_created.compute_if_absent(full_name) do
         synchronized do
           @pgmq.create(full_name)
+          tune_autovacuum(full_name)
           @pgmq.enable_notify_insert(full_name, throttle_interval_ms: NOTIFY_THROTTLE_MS) if config.listen_notify
         end
         true
       end
     end
 
+    def tune_autovacuum(queue_name)
+      with_raw_connection do |conn|
+        conn.exec(AutovacuumTuning.sql_for_queue(queue_name))
+      end
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus::Client] Autovacuum tuning failed for #{queue_name}: #{e.message}" }
+    end
+
     # Serialize PGMQ operations through a mutex when sharing a connection
     # with ActiveRecord (Proc path). When pgmq-ruby owns its own connections
     # (String/Hash path), the internal connection_pool handles concurrency.

data/lib/pgbus/engine.rb

@@ -66,6 +66,29 @@ module Pgbus
       app.middleware.use Pgbus::Streams::WatermarkCacheMiddleware if Pgbus.configuration.streams_enabled
     end
 
+    # Make stream_source_element.js available to the host app's asset
+    # pipeline (Propshaft or Sprockets) so it can be included via
+    # `javascript_include_tag "pgbus/stream_source_element"` or pinned
+    # in importmap. When importmap-rails is loaded, auto-pin it so
+    # host apps get it without manual configuration.
+    initializer "pgbus.streams.assets" do |app|
+      if Pgbus.configuration.streams_enabled && app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[pgbus/stream_source_element.js]
+      end
+    end
+
+    initializer "pgbus.streams.importmap" do
+      if Pgbus.configuration.streams_enabled && defined?(::Importmap::Map)
+        ActiveSupport.on_load(:after_initialize) do
+          next unless Rails.application.respond_to?(:importmap)
+
+          Rails.application.importmap.pin(
+            "pgbus/stream_source_element", to: "pgbus/stream_source_element.js"
+          )
+        end
+      end
+    end
+
     # Install the Turbo::StreamsChannel patch after turbo-rails has been
     # loaded. The patch redirects broadcast_stream_to through Pgbus.stream
     # instead of ActionCable. When turbo-rails is not loaded, this is a