pgbus 0.18.2 → 0.19.1

data/config/locales/nl.yml

@@ -236,6 +236,102 @@ nl:
         payload: Inhoud
         retry: Opnieuw proberen
         title: 'DLQ Bericht #%{id}'
+    deploy_tasks:
+      banner:
+        heading: Uitrol
+        lagging_html:
+          one: 'Wacht op uitrol: 1 proces draait nog niet op <code>%{revision}</code>.'
+          other: 'Wacht op uitrol: %{count} processen draaien nog niet op <code>%{revision}</code>.'
+        lagging_more: "…en nog %{count}"
+        lagging_process: "%{kind}@%{hostname} pid %{pid} op %{revision}"
+        live_count: "%{count} op %{revision}"
+        live_heading: 'Actieve processen:'
+        no_revision_hint_html: Stel <code>config.app_revision</code> in, of een van <code>PGBUS_REVISION</code>, <code>DASH_VERSION</code> of <code>KAMAL_VERSION</code>, of lever een <code>REVISION</code>-bestand mee. Nu uitvoeren werkt nog steeds.
+        no_revision_html: 'App-revisie niet geconfigureerd: deploy-taken wachten tot die er is.'
+        no_revision_label: geen revisie
+        no_scheduler_html: 'Er draait geen scheduler: deploy-taken worden alleen door de scheduler gestart. Dit oordeel gebruikt de eigen revisie van het dashboard.'
+        no_workers_html: 'Wacht op uitrol: nog geen worker op <code>%{revision}</code>.'
+        ready_html: 'Uitgerold: elk actief proces draait <code>%{revision}</code>. Klaargezette taken draaien bij de volgende tick van de scheduler.'
+        unavailable_html: De uitrolstatus kon niet worden gelezen.
+      default_queue: default
+      disable: Uitschakelen
+      enable: Inschakelen
+      enqueue:
+        enqueued: Deploy-taak in de wachtrij gezet
+        failed: 'De deploy-taak is niet in de wachtrij gezet: zie het log voor de reden'
+      every_deploy: Bij elke deploy
+      index:
+        task_count:
+          one: "%{count} taak gedeclareerd"
+          other: "%{count} taken gedeclareerd"
+        title: Deploy-taken
+      not_found: Deploy-taak niet gevonden
+      reasons:
+        disabled_armed_html: 'Uitgeschakeld met een uitrolrun in afwachting: schakel hem in om hem te laten draaien.'
+        disabled_html: 'Uitgeschakeld: de scheduler slaat hem over.'
+        due_html: 'Klaar: draait bij de volgende tick van de scheduler.'
+        manual_html: "· draaide %{ago} (handmatig)"
+        never_html: Nooit gedraaid na een uitrol.
+        ran_html: Draaide %{ago} op <code>%{revision}</code> (uitrol).
+        waiting_lagging_html:
+          one: 'Wacht op uitrol: 1 proces draait nog niet op <code>%{revision}</code>.'
+          other: 'Wacht op uitrol: %{count} processen draaien nog niet op <code>%{revision}</code>.'
+        waiting_no_revision_html: 'Wacht: de app-revisie is niet geconfigureerd.'
+        waiting_no_scheduler_html: 'Wacht: er draait geen scheduler.'
+        waiting_no_workers_html: Wacht op een worker op <code>%{revision}</code>.
+        waiting_unknown_html: 'Wacht: de uitrolstatus kon niet worden gelezen.'
+      run_now: Nu uitvoeren
+      show:
+        armed_html: "%{armed_for}, klaargezet %{ago}"
+        back: Terug
+        configuration: Configuratie
+        labels:
+          arguments: Argumenten
+          armed: Openstaande run
+          command: Commando
+          description: Beschrijving
+          job_class: Jobklasse
+          priority: Prioriteit
+          queue: Wachtrij
+          source: Bron
+        last_run: Laatste run
+        no_runs: Nog geen runs vastgelegd
+        recent_runs: Recente runs
+        run_headers:
+          enqueued_at: In wachtrij gezet
+          queue: Wachtrij
+          revision: Revisie
+          triggered_by: Gestart door
+          version: Versie
+        source_config: Configuratiebestand
+        source_dynamic: Dynamisch
+        state: Status
+        version: Versie
+      states:
+        disabled: Uitgeschakeld
+        due: Klaar
+        never: Nooit gedraaid
+        ran: Gedraaid
+        waiting: Wacht
+      tasks_table:
+        empty_hint_html: Declareer eenmalige taken in <code>config/deploy_tasks.yml</code>; <code>rails generate pgbus:add_deploy_tasks</code> schrijft een startbestand.
+        empty_title: Geen deploy-taken gedeclareerd
+        headers:
+          actions: Acties
+          last_run: Laatste run
+          queue: Wachtrij
+          state: Status
+          task: Taak
+          version: Versie
+        never: Nooit
+      toggle:
+        disabled: Deploy-taak uitgeschakeld
+        enabled: Deploy-taak ingeschakeld
+        failed: Omschakelen van de deploy-taak mislukt
+      triggered_by:
+        manual: Handmatig
+        rollover: Uitrol
+      version: v%{version}
     dialogs:
       cancel: Annuleren
       confirm: Bevestigen
@@ -617,6 +713,7 @@ nl:
       nav:
         batches: Groepen
         dashboard: Dashboard
+        deploy_tasks: Deploy
         dlq: DLQ
         events: Evenementen
         insights: Inzichten

data/config/locales/pt.yml

@@ -236,6 +236,102 @@ pt:
         payload: Carga útil
         retry: Tentar novamente
         title: 'Mensagem DLQ #%{id}'
+    deploy_tasks:
+      banner:
+        heading: Transição
+        lagging_html:
+          one: 'Aguardando a transição: 1 processo ainda não executa <code>%{revision}</code>.'
+          other: 'Aguardando a transição: %{count} processos ainda não executam <code>%{revision}</code>.'
+        lagging_more: "…e mais %{count}"
+        lagging_process: "%{kind}@%{hostname} pid %{pid} em %{revision}"
+        live_count: "%{count} em %{revision}"
+        live_heading: 'Processos ativos:'
+        no_revision_hint_html: Defina <code>config.app_revision</code>, ou uma de <code>PGBUS_REVISION</code>, <code>DASH_VERSION</code> ou <code>KAMAL_VERSION</code>, ou inclua um arquivo <code>REVISION</code>. Executar agora continua funcionando.
+        no_revision_html: 'Revisão da aplicação não configurada: as tarefas de deploy aguardam até que esteja.'
+        no_revision_label: sem revisão
+        no_scheduler_html: 'Nenhum agendador em execução: as tarefas de deploy só são disparadas pelo agendador. Este veredito usa a revisão do próprio painel.'
+        no_workers_html: 'Aguardando a transição: ainda nenhum worker em <code>%{revision}</code>.'
+        ready_html: 'Transição concluída: cada processo ativo executa <code>%{revision}</code>. Tarefas armadas executam no próximo tick do agendador.'
+        unavailable_html: Não foi possível ler o estado da transição.
+      default_queue: default
+      disable: Desativar
+      enable: Ativar
+      enqueue:
+        enqueued: Tarefa de deploy enfileirada
+        failed: 'A tarefa de deploy não foi enfileirada: veja o log para o motivo'
+      every_deploy: Em todo deploy
+      index:
+        task_count:
+          one: "%{count} tarefa declarada"
+          other: "%{count} tarefas declaradas"
+        title: Tarefas de deploy
+      not_found: Tarefa de deploy não encontrada
+      reasons:
+        disabled_armed_html: 'Desativada com uma execução de transição pendente: ative-a para deixá-la executar.'
+        disabled_html: 'Desativada: o agendador a ignora.'
+        due_html: 'Pronta: executa no próximo tick do agendador.'
+        manual_html: "· executada %{ago} (manual)"
+        never_html: Nunca executada após uma transição.
+        ran_html: Executada %{ago} em <code>%{revision}</code> (transição).
+        waiting_lagging_html:
+          one: 'Aguardando a transição: 1 processo ainda não executa <code>%{revision}</code>.'
+          other: 'Aguardando a transição: %{count} processos ainda não executam <code>%{revision}</code>.'
+        waiting_no_revision_html: 'Aguardando: a revisão da aplicação não está configurada.'
+        waiting_no_scheduler_html: 'Aguardando: nenhum agendador em execução.'
+        waiting_no_workers_html: Aguardando um worker em <code>%{revision}</code>.
+        waiting_unknown_html: 'Aguardando: não foi possível ler o estado da transição.'
+      run_now: Executar agora
+      show:
+        armed_html: "%{armed_for}, armada %{ago}"
+        back: Voltar
+        configuration: Configuração
+        labels:
+          arguments: Argumentos
+          armed: Execução pendente
+          command: Comando
+          description: Descrição
+          job_class: Classe do job
+          priority: Prioridade
+          queue: Fila
+          source: Origem
+        last_run: Última execução
+        no_runs: Nenhuma execução registrada ainda
+        recent_runs: Execuções recentes
+        run_headers:
+          enqueued_at: Enfileirada em
+          queue: Fila
+          revision: Revisão
+          triggered_by: Disparada por
+          version: Versão
+        source_config: Arquivo de configuração
+        source_dynamic: Dinâmica
+        state: Estado
+        version: Versão
+      states:
+        disabled: Desativada
+        due: Pronta
+        never: Nunca executada
+        ran: Executada
+        waiting: Aguardando
+      tasks_table:
+        empty_hint_html: Declare tarefas pontuais em <code>config/deploy_tasks.yml</code>; <code>rails generate pgbus:add_deploy_tasks</code> cria um arquivo inicial.
+        empty_title: Nenhuma tarefa de deploy declarada
+        headers:
+          actions: Ações
+          last_run: Última execução
+          queue: Fila
+          state: Estado
+          task: Tarefa
+          version: Versão
+        never: Nunca
+      toggle:
+        disabled: Tarefa de deploy desativada
+        enabled: Tarefa de deploy ativada
+        failed: Falha ao alternar a tarefa de deploy
+      triggered_by:
+        manual: Manual
+        rollover: Transição
+      version: v%{version}
     dialogs:
       cancel: Cancelar
       confirm: Confirmar
@@ -617,6 +713,7 @@ pt:
       nav:
         batches: Lotes
         dashboard: Painel
+        deploy_tasks: Deploy
         dlq: DLQ
         events: Eventos
         insights: Insights

data/config/locales/sv.yml

@@ -236,6 +236,102 @@ sv:
         payload: Innehåll
         retry: Försök igen
         title: 'DLQ-meddelande #%{id}'
+    deploy_tasks:
+      banner:
+        heading: Utrullning
+        lagging_html:
+          one: 'Väntar på utrullning: 1 process kör ännu inte <code>%{revision}</code>.'
+          other: 'Väntar på utrullning: %{count} processer kör ännu inte <code>%{revision}</code>.'
+        lagging_more: "…och %{count} till"
+        lagging_process: "%{kind}@%{hostname} pid %{pid} på %{revision}"
+        live_count: "%{count} på %{revision}"
+        live_heading: 'Aktiva processer:'
+        no_revision_hint_html: Sätt <code>config.app_revision</code>, eller någon av <code>PGBUS_REVISION</code>, <code>DASH_VERSION</code> eller <code>KAMAL_VERSION</code>, eller leverera en <code>REVISION</code>-fil. Kör nu fungerar fortfarande.
+        no_revision_html: 'Appens revision är inte konfigurerad: deploy-uppgifter väntar tills den är det.'
+        no_revision_label: ingen revision
+        no_scheduler_html: 'Ingen schemaläggare körs: deploy-uppgifter startas bara av schemaläggaren. Bedömningen använder instrumentpanelens egen revision.'
+        no_workers_html: 'Väntar på utrullning: ingen worker på <code>%{revision}</code> ännu.'
+        ready_html: 'Utrullad: varje aktiv process kör <code>%{revision}</code>. Väntande uppgifter körs vid schemaläggarens nästa tick.'
+        unavailable_html: Utrullningsstatusen kunde inte läsas.
+      default_queue: default
+      disable: Inaktivera
+      enable: Aktivera
+      enqueue:
+        enqueued: Deploy-uppgiften köad
+        failed: 'Deploy-uppgiften köades inte: se loggen för orsaken'
+      every_deploy: Vid varje deploy
+      index:
+        task_count:
+          one: "%{count} uppgift deklarerad"
+          other: "%{count} uppgifter deklarerade"
+        title: Deploy-uppgifter
+      not_found: Deploy-uppgiften hittades inte
+      reasons:
+        disabled_armed_html: 'Inaktiverad med en väntande utrullningskörning: aktivera den för att låta den köras.'
+        disabled_html: 'Inaktiverad: schemaläggaren hoppar över den.'
+        due_html: 'Redo: körs vid schemaläggarens nästa tick.'
+        manual_html: "· kördes %{ago} (manuellt)"
+        never_html: Har aldrig körts efter en utrullning.
+        ran_html: Kördes %{ago} på <code>%{revision}</code> (utrullning).
+        waiting_lagging_html:
+          one: 'Väntar på utrullning: 1 process kör ännu inte <code>%{revision}</code>.'
+          other: 'Väntar på utrullning: %{count} processer kör ännu inte <code>%{revision}</code>.'
+        waiting_no_revision_html: 'Väntar: appens revision är inte konfigurerad.'
+        waiting_no_scheduler_html: 'Väntar: ingen schemaläggare körs.'
+        waiting_no_workers_html: Väntar på en worker på <code>%{revision}</code>.
+        waiting_unknown_html: 'Väntar: utrullningsstatusen kunde inte läsas.'
+      run_now: Kör nu
+      show:
+        armed_html: "%{armed_for}, förberedd %{ago}"
+        back: Tillbaka
+        configuration: Konfiguration
+        labels:
+          arguments: Argument
+          armed: Väntande körning
+          command: Kommando
+          description: Beskrivning
+          job_class: Jobbklass
+          priority: Prioritet
+          queue: Kö
+          source: Källa
+        last_run: Senaste körning
+        no_runs: Inga körningar registrerade ännu
+        recent_runs: Senaste körningar
+        run_headers:
+          enqueued_at: Köad
+          queue: Kö
+          revision: Revision
+          triggered_by: Startad av
+          version: Version
+        source_config: Konfigurationsfil
+        source_dynamic: Dynamisk
+        state: Tillstånd
+        version: Version
+      states:
+        disabled: Inaktiverad
+        due: Redo
+        never: Aldrig körd
+        ran: Körd
+        waiting: Väntar
+      tasks_table:
+        empty_hint_html: Deklarera engångsuppgifter i <code>config/deploy_tasks.yml</code>; <code>rails generate pgbus:add_deploy_tasks</code> skapar en startfil.
+        empty_title: Inga deploy-uppgifter deklarerade
+        headers:
+          actions: Åtgärder
+          last_run: Senaste körning
+          queue: Kö
+          state: Tillstånd
+          task: Uppgift
+          version: Version
+        never: Aldrig
+      toggle:
+        disabled: Deploy-uppgiften inaktiverad
+        enabled: Deploy-uppgiften aktiverad
+        failed: Det gick inte att växla deploy-uppgiften
+      triggered_by:
+        manual: Manuellt
+        rollover: Utrullning
+      version: v%{version}
     dialogs:
       cancel: Avbryt
       confirm: Bekräfta
@@ -617,6 +713,7 @@ sv:
       nav:
         batches: Grupper
         dashboard: Instrumentpanel
+        deploy_tasks: Deploy
         dlq: DLQ
         events: Händelser
         insights: Insikter

data/config/routes.rb

@@ -45,6 +45,13 @@ Pgbus::Engine.routes.draw do
     end
   end
 
+  resources :deploy_tasks, only: %i[index show] do
+    member do
+      post :toggle
+      post :enqueue
+    end
+  end
+
   resources :batches, only: %i[index show]
   resources :processes, only: [:index]
 

data/lib/generators/pgbus/add_deploy_tasks_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "migration_path"
+
+module Pgbus
+  module Generators
+    class AddDeployTasksGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationPath
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add deploy tasks tables (one-time jobs run after a rollover) to an existing Pgbus installation"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration_file
+        migration_template "add_deploy_tasks_tables.rb.erb",
+                           File.join(pgbus_migrate_path, "add_pgbus_deploy_tasks_tables.rb")
+      end
+
+      def create_deploy_tasks_config
+        template "deploy_tasks.yml.erb", "config/deploy_tasks.yml"
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus deploy tasks installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
+        say "  2. Edit config/deploy_tasks.yml to declare your one-time tasks"
+        say "  3. Make sure every pgbus process knows the app revision (config.app_revision,"
+        say "     PGBUS_REVISION, DASH_VERSION, KAMAL_VERSION or a REVISION file)"
+        say "  4. Restart pgbus: bin/pgbus start"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+class AddPgbusDeployTasksTables < ActiveRecord::Migration<%= migration_version %>
+  # if_not_exists throughout: pgbus:update queues this migration when either
+  # table is missing, so a half-present schema must not fail it.
+  def change
+    create_table :pgbus_deploy_tasks, if_not_exists: true do |t|
+      t.string :key, null: false
+      t.string :class_name
+      t.string :command, limit: 2048
+      t.text :arguments
+      t.string :queue_name
+      t.integer :priority, default: 0
+      t.string :version, null: false, default: "1"
+      t.boolean :every_deploy, null: false, default: false
+      t.boolean :static, null: false, default: true
+      t.boolean :enabled, null: false, default: true
+      t.text :description
+      t.datetime :armed_at
+      t.string :armed_for
+      t.timestamps
+    end
+
+    add_index :pgbus_deploy_tasks, :key,
+      unique: true, name: "idx_pgbus_deploy_tasks_key", if_not_exists: true
+    add_index :pgbus_deploy_tasks, :armed_at,
+      where: "armed_at IS NOT NULL", name: "idx_pgbus_deploy_tasks_armed", if_not_exists: true
+
+    create_table :pgbus_deploy_task_runs, if_not_exists: true do |t|
+      t.string :task_key, null: false
+      t.string :version, null: false
+      t.string :revision
+      t.string :triggered_by, null: false
+      t.string :queue_name
+      t.bigint :msg_id
+      t.datetime :run_at, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :pgbus_deploy_task_runs, [:task_key, :run_at],
+      name: "idx_pgbus_deploy_task_runs_task", if_not_exists: true
+    add_index :pgbus_deploy_task_runs, :run_at,
+      name: "idx_pgbus_deploy_task_runs_cleanup", if_not_exists: true
+  end
+end

data/lib/generators/pgbus/templates/deploy_tasks.yml.erb

@@ -0,0 +1,42 @@
+# Pgbus Deploy Tasks Configuration
+#
+# One-time jobs that run once the whole fleet has rolled over to a new app
+# revision: a backfill, a data fix, a cache warm. Same shape as
+# config/recurring.yml, without schedule:. Supports environment-scoped or
+# flat configuration.
+#
+# The scheduler enqueues a task only when every live pgbus process reports
+# the scheduler's own app revision and at least one worker on it is alive,
+# so a task never runs on old code during the deploy overlap window. The
+# revision comes from config.app_revision, then PGBUS_REVISION, DASH_VERSION,
+# KAMAL_VERSION, then the REVISION file at Rails.root. Without one, deploy
+# tasks wait (the dashboard says so) and only "Run now" enqueues them.
+#
+# Format:
+#   task_key:
+#     class: JobClassName      # ActiveJob class to run (or use command:)
+#     version: 1               # Runs once per version; bump it to run again after the next deploy
+#     every_deploy: false      # true: run after every rollover instead (version is ignored)
+#     queue: default           # Optional: queue name (default: pgbus default queue)
+#     args: [arg1, arg2]       # Optional: job arguments
+#     priority: 0              # Optional: numeric priority
+#     description: "text"      # Optional: human-readable description
+#
+# Command-based tasks (no job class needed):
+#   warm_fragment_caches:
+#     command: "FragmentCacheWarmer.run"
+#     every_deploy: true
+#
+# Examples:
+#
+# production:
+#   backfill_order_totals:
+#     class: BackfillOrderTotalsJob
+#     version: 2
+#     queue: maintenance
+#     args: [{ batch_size: 500 }]
+#     description: Recompute totals after the currency migration
+#
+#   warm_fragment_caches:
+#     command: "FragmentCacheWarmer.run"
+#     every_deploy: true

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

@@ -170,6 +170,47 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     add_index :pgbus_recurring_executions, :run_at,
       name: "idx_pgbus_recurring_executions_cleanup"
 
+    # Deploy tasks (synced from config/deploy_tasks.yml): one-time jobs the
+    # scheduler enqueues once the fleet has rolled over to a new revision.
+    # armed_at/armed_for is the compare-and-set claim; runs are the history.
+    create_table :pgbus_deploy_tasks do |t|
+      t.string :key, null: false
+      t.string :class_name
+      t.string :command, limit: 2048
+      t.text :arguments
+      t.string :queue_name
+      t.integer :priority, default: 0
+      t.string :version, null: false, default: "1"
+      t.boolean :every_deploy, null: false, default: false
+      t.boolean :static, null: false, default: true
+      t.boolean :enabled, null: false, default: true
+      t.text :description
+      t.datetime :armed_at
+      t.string :armed_for
+      t.timestamps
+    end
+
+    add_index :pgbus_deploy_tasks, :key,
+      unique: true, name: "idx_pgbus_deploy_tasks_key"
+    add_index :pgbus_deploy_tasks, :armed_at,
+      where: "armed_at IS NOT NULL", name: "idx_pgbus_deploy_tasks_armed"
+
+    create_table :pgbus_deploy_task_runs do |t|
+      t.string :task_key, null: false
+      t.string :version, null: false
+      t.string :revision
+      t.string :triggered_by, null: false
+      t.string :queue_name
+      t.bigint :msg_id
+      t.datetime :run_at, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :pgbus_deploy_task_runs, [:task_key, :run_at],
+      name: "idx_pgbus_deploy_task_runs_task"
+    add_index :pgbus_deploy_task_runs, :run_at,
+      name: "idx_pgbus_deploy_task_runs_cleanup"
+
     # Stream queue registry — records which PGMQ queues back streams (vs jobs).
     # Stream and job queues share the pgbus_ namespace, so maintenance
     # (per-stream retention, orphan sweep) and wildcard workers rely on this
@@ -204,6 +245,8 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     execute "SELECT pgmq.drop_queue('pgbus_default')"
 
     drop_table :pgbus_stream_queues
+    drop_table :pgbus_deploy_task_runs
+    drop_table :pgbus_deploy_tasks
     drop_table :pgbus_recurring_executions
     drop_table :pgbus_recurring_tasks
     drop_table :pgbus_batch_executions

data/lib/pgbus/active_job/current_attributes.rb

@@ -28,7 +28,9 @@ module Pgbus
       included do
         attr_accessor :pgbus_current_attributes
 
-        class_attribute :pgbus_persist_current_attributes, instance_writer: false, default: nil
+        # A per-class setting the job's own class body writes at load; jobs
+        # only read it while they serialize.
+        class_attribute :pgbus_persist_current_attributes, instance_writer: false, default: nil # rubocop:disable ThreadSafety/ClassAndModuleAttributes
       end
 
       def serialize

data/lib/pgbus/batch.rb

@@ -209,22 +209,28 @@ module Pgbus
       0
     end
 
+    # Schema-probe memos (a true answer is kept for the life of the process)
+    # and the warn-once flag, read and written under @schema_lock (issue
+    # #527). The probes run outside it: a duplicate probe on a race is
+    # harmless, a lock held across a query is not.
+    @schema_lock = Mutex.new
+
     def self.executions_migrated?
-      return true if @executions_migrated
+      return true if @schema_lock.synchronize { @executions_migrated }
 
       result = begin
         BatchExecution.table_exists?
       rescue StandardError
         false
       end
-      @executions_migrated = true if result
+      @schema_lock.synchronize { @executions_migrated = true } if result
       result
     end
 
     def self.warn_callback_jobs_unmigrated
-      return if @warned_callback_jobs_unmigrated
+      first = @schema_lock.synchronize { @warned_callback_jobs_unmigrated ? false : (@warned_callback_jobs_unmigrated = true) }
+      return unless first
 
-      @warned_callback_jobs_unmigrated = true
       Pgbus.logger.warn do
         "[Pgbus] Batch callback configured as an ActiveJob instance, but pgbus_batches has no " \
           "on_*_job columns yet — .set options (queue, wait, priority) are ignored until " \
@@ -233,23 +239,25 @@ module Pgbus
     end
 
     def self.reset_executions_migrated_cache!
-      @executions_migrated = nil
-      @callback_jobs_migrated = nil
-      @warned_callback_jobs_unmigrated = nil
+      @schema_lock.synchronize do
+        @executions_migrated = nil
+        @callback_jobs_migrated = nil
+        @warned_callback_jobs_unmigrated = nil
+      end
     end
 
     # True once the on_finish_job / on_success_job / on_failure_job jsonb
     # columns exist (issue #415). Until then, configured callback instances
     # have nowhere to live and only bare classes are stored.
     def self.callback_jobs_migrated?
-      return true if @callback_jobs_migrated
+      return true if @schema_lock.synchronize { @callback_jobs_migrated }
 
       result = begin
         BatchEntry.column_names.include?("on_finish_job")
       rescue StandardError
         false
       end
-      @callback_jobs_migrated = true if result
+      @schema_lock.synchronize { @callback_jobs_migrated = true } if result
       result
     end
 

data/lib/pgbus/cli.rb

@@ -37,6 +37,9 @@ module Pgbus
 
     def start_supervisor(args = [])
       apply_start_options(args)
+      # The flags go through setters, after boot finalized the configuration:
+      # finalize their values too before the supervisor forks.
+      Pgbus.finalize!
       Pgbus.logger.info { "[Pgbus] Starting Pgbus #{Pgbus::VERSION}..." }
 
       supervisor = Process::Supervisor.new

data/lib/pgbus/client/read_after.rb

@@ -9,7 +9,16 @@ module Pgbus
     # The cursor is the highest msg_id the client has already seen. Replay returns
     # everything strictly greater, ordered by msg_id ASC, capped by `limit`.
     module ReadAfter
-      Envelope = Data.define(:msg_id, :enqueued_at, :payload, :source)
+      # Ractor-shareable like the streamer's other dispatch values (issue
+      # #527): the Strings are frozen in place, they are the read's own.
+      Envelope = Data.define(:msg_id, :enqueued_at, :payload, :source) do
+        def initialize(msg_id:, enqueued_at:, payload:, source:)
+          enqueued_at&.freeze
+          payload&.freeze
+          source&.freeze
+          super
+        end
+      end
 
       DEFAULT_LIMIT = 500