Make async DB pool guidance Rails-version aware

Author: crmne

README.md

@@ -282,6 +282,7 @@ Here's an overview of the different options:
 - `threads`: this is the execution capacity for a worker in `thread` mode. It is the max size of the thread pool. By default, this is `3`. Only workers have this setting.
 It is recommended to set this value less than or equal to the queue database's connection pool size minus 2, as each worker uses connections for polling and heartbeat and thread mode may use additional connections for job execution.
 - `capacity`: an alias for worker execution capacity. This is the clearer name when `execution_mode: async`, because it refers to in-flight execution capacity rather than operating system threads.
+  Async workers reject `threads`; use `capacity` or `fibers` instead. On Rails 7.2 and later, a practical starting point is usually `3-5` queue database connections per worker process rather than `capacity`, because ordinary Active Record query paths can release connections between async waits. On Rails 7.1, size the queue database pool more conservatively, as in-flight async jobs may still retain connections roughly in proportion to `capacity`.
 - `fibers`: an alias for `capacity` when `execution_mode: async`.
 - `processes`: this is the number of worker processes that will be forked by the supervisor with the settings given. By default, this is `1`, just a single process. This setting is useful if you want to dedicate more than one CPU core to a queue or queues with the same configuration. Only workers have this setting. This works with both `execution_mode: thread` and `execution_mode: async` as long as the supervisor is running in the default `fork` mode. **Note**: this option is ignored only when the supervisor itself is [running in `async` mode](#fork-vs-async-mode).
 - `concurrency_maintenance`: whether the dispatcher will perform the concurrency maintenance work. This is `true` by default, and it's useful if you don't use any [concurrency controls](#concurrency-controls) and want to disable it or if you run multiple dispatchers and want some of them to just dispatch jobs without doing anything else.
@@ -380,6 +381,10 @@ Async worker execution is best suited for cooperative, mostly I/O-bound jobs. Bl
 
 Because async workers run multiple fibers on a single thread, Rails must also isolate execution state per fiber rather than per thread. If your app keeps the default thread-scoped isolation level, Solid Queue will raise a boot-time error instead of running async workers with shared Active Record state.
 
+On Rails 7.2 and later, async workers can often use a much smaller queue database pool than an equivalent thread pool. A practical starting point is `3-5` queue database connections per worker process: one for job execution, one for polling, one for heartbeats, plus some headroom. In the default `fork` supervisor mode, that guidance applies per worker process. In supervisor `async` mode, all workers share one process, so add together the requirements for the workers running there.
+
+That lower-pool guidance depends on job code not holding connections open across async waits. APIs such as `ActiveRecord::Base.connection`, `lease_connection`, `connection_pool.checkout`, or long-lived `with_connection` / transaction blocks can pin connections and push async workers back toward thread-like pool usage. On Rails 7.1, plan conservatively and assume async capacity can still grow queue database connection usage.
+
 The supervisor is in charge of managing these processes, and it responds to the following signals when running in its own process via `bin/jobs` or with [the Puma plugin](#puma-plugin) with the default `fork` mode:
 - `TERM`, `INT`: starts graceful termination. The supervisor will send a `TERM` signal to its supervised processes, and it'll wait up to `SolidQueue.shutdown_timeout` time until they're done. If any supervised processes are still around by then, it'll send a `QUIT` signal to them to indicate they must exit.
 - `QUIT`: starts immediate termination. The supervisor will send a `QUIT` signal to its supervised processes, causing them to exit immediately.

lib/solid_queue/configuration.rb

@@ -6,7 +6,7 @@ class Configuration
 
     validate :ensure_configured_processes
     validate :ensure_valid_recurring_tasks
-    validate :ensure_correctly_sized_thread_pool
+    validate :ensure_correctly_sized_database_pool
     validate :ensure_valid_worker_execution_modes
     validate :ensure_async_workers_use_capacity_aliases
     validate :ensure_async_workers_have_required_dependency
@@ -40,6 +40,7 @@ def instantiate
 
     DEFAULT_CONFIG_FILE_PATH = "config/queue.yml"
     DEFAULT_RECURRING_SCHEDULE_FILE_PATH = "config/recurring.yml"
+    ASYNC_QUERY_SCOPED_CONNECTIONS_VERSION = Gem::Version.new("7.2.0")
 
     def initialize(**options)
       @options = options.with_defaults(default_options)
@@ -93,10 +94,11 @@ def ensure_valid_recurring_tasks
         end
       end
 
-      def ensure_correctly_sized_thread_pool
-        if (db_pool_size = SolidQueue::Record.connection_pool&.size) && db_pool_size < estimated_number_of_threads
-          errors.add(:base, "Solid Queue is configured to use #{estimated_number_of_threads} threads but the " +
-            "database connection pool is #{db_pool_size}. Increase it in `config/database.yml`")
+      def ensure_correctly_sized_database_pool
+        if (db_pool_size = SolidQueue::Record.connection_pool&.size) && db_pool_size < estimated_database_pool_size
+          errors.add(:base, "Solid Queue requires at least #{estimated_database_pool_size} database connections " +
+            "for the configured workers, but the queue database connection pool is #{db_pool_size}. " +
+            "Increase it in `config/database.yml`")
         end
       end
 
@@ -264,11 +266,13 @@ def load_config_from_file(file)
         end
       end
 
-      def estimated_number_of_threads
-        # At most one execution thread for async workers, or "threads" for thread workers,
-        # plus 1 thread for the worker loop and 1 thread for the heartbeat task.
-        thread_count = workers_options.map { |options| execution_threads_for_pool(options) }.max
-        (thread_count || 1) + 2
+      def estimated_database_pool_size
+        worker_pool_size = workers_options.map { |options| estimated_database_pool_size_for_worker(options) }.max
+        worker_pool_size || 1
+      end
+
+      def estimated_database_pool_size_for_worker(options)
+        estimated_execution_connections_for_worker(options) + 2
       end
 
       def normalize_worker_options(options)
@@ -289,8 +293,16 @@ def normalized_worker_execution_mode(options)
         options[:execution_mode] || WORKER_DEFAULTS[:execution_mode]
       end
 
-      def execution_threads_for_pool(options)
-        async_worker?(options) ? 1 : worker_capacity(options)
+      def estimated_execution_connections_for_worker(options)
+        async_worker?(options) ? async_execution_connections_for_worker(options) : worker_capacity(options)
+      end
+
+      def async_execution_connections_for_worker(options)
+        async_jobs_release_connections_between_queries? ? 1 : worker_capacity(options)
+      end
+
+      def async_jobs_release_connections_between_queries?
+        ActiveRecord.gem_version >= ASYNC_QUERY_SCOPED_CONNECTIONS_VERSION
       end
 
       def async_worker?(options)

test/unit/configuration_test.rb

@@ -90,7 +90,24 @@ class ConfigurationTest < ActiveSupport::TestCase
     end
   end
 
-  test "async worker capacity does not inflate required database pool size" do
+  test "async worker capacity inflates required database pool size on Rails 7.1" do
+    skip if async_workers_release_connections_between_queries?
+
+    with_execution_isolation(:fiber) do
+      configuration = SolidQueue::Configuration.new(
+        workers: [ { queues: "llm*", execution_mode: :async, capacity: 1000 } ],
+        dispatchers: [],
+        skip_recurring: true
+      )
+
+      assert_not configuration.valid?
+      assert_match /requires at least 1002 database connections/, configuration.errors.full_messages.first
+    end
+  end
+
+  test "async worker capacity does not inflate required database pool size on Rails 7.2+" do
+    skip unless async_workers_release_connections_between_queries?
+
     with_execution_isolation(:fiber) do
       configuration = SolidQueue::Configuration.new(
         workers: [ { queues: "llm*", execution_mode: :async, capacity: 1000 } ],
@@ -227,11 +244,15 @@ class ConfigurationTest < ActiveSupport::TestCase
     # Not enough DB connections
     configuration = SolidQueue::Configuration.new(workers: [ { queues: "background", threads: 50, polling_interval: 10 } ])
     assert_not configuration.valid?
-    assert_match /Solid Queue is configured to use \d+ threads but the database connection pool is \d+. Increase it in `config\/database.yml`/,
+    assert_match /Solid Queue requires at least \d+ database connections for the configured workers, but the queue database connection pool is \d+. Increase it in `config\/database.yml`/,
       configuration.errors.full_messages.first
   end
 
   private
+    def async_workers_release_connections_between_queries?
+      ActiveRecord.gem_version >= SolidQueue::Configuration::ASYNC_QUERY_SCOPED_CONNECTIONS_VERSION
+    end
+
     def assert_processes(configuration, kind, count, **attributes)
       processes = configuration.configured_processes.select { |p| p.kind == kind }
       assert_equal count, processes.size