solid_queue 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d40f055103084c9aaa9efe6ded0e675ff967a88200bf9f5579b1287e29d48818
-  data.tar.gz: af6ab85d5c674dbceff32768b5aa7b4d87bc1aeea24476e3fb469d639c4fad46
+  metadata.gz: 82eb2e9041fa69b3e7f3bd4a3d62c46b7826100a708b2237750f0f9e4fdee9c5
+  data.tar.gz: 14000eeba6030e0248273d4cc158e17f25f78268d5e2c62c5e74f9a959f8d94f
 SHA512:
-  metadata.gz: 926a7f82ebca8389d5d6d6116bd6539d65715704e739f66083f1e21411737da72972f4b643bd4291e95ef5bb107417cb11fde6c535d6e4013434ac589cc2fc6e
-  data.tar.gz: 684e5f32bbe7aa4ce0645687a92c2538016431151208156ec144b574e1d48e8d04144f28a2eacca86ff5bd4449a2c6bdd439bdcd74bdf72788ae4430abd284c2
+  metadata.gz: 9bb7b225b9a3b1b13e1f2edfa04927cb2f3954d0a0b226ca79e7fc69dff6675c002ac5e6dd13fd0ff9794d2f0a660487a70cb078868034e7a048378b14911a4f
+  data.tar.gz: b30ef8f4992fc7a3d858294b3ae9b1c4459f813d9ec3bb3ff4a4fde97ad114469d76d913bb19912117de3d081e6c8d159798e5bcdd0790858ea3af6f4faf7cc6

data/README.md

@@ -214,6 +214,8 @@ bin/jobs -c config/calendar.yml
 
 You can also skip the scheduler process by setting the environment variable `SOLID_QUEUE_SKIP_RECURRING=true`. This is useful for environments like staging, review apps, or development where you don't want any recurring jobs to run. This is equivalent to using the `--skip-recurring` option with `bin/jobs`.
 
+To run **only** the scheduler (no workers or dispatchers)—for example to isolate recurring tasks on a dedicated process—set `SOLID_QUEUE_ONLY_RECURRING=true` or use the `--only-recurring` option with `bin/jobs`.
+
 This is what this configuration looks like:
 
 ```yml
@@ -404,6 +406,7 @@ There are several settings that control how Solid Queue works that you can set a
 - `use_skip_locked`: whether to use `FOR UPDATE SKIP LOCKED` when performing locking reads. This will be automatically detected in the future, and for now, you only need to set this to `false` if your database doesn't support it. For MySQL, that'd be versions < 8; for MariaDB, versions < 10.6; and for PostgreSQL, versions < 9.5. If you use SQLite, this has no effect, as writes are sequential.
 - `process_heartbeat_interval`: the heartbeat interval that all processes will follow—defaults to 60 seconds.
 - `process_alive_threshold`: how long to wait until a process is considered dead after its last heartbeat—defaults to 5 minutes.
+- `fork_boot_timeout`: how long a forked process can take to finish booting before the supervisor replaces it—defaults to 5 minutes. It only applies in the default `fork` mode.
 - `shutdown_timeout`: time the supervisor will wait since it sent the `TERM` signal to its supervised processes before sending a `QUIT` version to them requesting immediate termination—defaults to 5 seconds.
 - `silence_polling`: whether to silence Active Record logs emitted when polling for both workers and dispatchers—defaults to `true`.
 - `supervisor_pidfile`: path to a pidfile that the supervisor will create when booting to prevent running more than one supervisor in the same host, or in case you want to use it for a health check. It's `nil` by default.
@@ -709,6 +712,8 @@ bin/jobs --recurring_schedule_file=config/schedule.yml
 
 You can completely disable recurring tasks by setting the environment variable `SOLID_QUEUE_SKIP_RECURRING=true` or by using the `--skip-recurring` option with `bin/jobs`.
 
+To run only the scheduler (no workers or dispatchers), set `SOLID_QUEUE_ONLY_RECURRING=true` or use `--only-recurring` with `bin/jobs`.
+
 The configuration itself looks like this:
 
 ```yml

data/app/models/solid_queue/record/distinct_values.rb

@@ -19,23 +19,25 @@ module SolidQueue
 
         private
           def loose_index_scan_emulation_needed?
-            connection.adapter_name == "PostgreSQL"
+            connection_pool.with_connection { |connection| connection.adapter_name == "PostgreSQL" }
           end
 
           # Emulates a loose index scan, honoring the current scope (e.g. LIKE prefixes)
           # by building the anchor and the recursive step as scoped relations, whose
           # #to_sql inlines any bind parameters so they can be embedded in the raw CTE.
           def loose_distinct_via_recursive_cte(column)
-            col = connection.quote_column_name(column)
+            connection_pool.with_connection do |connection|
+              col = connection.quote_column_name(column)
 
-            connection.select_values(<<~SQL.squish)
-              WITH RECURSIVE t AS (
-                (#{next_distinct_value(col, "#{col} IS NOT NULL")})
-                UNION ALL
-                SELECT (#{next_distinct_value(col, "#{col} > t.#{col}")}) FROM t WHERE t.#{col} IS NOT NULL
-              )
-              SELECT #{col} FROM t WHERE #{col} IS NOT NULL
-            SQL
+              connection.select_values(<<~SQL.squish)
+                WITH RECURSIVE t AS (
+                  (#{next_distinct_value(col, "#{col} IS NOT NULL")})
+                  UNION ALL
+                  SELECT (#{next_distinct_value(col, "#{col} > t.#{col}")}) FROM t WHERE t.#{col} IS NOT NULL
+                )
+                SELECT #{col} FROM t WHERE #{col} IS NOT NULL
+              SQL
+            end
           end
 
           # Smallest value of `col` within the current scope that matches `condition`.

data/app/models/solid_queue/record.rb

@@ -24,6 +24,16 @@ module SolidQueue
         end
       end
 
+      def warn_about_pending_migrations
+        SolidQueue.deprecator.warn(<<~DEPRECATION)
+          Solid Queue has pending database migrations. To get the new migration files, run:
+            rails solid_queue:update
+          And then:
+            rails db:migrate
+          These migrations will be required after version #{SolidQueue.next_major_version}.0
+        DEPRECATION
+      end
+
       # Pass index hints to the query optimizer using SQL comment hints.
       # Uses MySQL 8 optimizer hint query comments, which SQLite and
       # PostgreSQL ignore.

data/lib/generators/solid_queue/update/update_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+class SolidQueue::UpdateGenerator < Rails::Generators::Base
+  include ActiveRecord::Generators::Migration
+
+  source_root File.expand_path("templates", __dir__)
+
+  class_option :database, type: :string, aliases: %i[ --db ], default: "queue",
+    desc: "The database that Solid Queue uses. Defaults to `queue`"
+
+  def copy_new_migrations
+    Dir.glob(File.join(self.class.source_root, "db", "*.rb")).each do |migration_file|
+      name = File.basename(migration_file)
+      migration_template File.join("db", name), File.join(db_migrate_path, name), skip: true
+    end
+  end
+end

data/lib/solid_queue/cli.rb

@@ -20,6 +20,10 @@ module SolidQueue
       desc: "Whether to skip recurring tasks scheduling",
       banner: "SOLID_QUEUE_SKIP_RECURRING"
 
+    class_option :only_recurring, type: :boolean,
+      desc: "Whether to run only the scheduler process for recurring tasks",
+      banner: "SOLID_QUEUE_ONLY_RECURRING"
+
     def self.exit_on_failure?
       true
     end

data/lib/solid_queue/configuration.rb

@@ -43,7 +43,10 @@ module SolidQueue
     end
 
     def configured_processes
-      if only_work? then workers
+      if only_work?
+        workers
+      elsif only_recurring?
+        schedulers
       else
         dispatchers + workers + schedulers
       end
@@ -126,6 +129,7 @@ module SolidQueue
           recurring_schedule_file: Rails.root.join(ENV["SOLID_QUEUE_RECURRING_SCHEDULE"] || DEFAULT_RECURRING_SCHEDULE_FILE_PATH),
           only_work: false,
           only_dispatch: false,
+          only_recurring: ActiveModel::Type::Boolean.new.cast(ENV["SOLID_QUEUE_ONLY_RECURRING"]),
           skip_recurring: ActiveModel::Type::Boolean.new.cast(ENV["SOLID_QUEUE_SKIP_RECURRING"])
         }
       end
@@ -142,6 +146,10 @@ module SolidQueue
         options[:only_dispatch]
       end
 
+      def only_recurring?
+        options[:only_recurring]
+      end
+
       def skip_recurring_tasks?
         options[:skip_recurring] || only_work?
       end

data/lib/solid_queue/engine.rb

@@ -43,5 +43,9 @@ module SolidQueue
         include ActiveJob::ConcurrencyControls
       end
     end
+
+    initializer "solid_queue.deprecator" do |app|
+      app.deprecators[:solid_queue] = SolidQueue.deprecator
+    end
   end
 end

data/lib/solid_queue/fork_supervisor.rb

@@ -31,6 +31,21 @@ module SolidQueue
 
         replace_fork(pid, status)
       end
+
+      check_boot_timeouts
+    end
+
+    def check_boot_timeouts
+      process_instances.each do |pid, instance|
+        terminate_unready_process(pid) if instance.boot_timed_out?
+      end
+    end
+
+    def terminate_unready_process(pid)
+      SolidQueue.instrument(:fork_boot_timeout, process: process_instances[pid], pid: pid) do
+        # A child stuck in boot cannot reach its run loop to stop gracefully
+        signal_process(pid, :KILL)
+      end
     end
 
     def reap_terminated_forks
@@ -38,9 +53,13 @@ module SolidQueue
         pid, status = ::Process.waitpid2(-1, ::Process::WNOHANG)
         break unless pid
 
-        if (terminated_fork = process_instances.delete(pid)) && (!status.exited? || status.exitstatus.to_i > 0)
-          error = Processes::ProcessExitError.new(status)
-          release_claimed_jobs_by(terminated_fork, with_error: error)
+        if terminated_fork = process_instances.delete(pid)
+          terminated_fork.mark_as_reaped
+
+          if !status.exited? || status.exitstatus.to_i > 0
+            error = Processes::ProcessExitError.new(status)
+            release_claimed_jobs_by(terminated_fork, with_error: error)
+          end
         end
 
         configured_processes.delete(pid)
@@ -52,6 +71,7 @@ module SolidQueue
     def replace_fork(pid, status)
       SolidQueue.instrument(:replace_fork, supervisor_pid: ::Process.pid, pid: pid, status: status) do |payload|
         if terminated_fork = process_instances.delete(pid)
+          terminated_fork.mark_as_reaped
           payload[:fork] = terminated_fork
           error = Processes::ProcessExitError.new(status)
           release_claimed_jobs_by(terminated_fork, with_error: error)

data/lib/solid_queue/log_subscriber.rb

@@ -161,6 +161,11 @@ class SolidQueue::LogSubscriber < ActiveSupport::LogSubscriber
     end
   end
 
+  def fork_boot_timeout(event)
+    process = event.payload[:process]
+    warn formatted_event(event, action: "Terminate #{process.kind} that failed to boot in time", **event.payload.slice(:pid).merge(hostname: process.hostname, name: process.name))
+  end
+
   private
     def formatted_event(event, action:, **attributes)
       "SolidQueue-#{SolidQueue::VERSION} #{action} (#{event.duration.round(1)}ms)  #{formatted_attributes(**attributes)}"

data/lib/solid_queue/processes/runnable.rb

@@ -31,6 +31,14 @@ module SolidQueue::Processes
       !running_async? || @thread&.alive?
     end
 
+    def boot_timed_out?
+      @boot_guard.timed_out?
+    end
+
+    def mark_as_reaped
+      @boot_guard.close
+    end
+
     private
       DEFAULT_MODE = :async
 
@@ -41,11 +49,14 @@ module SolidQueue::Processes
       def run_in_mode(&block)
         case
         when running_as_fork?
-          fork(&block)
+          @boot_guard = BootGuards::ForkGuard.new
+          fork(&block).tap { @boot_guard.start }
         when running_async?
+          @boot_guard = BootGuards::NullGuard.new
           @thread = create_thread(&block)
           @thread.object_id
         else
+          @boot_guard = BootGuards::NullGuard.new
           block.call
         end
       end
@@ -59,6 +70,8 @@ module SolidQueue::Processes
             end
           end
         end
+
+        @boot_guard.complete
       end
 
       def shutting_down?
@@ -95,4 +108,76 @@ module SolidQueue::Processes
         mode.fork?
       end
   end
+
+  module BootGuards
+    # Tracks a process that shares memory with its supervisor, whose boot time
+    # doesn't need monitoring.
+    class NullGuard
+      def complete
+        @completed = true
+      end
+
+      def start
+      end
+
+      def completed?
+        @completed
+      end
+
+      def timed_out?
+        false
+      end
+
+      def close
+      end
+    end
+
+    # Tracks a forked process from the moment it's started until its boot
+    # callbacks finish, over a pipe that survives forking: the forked process
+    # writes to it when it's done booting, and its supervisor reads from it to
+    # decide whether the process is taking too long to boot and needs replacing.
+    class ForkGuard
+      def initialize
+        @reader, @writer = IO.pipe
+        @created_at = SolidQueue::Timer.monotonic_time_now
+      end
+
+      # Runs in the forked process when it has finished booting
+      def complete
+        reader.close
+        writer.write(".")
+      rescue Errno::EPIPE
+        # The supervisor stopped waiting while this process finished booting
+      ensure
+        writer.close
+      end
+
+      # Runs in the parent process right after forking
+      def start
+        writer.close
+      end
+
+      # A byte means boot completed; EOF means the process exited before
+      # finishing its boot, and will be replaced when it's reaped
+      def completed?
+        @completed ||= begin
+          completed = reader.read_nonblock(1, exception: false) != :wait_readable
+          reader.close if completed
+          completed
+        end
+      end
+
+      def timed_out?
+        !completed? && SolidQueue::Timer.monotonic_time_now - created_at >= SolidQueue.fork_boot_timeout
+      end
+
+      def close
+        reader.close unless reader.closed?
+        writer.close unless writer.closed?
+      end
+
+      private
+        attr_reader :reader, :writer, :created_at
+    end
+  end
 end

data/lib/solid_queue/tasks.rb

@@ -4,6 +4,11 @@ namespace :solid_queue do
     Rails::Command.invoke :generate, [ "solid_queue:install" ]
   end
 
+  desc "Copy any new Solid Queue migrations to the application"
+  task :update do
+    Rails::Command.invoke :generate, [ "solid_queue:update" ]
+  end
+
   desc "start solid_queue supervisor to dispatch and process jobs"
   task start: :environment do
     SolidQueue::Supervisor.start

data/lib/solid_queue/timer.rb

@@ -20,9 +20,8 @@ module SolidQueue
       end
     end
 
-    private
-      def monotonic_time_now
-        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-      end
+    def monotonic_time_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
   end
 end

data/lib/solid_queue/version.rb

@@ -1,3 +1,7 @@
 module SolidQueue
-  VERSION = "1.5.0"
+  VERSION = "1.5.1"
+
+  def self.next_major_version
+    Gem::Version.new(VERSION).segments.first + 1
+  end
 end

data/lib/solid_queue.rb

@@ -29,6 +29,7 @@ module SolidQueue
 
   mattr_accessor :process_heartbeat_interval, default: 60.seconds
   mattr_accessor :process_alive_threshold, default: 5.minutes
+  mattr_accessor :fork_boot_timeout, default: 5.minutes
 
   mattr_accessor :shutdown_timeout, default: 5.seconds
 
@@ -86,6 +87,10 @@ module SolidQueue
     preserve_finished_jobs
   end
 
+  def deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new(next_major_version, "SolidQueue")
+  end
+
   def instrument(channel, **options, &block)
     ActiveSupport::Notifications.instrument("#{channel}.solid_queue", **options, &block)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Rosa Gutierrez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -309,6 +309,7 @@ files:
 - lib/generators/solid_queue/install/templates/config/queue.yml
 - lib/generators/solid_queue/install/templates/config/recurring.yml
 - lib/generators/solid_queue/install/templates/db/queue_schema.rb
+- lib/generators/solid_queue/update/update_generator.rb
 - lib/puma/plugin/solid_queue.rb
 - lib/solid_queue.rb
 - lib/solid_queue/app_executor.rb