good_job 1.9.6 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db147d840e981330790b1b3254d9aa40d0c9e6e9284612336e3815928c0efa38
-  data.tar.gz: 22d1b91b0edc67538ded7b8efd9dbdf36e4d1a06717c8e96ed09adb50188310a
+  metadata.gz: 96c16ec6a03de5eaf957327ad3f9161d19665eeef2e8bc300caa758a84cfe58f
+  data.tar.gz: 22be95e4ae3d2dc29a8b242cb37889d21d2b19f119184a5a33d07f04e9a3b453
 SHA512:
-  metadata.gz: 352ddf2bbe0dbe7c79a650a32f37c070855d3330ecb444a79b33afbb253108bac567794959cd2a2111f10c7c2623f08a341f17211ee70c13841c783f0611ed04
-  data.tar.gz: 5ecbac7d33b5a6db0d8ad2f5964dadd9bc6f394eab3d6935584c5b4ab3633dadc1ed2249e99de8e532f8cd1c4cd4268a76cf7104c21f3b00bc924e8fd12ee64b
+  metadata.gz: a59d51fdaf7e08a551e6401bdc6fb59d56e8397bc15b7f6ead69ce5eb45da653c149ebad6583af739cdcb619c2d827fb19f50becf4e4b3780ef4d31dc9be4a50
+  data.tar.gz: a9c3c96e76c19270b436d03fcff64e2e873cb6f14b784cbe8b2dd20e2deee455ce2ae6e1869a67b812f414880a7e264a50afd2951d80b41f4ddb9acdab8a0764

data/CHANGELOG.md

@@ -1,23 +1,53 @@
 # Changelog
 
-## [v1.9.6](https://github.com/bensheldon/good_job/tree/v1.9.6) (2021-06-04)
+## [v1.10.0](https://github.com/bensheldon/good_job/tree/v1.10.0) (2021-06-29)
 
-[Full Changelog](https://github.com/bensheldon/good_job/compare/v1.9.5...v1.9.6)
+[Full Changelog](https://github.com/bensheldon/good_job/compare/v1.9.6...v1.10.0)
+
+**Implemented enhancements:**
+
+- Add `rails g good_job:update` command to add idempotent migration files, including `active_job_id`, `concurrency_key`, `cron_key` columns [\#266](https://github.com/bensheldon/good_job/pull/266) ([bensheldon](https://github.com/bensheldon))
+
+**Fixed bugs:**
+
+- Use `pg_advisory_unlock_all` after each thread's job execution; fix Lockable return values; improve test stability [\#285](https://github.com/bensheldon/good_job/pull/285) ([bensheldon](https://github.com/bensheldon))
+- Dashboard AssetsController does not raise if verify\_authenticity\_token is not in the callback chain [\#284](https://github.com/bensheldon/good_job/pull/284) ([bensheldon](https://github.com/bensheldon))
 
 **Closed issues:**
 
-- Pause jobs during migration / maintenance? [\#257](https://github.com/bensheldon/good_job/issues/257)
-- How to properly report errors to error tracker service [\#159](https://github.com/bensheldon/good_job/issues/159)
+- \[Question\] Dashboard assets not showing [\#282](https://github.com/bensheldon/good_job/issues/282)
 
 **Merged pull requests:**
 
+- Separately cache Appraisal gems in GH Action [\#280](https://github.com/bensheldon/good_job/pull/280) ([bensheldon](https://github.com/bensheldon))
+- Use custom RSpec doc formatter to show spec examples that are running [\#279](https://github.com/bensheldon/good_job/pull/279) ([bensheldon](https://github.com/bensheldon))
+- Update development dependencies [\#278](https://github.com/bensheldon/good_job/pull/278) ([bensheldon](https://github.com/bensheldon))
+- Fix Scheduler integration spec to ensure jobs are run in the Scheduler under test [\#276](https://github.com/bensheldon/good_job/pull/276) ([bensheldon](https://github.com/bensheldon))
+- Add example benchmark for job throughput [\#275](https://github.com/bensheldon/good_job/pull/275) ([bensheldon](https://github.com/bensheldon))
+- Allow Lockable to be passed custom column, key, and Postgres advisory lock/unlock function [\#273](https://github.com/bensheldon/good_job/pull/273) ([bensheldon](https://github.com/bensheldon))
+
+## [v1.9.6](https://github.com/bensheldon/good_job/tree/v1.9.6) (2021-06-04)
+
+[Full Changelog](https://github.com/bensheldon/good_job/compare/v1.9.5...v1.9.6)
+
+**Implemented enhancements:**
+
 - Add deleting jobs from UI. [\#265](https://github.com/bensheldon/good_job/pull/265) ([morgoth](https://github.com/morgoth))
 - Collapse Dashboard params by default [\#263](https://github.com/bensheldon/good_job/pull/263) ([morgoth](https://github.com/morgoth))
 
+**Closed issues:**
+
+- Pause jobs during migration / maintenance? [\#257](https://github.com/bensheldon/good_job/issues/257)
+- How to properly report errors to error tracker service [\#159](https://github.com/bensheldon/good_job/issues/159)
+
 ## [v1.9.5](https://github.com/bensheldon/good_job/tree/v1.9.5) (2021-05-24)
 
 [Full Changelog](https://github.com/bensheldon/good_job/compare/v1.9.4...v1.9.5)
 
+**Implemented enhancements:**
+
+- Update Dashboard to Bootstrap 5 [\#260](https://github.com/bensheldon/good_job/pull/260) ([morgoth](https://github.com/morgoth))
+
 **Closed issues:**
 
 - Update from bootstrap 4 to bootstrap 5 [\#258](https://github.com/bensheldon/good_job/issues/258)
@@ -26,7 +56,6 @@
 
 - Serve Dashboard assets as discrete paths instead of inlining [\#262](https://github.com/bensheldon/good_job/pull/262) ([bensheldon](https://github.com/bensheldon))
 - Fix Gemfile.lock's missing JRuby dependencies; fix release script and add check [\#261](https://github.com/bensheldon/good_job/pull/261) ([bensheldon](https://github.com/bensheldon))
-- Update Dashboard to Bootstrap 5 [\#260](https://github.com/bensheldon/good_job/pull/260) ([morgoth](https://github.com/morgoth))
 
 ## [v1.9.4](https://github.com/bensheldon/good_job/tree/v1.9.4) (2021-05-18)
 

data/README.md

@@ -38,6 +38,7 @@ For more of the story of GoodJob, read the [introductory blog post](https://isla
     - [Configuration options](#configuration-options)
     - [Global options](#global-options)
     - [Dashboard](#dashboard)
+    - [Updating](#updating)
 - [Go deeper](#go-deeper)
     - [Exceptions, retries, and reliability](#exceptions-retries-and-reliability)
         - [Exceptions](#exceptions)
@@ -318,6 +319,22 @@ GoodJob includes a Dashboard as a mountable `Rails::Engine`.
     end
     ```
 
+### Updating
+
+GoodJob follows semantic versioning, though updates may be encouraged through deprecation warnings in minor versions.
+
+To apply updates:
+
+```bash
+bin/rails g good_job:update
+```
+
+...and run the resulting migration:
+
+```bash
+bin/rails db:migrate
+```
+
 ## Go deeper
 
 ### Exceptions, retries, and reliability

data/engine/app/controllers/good_job/assets_controller.rb

@@ -1,6 +1,6 @@
 module GoodJob
   class AssetsController < ActionController::Base # rubocop:disable Rails/ApplicationController
-    skip_before_action :verify_authenticity_token
+    skip_before_action :verify_authenticity_token, raise: false
 
     before_action do
       expires_in 1.year, public: true

data/lib/generators/good_job/install_generator.rb

@@ -1,13 +1,9 @@
 require 'rails/generators'
 require 'rails/generators/active_record'
-
 module GoodJob
   #
-  # Implements the Rails generator used for setting up GoodJob in a Rails
-  # application. Run it with +bin/rails g good_job:install+ in your console.
-  #
-  # This generator is primarily dedicated to stubbing out a migration that adds
-  # a table to hold GoodJob's queued jobs in your database.
+  # Rails generator used for setting up GoodJob in a Rails application.
+  # Run it with +bin/rails g good_job:install+ in your console.
   #
   class InstallGenerator < Rails::Generators::Base
     include Rails::Generators::Migration
@@ -16,17 +12,11 @@ module GoodJob
       delegate :next_migration_number, to: ActiveRecord::Generators::Base
     end
 
-    source_paths << File.join(File.dirname(__FILE__), "templates")
+    source_paths << File.join(File.dirname(__FILE__), "templates/install")
 
-    # Generates the actual migration file and places it on disk.
+    # Generates monolithic migration file that contains all database changes.
     def create_migration_file
-      migration_template 'migration.rb.erb', 'db/migrate/create_good_jobs.rb', migration_version: migration_version
-    end
-
-    private
-
-    def migration_version
-      "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      migration_template 'migrations/create_good_jobs.rb.erb', 'db/migrate/create_good_jobs.rb'
     end
   end
 end

data/lib/generators/good_job/templates/install/migrations/create_good_jobs.rb.erb

@@ -0,0 +1,27 @@
+class CreateGoodJobs < ActiveRecord::Migration[5.2]
+  def change
+    enable_extension 'pgcrypto'
+
+    create_table :good_jobs, id: :uuid do |t|
+      t.text :queue_name
+      t.integer :priority
+      t.jsonb :serialized_params
+      t.timestamp :scheduled_at
+      t.timestamp :performed_at
+      t.timestamp :finished_at
+      t.text :error
+
+      t.timestamps
+
+      t.uuid :active_job_id
+      t.text :concurrency_key
+      t.text :cron_key
+    end
+
+    add_index :good_jobs, :scheduled_at, where: "(finished_at IS NULL)", name: "index_good_jobs_on_scheduled_at"
+    add_index :good_jobs, [:queue_name, :scheduled_at], where: "(finished_at IS NULL)", name: :index_good_jobs_on_queue_name_and_scheduled_at
+    add_index :good_jobs, [:active_job_id, :created_at], name: :index_good_jobs_on_active_job_id_and_created_at
+    add_index :good_jobs, :concurrency_key, where: "(finished_at IS NULL)", name: :index_good_jobs_on_concurrency_key_when_unfinished
+    add_index :good_jobs, [:cron_key, :created_at], name: :index_good_jobs_on_cron_key_and_created_at
+  end
+end

data/lib/generators/good_job/templates/{migration.rb.erb → update/migrations/01_create_good_jobs.rb}

@@ -1,4 +1,4 @@
-class CreateGoodJobs < ActiveRecord::Migration<%= migration_version %>
+class CreateGoodJobs < ActiveRecord::Migration[5.2]
   def change
     enable_extension 'pgcrypto'
 
@@ -14,7 +14,7 @@ class CreateGoodJobs < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
-    add_index :good_jobs, :scheduled_at, where: "(finished_at IS NULL)"
-    add_index :good_jobs, [:queue_name, :scheduled_at], where: "(finished_at IS NULL)"
+    add_index :good_jobs, :scheduled_at, where: "(finished_at IS NULL)", name: "index_good_jobs_on_scheduled_at"
+    add_index :good_jobs, [:queue_name, :scheduled_at], where: "(finished_at IS NULL)", name: :index_good_jobs_on_queue_name_and_scheduled_at
   end
 end

data/lib/generators/good_job/templates/update/migrations/02_add_active_job_id_concurrency_key_cron_key_to_good_jobs.rb

@@ -0,0 +1,15 @@
+class AddActiveJobIdConcurrencyKeyCronKeyToGoodJobs < ActiveRecord::Migration[5.2]
+  def change
+    reversible do |dir|
+      dir.up do
+        # Ensure this incremental update migration is idempotent
+        # with monolithic install migration.
+        return if connection.column_exists?(:good_jobs, :active_job_id)
+      end
+    end
+
+    add_column :good_jobs, :active_job_id, :uuid
+    add_column :good_jobs, :concurrency_key, :text
+    add_column :good_jobs, :cron_key, :text
+  end
+end

data/lib/generators/good_job/templates/update/migrations/03_add_active_job_id_index_and_concurrency_key_index_to_good_jobs.rb

@@ -0,0 +1,32 @@
+class AddActiveJobIdIndexAndConcurrencyKeyIndexToGoodJobs < ActiveRecord::Migration[5.2]
+  disable_ddl_transaction!
+
+  UPDATE_BATCH_SIZE = 1_000
+
+  class GoodJobJobs < ActiveRecord::Base
+    self.table_name = "good_jobs"
+  end
+
+  def change
+    reversible do |dir|
+      dir.up do
+        # Ensure this incremental update migration is idempotent
+        # with monolithic install migration.
+        return if connection.index_name_exists?(:good_jobs, :index_good_jobs_on_active_job_id_and_created_at)
+      end
+    end
+
+    add_index :good_jobs, [:active_job_id, :created_at], algorithm: :concurrently, name: :index_good_jobs_on_active_job_id_and_created_at
+    add_index :good_jobs, :concurrency_key, where: "(finished_at IS NULL)", algorithm: :concurrently, name: :index_good_jobs_on_concurrency_key_when_unfinished
+    add_index :good_jobs, [:cron_key, :created_at], algorithm: :concurrently, name: :index_good_jobs_on_cron_key_and_created_at
+
+    reversible do |dir|
+      dir.up do
+        start_time = Time.current
+        loop do
+          break if GoodJobJobs.where(active_job_id: nil, finished_at: nil).where("created_at < ?", start_time).limit(UPDATE_BATCH_SIZE).update_all("active_job_id = (serialized_params->>'job_id')::uuid").zero?
+        end
+      end
+    end
+  end
+end

data/lib/generators/good_job/update_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module GoodJob
+  #
+  # Rails generator used for updating GoodJob in a Rails application.
+  # Run it with +bin/rails g good_job:update+ in your console.
+  #
+  class UpdateGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    class << self
+      delegate :next_migration_number, to: ActiveRecord::Generators::Base
+    end
+
+    TEMPLATES = File.join(File.dirname(__FILE__), "templates/update")
+    source_paths << TEMPLATES
+
+    # Generates incremental migration files unless they already exist.
+    # All migrations should be idempotent e.g. +add_index+ is guarded with +if_index_exists?+
+    def update_migration_files
+      migration_templates = Dir.children(File.join(TEMPLATES, 'migrations')).sort
+      migration_templates.each do |template_file|
+        destination_file = template_file.match(/^\d*_(.*\.rb)/)[1] # 01_create_good_jobs.rb.erb => create_good_jobs.rb
+        migration_template "migrations/#{template_file}", "db/migrate/#{destination_file}", skip: true
+      end
+    end
+  end
+end

data/lib/good_job/job.rb

@@ -156,10 +156,10 @@ module GoodJob
     #   raised, if any (if the job raised, then the second array entry will be
     #   +nil+). If there were no jobs to execute, returns +nil+.
     def self.perform_with_advisory_lock
-      unfinished.priority_ordered.only_scheduled.limit(1).with_advisory_lock do |good_jobs|
+      unfinished.priority_ordered.only_scheduled.limit(1).with_advisory_lock(unlock_session: true) do |good_jobs|
         good_job = good_jobs.first
-        # TODO: Determine why some records are fetched without an advisory lock at all
-        break unless good_job&.executable?
+        break if good_job.blank?
+        break :unlocked unless good_job&.executable?
 
         good_job.perform
       end
@@ -196,13 +196,30 @@ module GoodJob
     #   The new {Job} instance representing the queued ActiveJob job.
     def self.enqueue(active_job, scheduled_at: nil, create_with_advisory_lock: false)
       ActiveSupport::Notifications.instrument("enqueue_job.good_job", { active_job: active_job, scheduled_at: scheduled_at, create_with_advisory_lock: create_with_advisory_lock }) do |instrument_payload|
-        good_job = GoodJob::Job.new(
+        good_job_args = {
           queue_name: active_job.queue_name.presence || DEFAULT_QUEUE_NAME,
           priority: active_job.priority || DEFAULT_PRIORITY,
           serialized_params: active_job.serialize,
           scheduled_at: scheduled_at,
-          create_with_advisory_lock: create_with_advisory_lock
-        )
+          create_with_advisory_lock: create_with_advisory_lock,
+        }
+
+        if column_names.include?('active_job_id')
+          good_job_args[:active_job_id] = active_job.job_id
+        else
+          ActiveSupport::Deprecation.warn(<<~DEPRECATION)
+            GoodJob has pending database migrations. To create the migration files, run:
+
+                rails generate good_job:update
+
+            To apply the migration files, run:
+
+                rails db:migrate
+
+          DEPRECATION
+        end
+
+        good_job = GoodJob::Job.new(**good_job_args)
 
         instrument_payload[:good_job] = good_job
 

data/lib/good_job/lockable.rb

@@ -22,17 +22,25 @@ module GoodJob
     RecordAlreadyAdvisoryLockedError = Class.new(StandardError)
 
     included do
+      # Default column to be used when creating Advisory Locks
+      cattr_accessor(:advisory_lockable_column, instance_accessor: false) { primary_key }
+
+      # Default Postgres function to be used for Advisory Locks
+      cattr_accessor(:advisory_lockable_function) { "pg_try_advisory_lock" }
+
       # Attempt to acquire an advisory lock on the selected records and
       # return only those records for which a lock could be acquired.
-      # @!method advisory_lock
+      # @!method advisory_lock(column: advisory_lockable_column, function: advisory_lockable_function)
       # @!scope class
+      # @param column [String, Symbol] column values to Advisory Lock against
+      # @param function [String, Symbol]  Postgres Advisory Lock function name to use
       # @return [ActiveRecord::Relation]
       #   A relation selecting only the records that were locked.
-      scope :advisory_lock, (lambda do
+      scope :advisory_lock, (lambda do |column: advisory_lockable_column, function: advisory_lockable_function|
         original_query = self
 
         cte_table = Arel::Table.new(:rows)
-        cte_query = original_query.select(primary_key).except(:limit)
+        cte_query = original_query.select(primary_key, column).except(:limit)
         cte_type = if supports_cte_materialization_specifiers?
                      'MATERIALIZED'
                    else
@@ -41,9 +49,14 @@ module GoodJob
 
         composed_cte = Arel::Nodes::As.new(cte_table, Arel::Nodes::SqlLiteral.new([cte_type, "(", cte_query.to_sql, ")"].join(' ')))
 
+        # In addition to an advisory lock, there is also a FOR UPDATE SKIP LOCKED
+        # because this causes the query to skip jobs that were completed (and deleted)
+        # by another session in the time since the table snapshot was taken.
+        # In rare cases under high concurrency levels, leaving this out can result in double executions.
         query = cte_table.project(cte_table[:id])
                          .with(composed_cte)
-                         .where(Arel.sql(sanitize_sql_for_conditions(["pg_try_advisory_lock(('x' || substr(md5(:table_name || #{connection.quote_table_name(cte_table.name)}.#{quoted_primary_key}::text), 1, 16))::bit(64)::bigint)", { table_name: table_name }])))
+                         .where(Arel.sql(sanitize_sql_for_conditions(["#{function}(('x' || substr(md5(:table_name || #{connection.quote_table_name(cte_table.name)}.#{connection.quote_column_name(column)}::text), 1, 16))::bit(64)::bigint)", { table_name: table_name }])))
+                         .lock(Arel.sql("FOR UPDATE SKIP LOCKED"))
 
         limit = original_query.arel.ast.limit
         query.limit = limit.value if limit.present?
@@ -57,40 +70,44 @@ module GoodJob
       #
       # For details on +pg_locks+, see
       # {https://www.postgresql.org/docs/current/view-pg-locks.html}.
-      # @!method joins_advisory_locks
+      # @!method joins_advisory_locks(column: advisory_lockable_column)
       # @!scope class
+      # @param column [String, Symbol] column values to Advisory Lock against
       # @return [ActiveRecord::Relation]
       # @example Get the records that have a session awaiting a lock:
       #   MyLockableRecord.joins_advisory_locks.where("pg_locks.granted = ?", false)
-      scope :joins_advisory_locks, (lambda do
+      scope :joins_advisory_locks, (lambda do |column: advisory_lockable_column|
         join_sql = <<~SQL.squish
           LEFT JOIN pg_locks ON pg_locks.locktype = 'advisory'
             AND pg_locks.objsubid = 1
-            AND pg_locks.classid = ('x' || substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(32)::int
-            AND pg_locks.objid = (('x' || substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(64) << 32)::bit(32)::int
+            AND pg_locks.classid = ('x' || substr(md5(:table_name || #{quoted_table_name}.#{connection.quote_column_name(column)}::text), 1, 16))::bit(32)::int
+            AND pg_locks.objid = (('x' || substr(md5(:table_name || #{quoted_table_name}.#{connection.quote_column_name(column)}::text), 1, 16))::bit(64) << 32)::bit(32)::int
         SQL
 
         joins(sanitize_sql_for_conditions([join_sql, { table_name: table_name }]))
       end)
 
       # Find records that do not have an advisory lock on them.
-      # @!method advisory_unlocked
+      # @!method advisory_unlocked(column: advisory_lockable_column)
       # @!scope class
+      # @param column [String, Symbol] column values to Advisory Lock against
       # @return [ActiveRecord::Relation]
-      scope :advisory_unlocked, -> { joins_advisory_locks.where(pg_locks: { locktype: nil }) }
+      scope :advisory_unlocked, ->(column: advisory_lockable_column) { joins_advisory_locks(column: column).where(pg_locks: { locktype: nil }) }
 
       # Find records that have an advisory lock on them.
-      # @!method advisory_locked
+      # @!method advisory_locked(column: advisory_lockable_column)
       # @!scope class
+      # @param column [String, Symbol] column values to Advisory Lock against
       # @return [ActiveRecord::Relation]
-      scope :advisory_locked, -> { joins_advisory_locks.where.not(pg_locks: { locktype: nil }) }
+      scope :advisory_locked, ->(column: advisory_lockable_column) { joins_advisory_locks(column: column).where.not(pg_locks: { locktype: nil }) }
 
       # Find records with advisory locks owned by the current Postgres
       # session/connection.
-      # @!method advisory_locked
+      # @!method advisory_locked(column: advisory_lockable_column)
       # @!scope class
+      # @param column [String, Symbol] column values to Advisory Lock against
       # @return [ActiveRecord::Relation]
-      scope :owns_advisory_locked, -> { joins_advisory_locks.where('"pg_locks"."pid" = pg_backend_pid()') }
+      scope :owns_advisory_locked, ->(column: advisory_lockable_column) { joins_advisory_locks(column: column).where('"pg_locks"."pid" = pg_backend_pid()') }
 
       # Whether an advisory lock should be acquired in the same transaction
       # that created the record.
@@ -122,6 +139,9 @@ module GoodJob
       # can (as in {Lockable.advisory_lock}) and only pass those that could be
       # locked to the block.
       #
+      # @param column [String, Symbol]  name of advisory lock or unlock function
+      # @param function [String, Symbol] Postgres Advisory Lock function name to use
+      # @param unlock_session [Boolean] Whether to unlock all advisory locks in the session afterwards
       # @yield [Array<Lockable>] the records that were successfully locked.
       # @return [Object] the result of the block.
       #
@@ -129,14 +149,21 @@ module GoodJob
       #   MyLockableRecord.order(created_at: :asc).limit(2).with_advisory_lock do |record|
       #     do_something_with record
       #   end
-      def with_advisory_lock
+      def with_advisory_lock(column: advisory_lockable_column, function: advisory_lockable_function, unlock_session: false)
         raise ArgumentError, "Must provide a block" unless block_given?
 
-        records = advisory_lock.to_a
+        records = advisory_lock(column: column, function: function).to_a
         begin
           yield(records)
         ensure
-          records.each(&:advisory_unlock)
+          if unlock_session
+            advisory_unlock_session
+          else
+            records.each do |record|
+              key = [table_name, record[advisory_lockable_column]].join
+              record.advisory_unlock(key: key, function: advisory_unlockable_function(function))
+            end
+          end
         end
       end
 
@@ -145,49 +172,79 @@ module GoodJob
 
         @_supports_cte_materialization_specifiers = connection.postgresql_version >= 120000
       end
+
+      # Postgres advisory unlocking function for the class
+      # @param function [String, Symbol] name of advisory lock or unlock function
+      # @return [Boolean]
+      def advisory_unlockable_function(function = advisory_lockable_function)
+        function.to_s.sub("_lock", "_unlock").sub("_try_", "_")
+      end
+
+      # Unlocks all advisory locks active in the current database session/connection
+      # @return [void]
+      def advisory_unlock_session
+        connection.exec_query("SELECT pg_advisory_unlock_all()::text AS unlocked", 'GoodJob::Lockable Unlock Session').first[:unlocked]
+      end
+
+      # Converts SQL query strings between PG-compatible and JDBC-compatible syntax
+      # @param query [String]
+      # @return [Boolean]
+      def pg_or_jdbc_query(query)
+        if Concurrent.on_jruby?
+          # Replace $1 bind parameters with ?
+          query.gsub(/\$\d*/, '?')
+        else
+          query
+        end
+      end
     end
 
     # Acquires an advisory lock on this record if it is not already locked by
     # another database session. Be careful to ensure you release the lock when
     # you are done with {#advisory_unlock} (or {#advisory_unlock!} to release
     # all remaining locks).
+    # @param key [String, Symbol] Key to Advisory Lock against
+    # @param function [String, Symbol] Postgres Advisory Lock function name to use
     # @return [Boolean] whether the lock was acquired.
-    def advisory_lock
+    def advisory_lock(key: lockable_key, function: advisory_lockable_function)
       query = <<~SQL.squish
-        SELECT 1 AS one
-        WHERE pg_try_advisory_lock(('x'||substr(md5($1 || $2::text), 1, 16))::bit(64)::bigint)
+        SELECT #{function}(('x'||substr(md5($1::text), 1, 16))::bit(64)::bigint) AS locked
       SQL
-      binds = [[nil, self.class.table_name], [nil, send(self.class.primary_key)]]
-      self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Lock', binds).any?
+      binds = [[nil, key]]
+      self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Lock', binds).first['locked']
     end
 
     # Releases an advisory lock on this record if it is locked by this database
     # session. Note that advisory locks stack, so you must call
     # {#advisory_unlock} and {#advisory_lock} the same number of times.
+    # @param key [String, Symbol] Key to lock against
+    # @param function [String, Symbol] Postgres Advisory Lock function name to use
     # @return [Boolean] whether the lock was released.
-    def advisory_unlock
+    def advisory_unlock(key: lockable_key, function: self.class.advisory_unlockable_function(advisory_lockable_function))
       query = <<~SQL.squish
-        SELECT 1 AS one
-        WHERE pg_advisory_unlock(('x'||substr(md5($1 || $2::text), 1, 16))::bit(64)::bigint)
+        SELECT #{function}(('x'||substr(md5($1::text), 1, 16))::bit(64)::bigint) AS unlocked
       SQL
-      binds = [[nil, self.class.table_name], [nil, send(self.class.primary_key)]]
-      self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Unlock', binds).any?
+      binds = [[nil, key]]
+      self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Unlock', binds).first['unlocked']
     end
 
     # Acquires an advisory lock on this record or raises
     # {RecordAlreadyAdvisoryLockedError} if it is already locked by another
     # database session.
+    # @param key [String, Symbol] Key to lock against
+    # @param function [String, Symbol] Postgres Advisory Lock function name to use
     # @raise [RecordAlreadyAdvisoryLockedError]
     # @return [Boolean] +true+
-    def advisory_lock!
-      result = advisory_lock
+    def advisory_lock!(key: lockable_key, function: advisory_lockable_function)
+      result = advisory_lock(key: key, function: function)
       result || raise(RecordAlreadyAdvisoryLockedError)
     end
 
     # Acquires an advisory lock on this record and safely releases it after the
     # passed block is completed. If the record is locked by another database
     # session, this raises {RecordAlreadyAdvisoryLockedError}.
-    #
+    # @param key [String, Symbol] Key to lock against
+    # @param function [String, Symbol] Postgres Advisory Lock function name to use
     # @yield Nothing
     # @return [Object] The result of the block.
     #
@@ -196,64 +253,63 @@ module GoodJob
     #   record.with_advisory_lock do
     #     do_something_with record
     #   end
-    def with_advisory_lock
+    def with_advisory_lock(key: lockable_key, function: advisory_lockable_function)
       raise ArgumentError, "Must provide a block" unless block_given?
 
-      advisory_lock!
+      advisory_lock!(key: key, function: function)
       yield
     ensure
-      advisory_unlock unless $ERROR_INFO.is_a? RecordAlreadyAdvisoryLockedError
+      advisory_unlock(key: key, function: self.class.advisory_unlockable_function(function)) unless $ERROR_INFO.is_a? RecordAlreadyAdvisoryLockedError
     end
 
     # Tests whether this record has an advisory lock on it.
+    # @param key [String, Symbol] Key to test lock against
     # @return [Boolean]
-    def advisory_locked?
+    def advisory_locked?(key: lockable_key)
       query = <<~SQL.squish
         SELECT 1 AS one
         FROM pg_locks
         WHERE pg_locks.locktype = 'advisory'
           AND pg_locks.objsubid = 1
-          AND pg_locks.classid = ('x' || substr(md5($1 || $2::text), 1, 16))::bit(32)::int
-          AND pg_locks.objid = (('x' || substr(md5($3 || $4::text), 1, 16))::bit(64) << 32)::bit(32)::int
+          AND pg_locks.classid = ('x' || substr(md5($1::text), 1, 16))::bit(32)::int
+          AND pg_locks.objid = (('x' || substr(md5($2::text), 1, 16))::bit(64) << 32)::bit(32)::int
       SQL
-      binds = [[nil, self.class.table_name], [nil, send(self.class.primary_key)], [nil, self.class.table_name], [nil, send(self.class.primary_key)]]
+      binds = [[nil, key], [nil, key]]
       self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Locked?', binds).any?
     end
 
     # Tests whether this record is locked by the current database session.
+    # @param key [String, Symbol] Key to test lock against
     # @return [Boolean]
-    def owns_advisory_lock?
+    def owns_advisory_lock?(key: lockable_key)
       query = <<~SQL.squish
         SELECT 1 AS one
         FROM pg_locks
         WHERE pg_locks.locktype = 'advisory'
           AND pg_locks.objsubid = 1
-          AND pg_locks.classid = ('x' || substr(md5($1 || $2::text), 1, 16))::bit(32)::int
-          AND pg_locks.objid = (('x' || substr(md5($3 || $4::text), 1, 16))::bit(64) << 32)::bit(32)::int
+          AND pg_locks.classid = ('x' || substr(md5($1::text), 1, 16))::bit(32)::int
+          AND pg_locks.objid = (('x' || substr(md5($2::text), 1, 16))::bit(64) << 32)::bit(32)::int
           AND pg_locks.pid = pg_backend_pid()
       SQL
-      binds = [[nil, self.class.table_name], [nil, send(self.class.primary_key)], [nil, self.class.table_name], [nil, send(self.class.primary_key)]]
+      binds = [[nil, key], [nil, key]]
       self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Owns Advisory Lock?', binds).any?
     end
 
     # Releases all advisory locks on the record that are held by the current
     # database session.
+    # @param key [String, Symbol] Key to lock against
+    # @param function [String, Symbol] Postgres Advisory Lock function name to use
     # @return [void]
-    def advisory_unlock!
-      advisory_unlock while advisory_locked?
+    def advisory_unlock!(key: lockable_key, function: self.class.advisory_unlockable_function(advisory_lockable_function))
+      advisory_unlock(key: key, function: function) while advisory_locked?
     end
 
-    private
-
-    # @param query [String]
-    # @return [Boolean]
-    def pg_or_jdbc_query(query)
-      if Concurrent.on_jruby?
-        # Replace $1 bind parameters with ?
-        query.gsub(/\$\d*/, '?')
-      else
-        query
-      end
+    # Default Advisory Lock key
+    # @return [String]
+    def lockable_key
+      [self.class.table_name, self[self.class.advisory_lockable_column]].join
     end
+
+    delegate :pg_or_jdbc_query, to: :class
   end
 end

data/lib/good_job/poller.rb

@@ -5,11 +5,13 @@ module GoodJob # :nodoc:
   # Pollers regularly wake up execution threads to check for new work.
   #
   class Poller
+    TIMEOUT_INTERVAL = 5
+
     # Defaults for instance of Concurrent::TimerTask.
     # The timer controls how and when sleeping threads check for new work.
     DEFAULT_TIMER_OPTIONS = {
       execution_interval: Configuration::DEFAULT_POLL_INTERVAL,
-      timeout_interval: 1,
+      timeout_interval: TIMEOUT_INTERVAL,
       run_now: true,
     }.freeze
 
@@ -49,9 +51,11 @@ module GoodJob # :nodoc:
 
     # Tests whether the timer is shutdown.
     # @return [true, false, nil]
-    delegate :shutdown?, to: :timer, allow_nil: true
+    def shutdown?
+      timer ? timer.shutdown? : true
+    end
 
-    # Shut down the notifier.
+    # Shut down the poller.
     # Use {#shutdown?} to determine whether threads have stopped.
     # @param timeout [nil, Numeric] Seconds to wait for active threads.
     #   * +nil+, the scheduler will trigger a shutdown but not wait for it to complete.

data/lib/good_job/version.rb

@@ -1,4 +1,4 @@
 module GoodJob
   # GoodJob gem version.
-  VERSION = '1.9.6'.freeze
+  VERSION = '1.10.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: good_job
 version: !ruby/object:Gem::Version
-  version: 1.9.6
+  version: 1.10.0
 platform: ruby
 authors:
 - Ben Sheldon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-06-04 00:00:00.000000000 Z
+date: 2021-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.8.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.8.4
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
@@ -342,7 +356,11 @@ files:
 - exe/good_job
 - lib/active_job/queue_adapters/good_job_adapter.rb
 - lib/generators/good_job/install_generator.rb
-- lib/generators/good_job/templates/migration.rb.erb
+- lib/generators/good_job/templates/install/migrations/create_good_jobs.rb.erb
+- lib/generators/good_job/templates/update/migrations/01_create_good_jobs.rb
+- lib/generators/good_job/templates/update/migrations/02_add_active_job_id_concurrency_key_cron_key_to_good_jobs.rb
+- lib/generators/good_job/templates/update/migrations/03_add_active_job_id_index_and_concurrency_key_index_to_good_jobs.rb
+- lib/generators/good_job/update_generator.rb
 - lib/good_job.rb
 - lib/good_job/adapter.rb
 - lib/good_job/cli.rb