pgbus 0.6.7 → 0.6.8

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/generators/migration_detector.rb

@@ -73,7 +73,8 @@ module Pgbus
         add_queue_states: "pgbus:add_queue_states",
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
-        add_failed_events_index: "pgbus:add_failed_events_index"
+        add_failed_events_index: "pgbus:add_failed_events_index",
+        tune_autovacuum: "pgbus:tune_autovacuum"
       }.freeze
 
       # Human-friendly description of each migration for the generator
@@ -88,7 +89,8 @@ module Pgbus
         add_queue_states: "queue states table (pause/resume)",
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
-        add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)"
+        add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
+        tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables"
       }.freeze
 
       def initialize(connection)
@@ -110,7 +112,8 @@ module Pgbus
           *queue_states_migrations,
           *outbox_migrations,
           *recurring_migrations,
-          *failed_events_index_migrations
+          *failed_events_index_migrations,
+          *autovacuum_migrations
         ]
       end
 
@@ -193,6 +196,15 @@ module Pgbus
         [:add_failed_events_index]
       end
 
+      # Autovacuum tuning: check if any PGMQ queue table already has
+      # custom autovacuum settings applied. If not, queue the migration.
+      def autovacuum_migrations
+        return [] unless pgmq_schema_exists?
+        return [] if autovacuum_already_tuned?
+
+        [:tune_autovacuum]
+      end
+
       # --- schema probes -------------------------------------------------
 
       def table_exists?(name)
@@ -212,6 +224,29 @@ module Pgbus
       rescue StandardError
         false
       end
+
+      def pgmq_schema_exists?
+        result = connection.select_value("SELECT 1 FROM information_schema.schemata WHERE schema_name = 'pgmq'")
+        result.present?
+      rescue StandardError
+        false
+      end
+
+      def autovacuum_already_tuned?
+        queue_name = connection.select_value("SELECT queue_name FROM pgmq.meta ORDER BY queue_name LIMIT 1")
+        return true unless queue_name # no queues = nothing to tune, skip
+
+        result = connection.select_value(<<~SQL)
+          SELECT reloptions::text LIKE '%autovacuum_vacuum_scale_factor%'
+          FROM pg_class
+          WHERE relname = 'q_#{queue_name}'
+            AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'pgmq')
+        SQL
+
+        [true, "t"].include?(result)
+      rescue StandardError
+        true # if we can't tell, assume already tuned (safe default)
+      end
     end
   end
 end

data/lib/pgbus/version.rb

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