good_job 1.9.2 → 1.10.0

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.rb

@@ -30,7 +30,7 @@ module GoodJob
   #   @!scope class
   #   The logger used by GoodJob (default: +Rails.logger+).
   #   Use this to redirect logs to a special location or file.
-  #   @return [Logger]
+  #   @return [Logger, nil]
   #   @example Output GoodJob logs to a file:
   #     GoodJob.logger = ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new("log/my_logs.log"))
   mattr_accessor :logger, default: ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new($stdout))
@@ -42,7 +42,7 @@ module GoodJob
   #   If you want to preserve jobs for latter inspection, set this to +true+.
   #   If you want to preserve only jobs that finished with error for latter inspection, set this to +:on_unhandled_error+.
   #   If +true+, you will need to clean out jobs using the +good_job cleanup_preserved_jobs+ CLI command.
-  #   @return [Boolean]
+  #   @return [Boolean, nil]
   mattr_accessor :preserve_job_records, default: false
 
   # @!attribute [rw] retry_on_unhandled_error
@@ -51,10 +51,11 @@ module GoodJob
   #   If +true+, causes jobs to be re-queued and retried if they raise an instance of +StandardError+.
   #   If +false+, jobs will be discarded or marked as finished if they raise an instance of +StandardError+.
   #   Instances of +Exception+, like +SIGINT+, will *always* be retried, regardless of this attribute's value.
-  #   @return [Boolean]
+  #   @return [Boolean, nil]
   mattr_accessor :retry_on_unhandled_error, default: true
 
   # @deprecated Use {GoodJob#retry_on_unhandled_error} instead.
+  # @return [Boolean, nil]
   def self.reperform_jobs_on_standard_error
     ActiveSupport::Deprecation.warn(
       "Calling 'GoodJob.reperform_jobs_on_standard_error' is deprecated. Please use 'retry_on_unhandled_error'"
@@ -63,6 +64,8 @@ module GoodJob
   end
 
   # @deprecated Use {GoodJob#retry_on_unhandled_error=} instead.
+  # @param value [Boolean]
+  # @return [Boolean]
   def self.reperform_jobs_on_standard_error=(value)
     ActiveSupport::Deprecation.warn(
       "Setting 'GoodJob.reperform_jobs_on_standard_error=' is deprecated. Please use 'retry_on_unhandled_error='"
@@ -77,7 +80,7 @@ module GoodJob
   #   @example Send errors to Sentry
   #     # config/initializers/good_job.rb
   #     GoodJob.on_thread_error = -> (exception) { Raven.capture_exception(exception) }
-  #   @return [#call, nil]
+  #   @return [Proc, nil]
   mattr_accessor :on_thread_error, default: nil
 
   # Stop executing jobs.
@@ -93,13 +96,13 @@ module GoodJob
   # @param wait [Boolean] whether to wait for shutdown
   # @return [void]
   def self.shutdown(timeout: -1, wait: nil)
-    timeout = if wait.present?
+    timeout = if wait.nil?
+                timeout
+              else
                 ActiveSupport::Deprecation.warn(
                   "Using `GoodJob.shutdown` with `wait:` kwarg is deprecated; use `timeout:` kwarg instead e.g. GoodJob.shutdown(timeout: #{wait ? '-1' : 'nil'})"
                 )
                 wait ? -1 : nil
-              else
-                timeout
               end
 
     executables = Array(Notifier.instances) + Array(Poller.instances) + Array(Scheduler.instances)
@@ -119,6 +122,7 @@ module GoodJob
   # When forking processes you should shut down these background threads before forking, and restart them after forking.
   # For example, you should use +shutdown+ and +restart+ when using async execution mode with Puma.
   # See the {file:README.md#executing-jobs-async--in-process} for more explanation and examples.
+  # @param timeout [Numeric, nil] Seconds to wait for active threads to finish.
   # @return [void]
   def self.restart(timeout: -1)
     executables = Array(Notifier.instances) + Array(Poller.instances) + Array(Scheduler.instances)
@@ -126,7 +130,7 @@ module GoodJob
   end
 
   # Sends +#shutdown+ or +#restart+ to executable objects ({GoodJob::Notifier}, {GoodJob::Poller}, {GoodJob::Scheduler})
-  # @param executables [Array<(Notifier, Poller, Scheduler)>] Objects to shut down.
+  # @param executables [Array<Notifier, Poller, Scheduler, MultiScheduler>] Objects to shut down.
   # @param method_name [:symbol] Method to call, e.g. +:shutdown+ or +:restart+.
   # @param timeout [nil,Numeric]
   # @return [void]

data/lib/good_job/adapter.rb

@@ -6,7 +6,7 @@ module GoodJob
     # Valid execution modes.
     EXECUTION_MODES = [:async, :async_server, :external, :inline].freeze
 
-    # @param execution_mode [nil, Symbol] specifies how and where jobs should be executed. You can also set this with the environment variable +GOOD_JOB_EXECUTION_MODE+.
+    # @param execution_mode [Symbol, nil] specifies how and where jobs should be executed. You can also set this with the environment variable +GOOD_JOB_EXECUTION_MODE+.
     #
     #  - +:inline+ executes jobs immediately in whatever process queued them (usually the web server process). This should only be used in test and development environments.
     #  - +:external+ causes the adapter to enqueue jobs, but not execute them. When using this option (the default for production environments), you'll need to use the command-line tool to actually execute your jobs.
@@ -19,9 +19,9 @@ module GoodJob
     #  - +development+ and +test+: +:inline+
     #  - +production+ and all other environments: +:external+
     #
-    # @param max_threads [nil, Integer] sets the number of threads per scheduler to use when +execution_mode+ is set to +:async+. The +queues+ parameter can specify a number of threads for each group of queues which will override this value. You can also set this with the environment variable +GOOD_JOB_MAX_THREADS+. Defaults to +5+.
-    # @param queues [nil, String] determines which queues to execute jobs from when +execution_mode+ is set to +:async+. See {file:README.md#optimize-queues-threads-and-processes} for more details on the format of this string. You can also set this with the environment variable +GOOD_JOB_QUEUES+. Defaults to +"*"+.
-    # @param poll_interval [nil, Integer] sets the number of seconds between polls for jobs when +execution_mode+ is set to +:async+. You can also set this with the environment variable +GOOD_JOB_POLL_INTERVAL+. Defaults to +1+.
+    # @param max_threads [Integer, nil] sets the number of threads per scheduler to use when +execution_mode+ is set to +:async+. The +queues+ parameter can specify a number of threads for each group of queues which will override this value. You can also set this with the environment variable +GOOD_JOB_MAX_THREADS+. Defaults to +5+.
+    # @param queues [String, nil] determines which queues to execute jobs from when +execution_mode+ is set to +:async+. See {file:README.md#optimize-queues-threads-and-processes} for more details on the format of this string. You can also set this with the environment variable +GOOD_JOB_QUEUES+. Defaults to +"*"+.
+    # @param poll_interval [Integer, nil] sets the number of seconds between polls for jobs when +execution_mode+ is set to +:async+. You can also set this with the environment variable +GOOD_JOB_POLL_INTERVAL+. Defaults to +1+.
     def initialize(execution_mode: nil, queues: nil, max_threads: nil, poll_interval: nil)
       if caller[0..4].find { |c| c.include?("/config/application.rb") || c.include?("/config/environments/") }
         ActiveSupport::Deprecation.warn(<<~DEPRECATION)
@@ -70,7 +70,7 @@ module GoodJob
     # Enqueues an ActiveJob job to be run at a specific time.
     # For use by Rails; you should generally not call this directly.
     # @param active_job [ActiveJob::Base] the job to be enqueued from +#perform_later+
-    # @param timestamp [Integer] the epoch time to perform the job
+    # @param timestamp [Integer, nil] the epoch time to perform the job
     # @return [GoodJob::Job]
     def enqueue_at(active_job, timestamp)
       good_job = GoodJob::Job.enqueue(
@@ -97,22 +97,21 @@ module GoodJob
     end
 
     # Shut down the thread pool executors.
-    # @param timeout [nil, Numeric] Seconds to wait for active threads.
-    #
+    # @param timeout [nil, Numeric, Symbol] Seconds to wait for active threads.
     #   * +nil+, the scheduler will trigger a shutdown but not wait for it to complete.
     #   * +-1+, the scheduler will wait until the shutdown is complete.
     #   * +0+, the scheduler will immediately shutdown and stop any threads.
     #   * A positive number will wait that many seconds before stopping any remaining active threads.
-    # @param wait [Boolean] Deprecated. Use +timeout:+ instead.
+    # @param wait [Boolean, nil] Deprecated. Use +timeout:+ instead.
     # @return [void]
     def shutdown(timeout: :default, wait: nil)
-      timeout = if wait.present?
+      timeout = if wait.nil?
+                  timeout
+                else
                   ActiveSupport::Deprecation.warn(
                     "Using `GoodJob::Adapter.shutdown` with `wait:` kwarg is deprecated; use `timeout:` kwarg instead e.g. GoodJob::Adapter.shutdown(timeout: #{wait ? '-1' : 'nil'})"
                   )
                   wait ? -1 : nil
-                else
-                  timeout
                 end
 
       timeout = if timeout == :default
@@ -126,18 +125,21 @@ module GoodJob
     end
 
     # Whether in +:async+ execution mode.
+    # @return [Boolean]
     def execute_async?
       @configuration.execution_mode == :async ||
         @configuration.execution_mode == :async_server && in_server_process?
     end
 
     # Whether in +:external+ execution mode.
+    # @return [Boolean]
     def execute_externally?
       @configuration.execution_mode == :external ||
         @configuration.execution_mode == :async_server && !in_server_process?
     end
 
     # Whether in +:inline+ execution mode.
+    # @return [Boolean]
     def execute_inline?
       @configuration.execution_mode == :inline
     end
@@ -145,11 +147,13 @@ module GoodJob
     private
 
     # Whether running in a web server process.
+    # @return [Boolean, nil]
     def in_server_process?
       return @_in_server_process if defined? @_in_server_process
 
       @_in_server_process = Rails.const_defined?('Server') ||
                             caller.grep(%r{config.ru}).any? || # EXAMPLE: config.ru:3:in `block in <main>' OR config.ru:3:in `new_from_string'
+                            caller.grep(%{/rack/handler/}).any? || # EXAMPLE: iodine-0.7.44/lib/rack/handler/iodine.rb:13:in `start'
                             (Concurrent.on_jruby? && caller.grep(%r{jruby/rack/rails_booter}).any?) # EXAMPLE: uri:classloader:/jruby/rack/rails_booter.rb:83:in `load_environment'
     end
   end

data/lib/good_job/configuration.rb

@@ -84,9 +84,9 @@ module GoodJob
     # on the format of this string.
     # @return [String]
     def queue_string
-      options[:queues] ||
-        rails_config[:queues] ||
-        env['GOOD_JOB_QUEUES'] ||
+      options[:queues].presence ||
+        rails_config[:queues].presence ||
+        env['GOOD_JOB_QUEUES'].presence ||
         '*'
     end
 

data/lib/good_job/current_execution.rb

@@ -3,7 +3,6 @@ require 'active_support/core_ext/module/attribute_accessors_per_thread'
 module GoodJob
   # Thread-local attributes for passing values from Instrumentation.
   # (Cannot use ActiveSupport::CurrentAttributes because ActiveJob resets it)
-
   module CurrentExecution
     # @!attribute [rw] error_on_retry
     #   @!scope class

data/lib/good_job/daemon.rb

@@ -13,6 +13,7 @@ module GoodJob
     end
 
     # Daemonizes the current process and writes out a pidfile.
+    # @return [void]
     def daemonize
       check_pid
       Process.daemon
@@ -21,6 +22,7 @@ module GoodJob
 
     private
 
+    # @return [void]
     def write_pid
       File.open(pidfile, ::File::CREAT | ::File::EXCL | ::File::WRONLY) { |f| f.write(Process.pid.to_s) }
       at_exit { File.delete(pidfile) if File.exist?(pidfile) }
@@ -29,10 +31,12 @@ module GoodJob
       retry
     end
 
+    # @return [void]
     def delete_pid
       File.delete(pidfile) if File.exist?(pidfile)
     end
 
+    # @return [void]
     def check_pid
       case pid_status(pidfile)
       when :running, :not_owned
@@ -42,6 +46,8 @@ module GoodJob
       end
     end
 
+    # @param pidfile [Pathname, String]
+    # @return [Symbol]
     def pid_status(pidfile)
       return :exited unless File.exist?(pidfile)
 

data/lib/good_job/job.rb

@@ -50,6 +50,14 @@ module GoodJob
       end
     end
 
+    # Get Jobs with given class name
+    # @!method with_job_class
+    # @!scope class
+    # @param string [String]
+    #   Job class name
+    # @return [ActiveRecord::Relation]
+    scope :with_job_class, ->(job_class) { where("serialized_params->>'job_class' = ?", job_class) }
+
     # Get Jobs that have not yet been completed.
     # @!method unfinished
     # @!scope class
@@ -94,6 +102,12 @@ module GoodJob
     # @return [ActiveRecord::Relation]
     scope :finished, ->(timestamp = nil) { timestamp ? where(arel_table['finished_at'].lteq(timestamp)) : where.not(finished_at: nil) }
 
+    # Get Jobs that started but not finished yet.
+    # @!method running
+    # @!scope class
+    # @return [ActiveRecord::Relation]
+    scope :running, -> { where.not(performed_at: nil).where(finished_at: nil) }
+
     # Get Jobs on queues that match the given queue string.
     # @!method queue_string(string)
     # @!scope class
@@ -142,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
@@ -182,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
 
@@ -235,7 +266,7 @@ module GoodJob
 
     private
 
-    # @return [GoodJob::ExecutionResult]
+    # @return [ExecutionResult]
     def execute
       params = serialized_params.merge(
         "provider_job_id" => id

data/lib/good_job/job_performer.rb

@@ -24,7 +24,7 @@ module GoodJob
     end
 
     # Perform the next eligible job
-    # @return [nil, Object] Returns job result or +nil+ if no job was found
+    # @return [Object, nil] Returns job result or +nil+ if no job was found
     def next
       job_query.perform_with_advisory_lock
     end
@@ -54,7 +54,7 @@ module GoodJob
     # @param after [DateTime, Time, nil] future jobs scheduled after this time
     # @param limit [Integer] number of future timestamps to return
     # @param now_limit [Integer] number of past timestamps to return
-    # @return [Array<(Time, DateTime)>, nil]
+    # @return [Array<DateTime, Time>, nil]
     def next_at(after: nil, limit: nil, now_limit: nil)
       job_query.next_scheduled_at(after: after, limit: limit, now_limit: now_limit)
     end

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,67 +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
-
-    def sanitize_sql_for_conditions(*args)
-      # Made public in Rails 5.2
-      self.class.send(:sanitize_sql_for_conditions, *args)
+    # Default Advisory Lock key
+    # @return [String]
+    def lockable_key
+      [self.class.table_name, self[self.class.advisory_lockable_column]].join
     end
 
-    def pg_or_jdbc_query(query)
-      if Concurrent.on_jruby?
-        # Replace $1 bind parameters with ?
-        query.gsub(/\$\d*/, '?')
-      else
-        query
-      end
-    end
+    delegate :pg_or_jdbc_query, to: :class
   end
 end