schked 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d392bfee50671c6bc87ab00b4cbdb29969e55544d35a6133ce23b24f1d3171e
-  data.tar.gz: 196a09231bd9abb1c0a83f7d4d6d4ecb140cb3b305e1710aa775f21690ae3eb7
+  metadata.gz: de7c669767af942f29f4c3414334cc7e996d8d41c3e9375ef2a249cc7ccc3b22
+  data.tar.gz: a55cb9f96f1eb18d43452ad0e61ec1d722c51d316f4e6b6604d7627b82aaaa2c
 SHA512:
-  metadata.gz: '02810b0f6a3717db6e4f5aa4cee9eee4644c74c7a583fbc1c0e6acae97d63193366c1ecbd0ee087106acbe542a49ace4e5cdfe209aba0b11c3d31938ef088638'
-  data.tar.gz: b55de68f347b8be57cc32cbf13ef582cd4ac33c8cddb881bfcead7bc449454953147c20bd311a03bfaa38c444884e6bf45daa7b54d2bb4bcbad5e2207d50194e
+  metadata.gz: 5691b00d0cd7b9575e82a743b45c7e0210593f34648a2bf1d98f7b387538805a9acea000f63724f6a31b81ce6b21a7825919b975023de04e46285eb009788ea8
+  data.tar.gz: 9184dd5c9190dff9f43c3534487fb4d38b6355fdd93b66d61b859f30dfc9c95d4d469d1298bb2f7f314a824ae577943835cfc530d5ff4dd3646e239a6f75b1ff

data/README.md

@@ -30,9 +30,9 @@ gem install schked
 
 ## Supported Ruby and Rails versions
 
-Schked requires **Ruby 2.7+**.
+Schked requires **Ruby 3.0+**.
 
-The test matrix covers Ruby **2.7, 3.0, 3.1, 3.2, 3.3, 3.4, and 4.0**. Rails integration tests run on every Ruby; Rails 8 is only included on Ruby **3.2+**.
+The test matrix covers Ruby **3.0, 3.1, 3.2, 3.3, 3.4, and 4.0**. Rails integration tests run on every Ruby; Rails 8 is only included on Ruby **3.2+**.
 
 ## Usage
 
@@ -80,7 +80,11 @@ bundle exec schked show
 
 ### Duplicate scheduling
 
-When you deploy your schedule to production, you want to start new instance before you shut down the current. And you don't want simultaneous working of both. To achieve a seamless transition, Schked is using Redis for locks.
+Schked ships two coordination strategies for multi-instance deployments. Choose one via `Schked.config.job_run_store`:
+
+#### Single-active-instance (default)
+
+When you deploy your schedule to production, you want to start new instance before you shut down the current. And you don't want simultaneous working of both. To achieve a seamless transition, Schked uses Redis for a global lock.
 
 You can configure Redis client as the following:
 
@@ -88,6 +92,67 @@ You can configure Redis client as the following:
 Schked.config.redis = {url: ENV.fetch("REDIS_URL") }
 ```
 
+This is the default — one instance runs all jobs; standby instances hold the global Redis lock and stay idle. This strategy will continue to be supported because it is the simplest and most predictable for many setups.
+
+#### Per-job deduplication
+
+When you want every scheduler instance to do useful work (and not require a global leader), opt into the per-job deduplication mode. Each recurring job claims its schedule interval atomically; only one instance wins each interval, so each job still runs exactly once across the cluster.
+
+Pick a coordination store:
+
+```ruby
+# Redis-backed (default Redis client from Schked.config.redis):
+Schked.config.job_run_store = :redis
+
+# Database-backed (no Redis required). The ActiveRecord or Sequel
+# connection pool is auto-detected; override via:
+Schked.config.job_run_store = :database
+Schked.config.database_connection = conn   # optional: Sequel::Database, ActiveRecord pool, or AR connection (PostgreSQL, Mysql2, or Trilogy)
+
+# Custom store responding to #claim(job_name, window_start) and #cleanup(older_than):
+Schked.config.job_run_store = my_store
+```
+
+The database backend runs entirely through the ActiveRecord/Sequel connection pool: claims and the internal cleanup sweep check connections out per operation, so they are thread-safe and survive database restarts and failovers. MySQL 8.0+ is required for the MySQL DDL.
+
+Additional tuning:
+
+```ruby
+Schked.config.max_skew = 60  # max expected clock skew between instances (seconds)
+```
+
+Schedule behavior in deduplication mode:
+
+- `every` jobs are aligned to an absolute time grid so all instances share the same phase. The first firing is the next grid point relative to now — not relative to process start.
+- `cron` jobs already align to absolute time natively and need no change.
+- `at` / `in` (one-time) jobs are deduplicated too — the claim is kept for the store's retention period (the Redis TTL / the database sweep window).
+- `interval` jobs **are not supported** and raise `Schked::ScheduleDSL::IntervalNotSupportedError` when scheduled in this mode. Their phase depends on job duration and cannot be grid-aligned. Use `every` or `cron` instead.
+
+##### Durability of the coordination store
+
+Choosing between `:redis` and `:database` is also choosing how strong the exactly-once guarantee is:
+
+- **`:database`** — claims are durable rows guarded by a UNIQUE constraint. They survive database restarts and failovers, and nothing removes them before the internal cleanup sweep (which keeps rows for 24 hours). Prefer this backend when a duplicate run is unacceptable.
+- **`:redis`** — claims are keys with a TTL of `max(10 × max_skew, 1 hour)`, so the guarantee is only as strong as the Redis instance's durability:
+  - **Eviction policy** must be `noeviction` (or the instance must never reach `maxmemory`). Claim keys have a TTL, so both `allkeys-*` and `volatile-*` policies can evict them under memory pressure — the evicted window may then be claimed and executed by another instance.
+  - **Persistence**: a Redis restart without AOF/RDB loses in-flight claims. If it happens inside the contention window (the `max_skew`-wide interval during which instances race to claim the same slot), the job may run twice. Enable AOF, or use `:database` if you cannot accept that risk.
+
+Failure semantics (both backends):
+
+- The claim is taken **before** the job runs, so the semantics are *at-most-once per window*: if the winning instance crashes mid-run, that window's execution is lost and Schked does not retry it.
+- The coordination store is a hard dependency: when it is unreachable, the claim fails and the firing is skipped (fail-closed) rather than risking a duplicate.
+
+##### Database store migration
+
+Run the migration generator to print the `schked_job_runs` DDL:
+
+```sh
+bundle exec schked generate-migration               # Postgres
+bundle exec schked generate-migration --flavor=mysql
+```
+
+Copy the SQL into your application's migration and run it. The gem does not write migration files or run DDL on its own — it stays framework-agnostic.
+
 ### Callbacks
 
 Also, you can define callbacks for errors handling:

data/lib/schked/adapters/active_record.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Schked
+  # Adapter for ActiveRecord connection pools (PostgreSQL, Mysql2,
+  # Trilogy). Implements the +Schked::JobRunStore+ contract.
+  #
+  # The adapter wraps a connection *pool*, not a single connection: every
+  # operation checks a connection out via +with_connection+ and returns it
+  # afterwards. The lease guarantees exclusive use of the checked-out
+  # connection, so claims (scheduler thread) and the cleanup sweep (work
+  # threads) can safely share the pool, and the pool transparently
+  # replaces dead connections after a database restart or failover.
+  class Adapters
+    class ActiveRecord
+      include JobRunStore
+
+      SUPPORTED_ADAPTERS = %w[PostgreSQL Mysql2 Trilogy].freeze
+
+      attr_reader :adapter_name
+      attr_reader :logger
+
+      def initialize(pool, logger: Logger.new($stdout))
+        # Accept either a ConnectionPool or a concrete adapter connection
+        # (+ActiveRecord::Base.connection+) and normalize to the pool.
+        @pool = pool.respond_to?(:with_connection) ? pool : pool.pool
+        @logger = logger
+        validate_adapter!
+      end
+
+      def claim(job_name, window_start)
+        validate!(job_name, window_start)
+
+        ts = window_start.is_a?(Time) ? window_start.to_i : Integer(window_start)
+        run_at = Time.now.to_f
+        claimer = SecureRandom.uuid
+
+        @pool.with_connection do |connection|
+          if postgres?
+            postgres_claim(connection, job_name, ts, run_at, claimer)
+          else
+            mysql_claim(connection, job_name, ts, run_at, claimer)
+          end
+        end
+      rescue ArgumentError
+        raise
+      rescue => e
+        logger.error("Failed to claim AR job run with error: #{e.message}")
+        raise
+      end
+
+      def cleanup(older_than)
+        cutoff = older_than.is_a?(Time) ? older_than.to_i : Integer(older_than)
+        @pool.with_connection do |connection|
+          connection.execute("DELETE FROM #{TABLE} WHERE window_start < #{connection.quote(cutoff)}")
+        end
+        nil
+      rescue => e
+        logger.error("Failed to clean up AR job runs with error: #{e.message}")
+        raise
+      end
+
+      private
+
+      TABLE = "schked_job_runs"
+
+      def validate_adapter!
+        name = @pool.with_connection do |connection|
+          connection.respond_to?(:adapter_name) ? connection.adapter_name.to_s : ""
+        end
+        unless SUPPORTED_ADAPTERS.any? { |supported| supported.casecmp?(name) }
+          raise ArgumentError,
+            "Schked::Adapters::ActiveRecord supports #{SUPPORTED_ADAPTERS.join(", ")} " \
+            "connections only, got: #{name.inspect}"
+        end
+
+        # Cached: claim/cleanup dispatch on the dialect without extra
+        # adapter_name round-trips on every firing.
+        @adapter_name = name
+      end
+
+      def postgres?
+        adapter_name.include?("Postgre") || adapter_name.include?("Postgres")
+      end
+
+      # Postgres can decide atomically in a single statement: INSERT ...
+      # ON CONFLICT DO NOTHING RETURNING yields a row only for the winner.
+      def postgres_claim(connection, job_name, ts, run_at, claimer)
+        sql = "INSERT INTO #{TABLE} (job_name, window_start, run_at, claimer) " \
+          "VALUES (#{connection.quote(job_name)}, #{connection.quote(ts)}, " \
+          "#{connection.quote(run_at)}, #{connection.quote(claimer)}) " \
+          "ON CONFLICT (job_name, window_start) DO NOTHING RETURNING id"
+        Integer(connection.exec_query(sql, "Schked CLAIM").length).positive?
+      end
+
+      # Rails' mysql2 and trilogy adapters both connect with the
+      # CLIENT_FOUND_ROWS capability set unconditionally (see
+      # mysql2_adapter.rb / trilogy_adapter.rb), so affected_rows cannot
+      # distinguish a fresh insert from a matched duplicate. Instead every
+      # claimer writes a unique token and reads it back: the
+      # UNIQUE (job_name, window_start) constraint guarantees exactly one
+      # row survives, so only the claimer whose token is stored in that
+      # row won the window.
+      def mysql_claim(connection, job_name, ts, run_at, claimer)
+        insert = "INSERT IGNORE INTO #{TABLE} (job_name, window_start, run_at, claimer) " \
+          "VALUES (#{connection.quote(job_name)}, #{connection.quote(ts)}, " \
+          "#{connection.quote(run_at)}, #{connection.quote(claimer)})"
+        connection.execute(insert)
+
+        select = "SELECT claimer FROM #{TABLE} " \
+          "WHERE job_name = #{connection.quote(job_name)} AND window_start = #{connection.quote(ts)}"
+        row = connection.exec_query(select, "Schked CLAIM").first
+        !row.nil? && row["claimer"] == claimer
+      end
+
+      def validate!(job_name, window_start)
+        raise ArgumentError, "job_name must be a non-empty String" if job_name.to_s.empty?
+        raise ArgumentError, "window_start must not be nil" if window_start.nil?
+      end
+    end
+  end
+end

data/lib/schked/adapters/sequel.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Schked
+  # Adapter for Sequel (Postgres or MySQL via +Sequel::Database+).
+  # Implements the +Schked::JobRunStore+ contract. Both operations go
+  # through Sequel's thread-safe connection pool, so claims (scheduler
+  # thread) and the cleanup sweep (work threads) can overlap freely.
+  class Adapters
+    class Sequel
+      include JobRunStore
+
+      SUPPORTED_DATABASE_TYPES = %w[postgres mysql].freeze
+
+      attr_reader :logger
+
+      def initialize(database, logger: Logger.new($stdout))
+        @database = database
+        @logger = logger
+        type = database.database_type.to_s
+        unless SUPPORTED_DATABASE_TYPES.include?(type)
+          raise ArgumentError,
+            "Schked::Adapters::Sequel supports Postgres and MySQL databases only, got: #{type.inspect}"
+        end
+      end
+
+      def claim(job_name, window_start)
+        validate!(job_name, window_start)
+
+        ts = window_start.is_a?(Time) ? window_start.to_i : Integer(window_start)
+        run_at = Time.now.to_f
+        claimer = SecureRandom.uuid
+
+        if postgres?
+          # Sequel's +insert_conflict+ is a PostgreSQL-only dataset method;
+          # it returns the new PK on success and +nil+ on conflict, so the
+          # winner is decided atomically in a single statement.
+          id = dataset
+            .insert_conflict(target: UNIQUE_COLUMNS)
+            .insert(job_name: job_name, window_start: ts, run_at: run_at, claimer: claimer)
+          !id.nil?
+        else
+          mysql_claim(job_name, ts, run_at, claimer)
+        end
+      rescue ArgumentError
+        raise
+      rescue => e
+        logger.error("Failed to claim sequel job run with error: #{e.message}")
+        raise
+      end
+
+      def cleanup(older_than)
+        cutoff = older_than.is_a?(Time) ? older_than.to_i : Integer(older_than)
+        dataset.where { window_start < cutoff }.delete
+        nil
+      rescue => e
+        logger.error("Failed to clean up sequel job runs with error: #{e.message}")
+        raise
+      end
+
+      def adapter_name
+        @database.adapter_scheme.to_s
+      end
+
+      private
+
+      TABLE = :schked_job_runs
+      UNIQUE_COLUMNS = %i[job_name window_start].freeze
+
+      def postgres?
+        @database.database_type == :postgres
+      end
+
+      # MySQL has no +RETURNING+, and affected-rows semantics depend on the
+      # CLIENT_FOUND_ROWS connection flag, so the winner cannot be derived
+      # from the insert alone. Instead every claimer writes a unique token
+      # and reads it back: the UNIQUE (job_name, window_start) constraint
+      # guarantees exactly one row survives, so only the claimer whose
+      # token is stored in that row won the window. +insert_ignore+ is a
+      # MySQL dataset method (+INSERT IGNORE+).
+      def mysql_claim(job_name, ts, run_at, claimer)
+        sql = dataset
+          .insert_ignore
+          .insert_sql(job_name: job_name, window_start: ts, run_at: run_at, claimer: claimer)
+
+        @database.synchronize do |conn|
+          conn.query(sql)
+        end
+
+        row = @database[TABLE]
+          .where(job_name: job_name, window_start: ts)
+          .select(:claimer)
+          .first
+        !row.nil? && row[:claimer] == claimer
+      end
+
+      def dataset
+        @database[TABLE]
+      end
+
+      def validate!(job_name, window_start)
+        raise ArgumentError, "job_name must be a non-empty String" if job_name.to_s.empty?
+        raise ArgumentError, "window_start must not be nil" if window_start.nil?
+      end
+    end
+  end
+end

data/lib/schked/callbacks.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Schked
+  # Installs rufus-scheduler callbacks that translate rufus events into
+  # schked semantics: per-job deduplication claims via the configured
+  # +JobRunStore+, logging, and user-registered +Schked.config+ callbacks
+  # (+:before_start+, +:after_finish+, +:on_error+, +:around_job+).
+  #
+  # Extracted from +Schked::Worker+ so the worker stays focused on
+  # lifecycle and the callback wiring remains independently testable.
+  class Callbacks
+    # Marker prefix for schked's own internal jobs (cleanup, liveness
+    # heartbeat). These are exempt from dedup claims.
+    INTERNAL_JOB_PREFIX = "Schked::Worker#"
+
+    def initialize(config:, job_run_store: nil)
+      @config = config
+      @job_run_store = job_run_store
+    end
+
+    def install(scheduler)
+      cfg = @config
+      store = @job_run_store
+      internal = method(:internal_job?)
+      # Unlabeled jobs are skipped on every firing; logging the guidance at
+      # error level for each firing would spam operators (an `every 10s`
+      # job yields 8_640 messages per day). Remember which labels were
+      # already reported and downgrade repeat notices to debug.
+      missing_as_reported = {}
+
+      scheduler.define_singleton_method(:extract_job_name) do |job|
+        if job
+          job.opts[:as] || job.job_id
+        else
+          "unknown"
+        end
+      end
+
+      scheduler.define_singleton_method(:on_error) do |job, error|
+        cfg.logger.fatal("Task #{extract_job_name(job)} failed with error: #{error.message}")
+        cfg.logger.error(error.backtrace.join("\n")) if error.backtrace
+
+        cfg.fire_callback(:on_error, job, error)
+      end
+
+      scheduler.define_singleton_method(:on_pre_trigger) do |job, time|
+        job_name = extract_job_name(job).to_s
+
+        if store && internal.call(job_name)
+          # Internal schked jobs (cleanup sweep, liveness heartbeat) skip
+          # the dedup claim entirely so they always run on every instance.
+        elsif store
+          unless job.opts[:as]
+            # Without an explicit +as:+, the dedup key falls back to
+            # +job.job_id+, which encodes the Ruby +object_id+ of the
+            # +Rufus::Scheduler::Job+ and is unique per process. Claiming
+            # with that key would silently duplicate every run across the
+            # cluster. Refuse to claim; the operator must add +as:+ to
+            # their schedule for dedup to be correct.
+            if missing_as_reported.key?(job_name)
+              cfg.logger.debug("Skipping task #{job_name}: still no `as:` label (already reported).")
+            else
+              cfg.logger.error(
+                "Task #{job_name} has no `as:` label and cannot be deduplicated " \
+                "(each process generates a unique job_id). Add `as: \"my_job\"` to " \
+                "the schedule entry. Skipping this firing."
+              )
+              missing_as_reported[job_name] = true
+            end
+            next false
+          end
+
+          window_start = job.previous_time || job.scheduled_at
+          begin
+            claimed = store.claim(job_name, window_start)
+          rescue => e
+            # Fail closed, but say what actually happened: the task did not
+            # fail — the coordination store is unavailable, and firing is
+            # skipped to avoid a duplicate run.
+            cfg.logger.fatal("Skipped task #{job_name}: job run store unavailable: #{e.class} #{e.message}")
+            cfg.fire_callback(:on_error, job, e)
+            next false
+          end
+          unless claimed
+            cfg.logger.info("Skipped task: #{job_name} (already claimed for window_start=#{window_start.to_i})")
+            next false
+          end
+        end
+
+        cfg.logger.info("Started task: #{extract_job_name(job)}")
+        cfg.fire_callback(:before_start, job, time)
+      end
+
+      scheduler.define_singleton_method(:around_trigger) do |job, &block|
+        cfg.fire_around_callback(:around_job, job, &block)
+      end
+
+      scheduler.define_singleton_method(:on_post_trigger) do |job, time|
+        cfg.logger.info("Finished task: #{extract_job_name(job)}")
+
+        cfg.fire_callback(:after_finish, job, time)
+      end
+
+      scheduler
+    end
+
+    def internal_job?(job_name)
+      job_name.start_with?(INTERNAL_JOB_PREFIX)
+    end
+  end
+end

data/lib/schked/cli.rb

@@ -47,6 +47,12 @@ module Schked
       puts "====="
     end
 
+    desc "generate-migration", "Print DDL SQL for the schked_job_runs table to stdout"
+    option :flavor, type: :string, default: "postgres", desc: "DDL flavor (postgres or mysql)"
+    def generate_migration(flavor = nil)
+      puts MigrationGenerator.sql(flavor || options[:flavor])
+    end
+
     private
 
     def load_requires

data/lib/schked/config.rb

@@ -4,10 +4,15 @@ require "logger"
 
 module Schked
   class Config
+    VALID_JOB_RUN_STORES = %i[redis database].freeze
+
     attr_writer :logger,
       :do_not_load_root_schedule,
       :redis,
-      :standalone
+      :standalone,
+      :job_run_store,
+      :max_skew,
+      :database_connection
 
     def liveness_probe
       @liveness_probe ||= LivenessProbeConfig.new
@@ -81,8 +86,59 @@ module Schked
       !!@standalone
     end
 
+    attr_reader :job_run_store
+
+    def max_skew
+      @max_skew ||= 60
+    end
+
+    attr_reader :database_connection
+
+    def dedup_enabled?
+      !@job_run_store.nil?
+    end
+
+    # Validates all configuration options. Called by the worker during
+    # initialization so the worker can remain agnostic about which options
+    # exist and which combinations are legal.
+    def validate!
+      validate_job_run_store!
+      validate_max_skew!
+    end
+
     private
 
+    def validate_max_skew!
+      return if @max_skew.nil?
+
+      begin
+        skew = Integer(@max_skew)
+      rescue ArgumentError, TypeError
+        raise ArgumentError,
+          "Schked `max_skew` must be a positive number of seconds, got: #{@max_skew.inspect}"
+      end
+
+      return if skew.positive?
+
+      raise ArgumentError,
+        "Schked `max_skew` must be a positive number of seconds, got: #{@max_skew.inspect}"
+    end
+
+    def validate_job_run_store!
+      return if @job_run_store.nil?
+
+      message = "Schked `job_run_store` must be one of #{VALID_JOB_RUN_STORES.inspect}, " \
+        "a Symbol, or an object responding to #claim and #cleanup; got: #{@job_run_store.inspect}"
+
+      valid = if @job_run_store.is_a?(Symbol)
+        VALID_JOB_RUN_STORES.include?(@job_run_store)
+      else
+        @job_run_store.respond_to?(:claim) && @job_run_store.respond_to?(:cleanup)
+      end
+
+      raise ArgumentError, message unless valid
+    end
+
     def callbacks
       @callbacks ||= Hash.new { |hsh, key| hsh[key] = [] }
     end

data/lib/schked/database_connection.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Schked
+  # Auto-detects which +Schked::Adapters::*+ class to use for the
+  # database-backed coordination store. Returns a concrete +JobRunStore+
+  # instance — the caller should not need to know which backend is in play.
+  #
+  # Resolution order:
+  # 1. An explicit connection/pool if provided.
+  # 2. +ActiveRecord::Base.connection_pool+ when ActiveRecord is loaded
+  #    and configured (the pool, not a single connection, so the adapter
+  #    can check out per operation).
+  # 3. Sequel's first available +Sequel::DATABASES+ database.
+  # 4. Otherwise raises a clear +NotFoundError+ telling the operator to
+  #    set +database_connection+ explicitly.
+  module DatabaseConnection
+    class NotFoundError < StandardError; end
+
+    module_function
+
+    def detect(connection: nil, logger: Logger.new($stdout))
+      raw = connection || auto_detect_connection
+      wrap(raw, logger: logger)
+    end
+
+    def wrap(raw, logger: Logger.new($stdout))
+      case raw
+      when Adapters::Sequel, Adapters::ActiveRecord
+        raw
+      else
+        build_for(raw, logger: logger)
+      end
+    end
+
+    def build_for(raw, logger: Logger.new($stdout))
+      if defined?(::Sequel::Database) && raw.is_a?(::Sequel::Database)
+        Adapters::Sequel.new(raw, logger: logger)
+      elsif raw.respond_to?(:with_connection)
+        # An ActiveRecord connection pool.
+        Adapters::ActiveRecord.new(raw, logger: logger)
+      elsif raw.respond_to?(:pool) && raw.respond_to?(:adapter_name)
+        # A concrete ActiveRecord adapter connection — normalize to its pool.
+        Adapters::ActiveRecord.new(raw.pool, logger: logger)
+      elsif raw.respond_to?(:claim) && raw.respond_to?(:cleanup)
+        # Already a store: a pre-built adapter or a custom object.
+        raw
+      else
+        raise NotFoundError,
+          "Schked could not detect an adapter for: #{raw.class}. " \
+          "Provide a Sequel::Database, an ActiveRecord connection pool, " \
+          "or an ActiveRecord connection (PostgreSQL, Mysql2, or Trilogy)."
+      end
+    end
+
+    def auto_detect_connection
+      if defined?(ActiveRecord) && ActiveRecord.const_defined?(:Base)
+        begin
+          return ActiveRecord::Base.connection_pool
+        rescue
+          # ActiveRecord is loaded but not configured (or the pool cannot
+          # be resolved) — fall through to Sequel detection below.
+        end
+      end
+
+      if defined?(Sequel) && Sequel.respond_to?(:DATABASES) && Sequel::DATABASES.any?
+        return Sequel::DATABASES.first
+      end
+
+      raise NotFoundError,
+        "Schked could not detect a database connection for the database-backed " \
+        "job run store. Load ActiveRecord or Sequel, or set `Schked.config.database_connection` " \
+        "explicitly."
+    end
+  end
+end

data/lib/schked/job_run_store.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Schked
+  # Abstract interface for the per-job coordination store used by the
+  # deduplication mode. A store records which `(job_name, window_start)` pairs
+  # have been claimed, so two scheduler instances cannot execute the same job
+  # in the same interval.
+  #
+  # Two built-in backends are provided: Redis (see +RedisJobRunStore+) and
+  # database (see +DatabaseJobRunStore+). An operator may also supply any
+  # custom object that responds to +#claim+ and +#cleanup+.
+  module JobRunStore
+    # Atomically records that +job_name+ was claimed for the interval starting
+    # at +window_start+ (a Time/Integer epoch).
+    #
+    # Returns +true+ if this caller won the claim (the job may run) and +false+
+    # if the interval is already claimed by another instance (the job must be
+    # skipped). Raises +ArgumentError+ for invalid arguments.
+    def claim(job_name, window_start)
+      raise NotImplementedError, "#{self.class} must implement #claim(job_name, window_start)"
+    end
+
+    # Removes records whose window_start is older than +older_than+. The
+    # Redis backend relies on native TTL and provides a no-op; the database
+    # backend deletes matching rows.
+    def cleanup(older_than)
+      raise NotImplementedError, "#{self.class} must implement #cleanup(older_than)"
+    end
+  end
+end

data/lib/schked/migration_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Schked
+  # Generates the DDL for the +schked_job_runs+ table used by the
+  # database-backed coordination store. Operators copy the SQL into their own
+  # migration; schked does not write migration files or run DDL on its own.
+  module MigrationGenerator
+    module_function
+
+    DDL_POSTGRES = <<~SQL
+      CREATE TABLE schked_job_runs (
+        id BIGSERIAL PRIMARY KEY,
+        job_name TEXT NOT NULL,
+        window_start BIGINT NOT NULL,
+        run_at DOUBLE PRECISION NOT NULL,
+        claimer TEXT NOT NULL,
+        CONSTRAINT schked_job_runs_unique UNIQUE (job_name, window_start)
+      );
+
+      CREATE INDEX schked_job_runs_window_start_idx ON schked_job_runs (window_start);
+    SQL
+
+    DDL_MYSQL = <<~SQL
+      CREATE TABLE schked_job_runs (
+        id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+        job_name VARCHAR(255) NOT NULL,
+        window_start BIGINT NOT NULL,
+        run_at DOUBLE NOT NULL,
+        claimer VARCHAR(255) NOT NULL,
+        UNIQUE KEY schked_job_runs_unique (job_name, window_start),
+        KEY schked_job_runs_window_start_idx (window_start)
+      );
+    SQL
+
+    def sql(flavor = "postgres")
+      case flavor.to_s.downcase
+      when "mysql" then DDL_MYSQL
+      else DDL_POSTGRES
+      end
+    end
+  end
+end

data/lib/schked/redis_job_run_store.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Schked
+  # Redis-backed implementation of the per-job coordination store.
+  # Uses +SET key 1 NX EX <ttl>+ so the first caller wins and TTL handles
+  # expiration; #cleanup is a no-op because native TTL covers retention.
+  class RedisJobRunStore
+    include JobRunStore
+
+    KEY_PREFIX = "schked:job_run"
+
+    attr_reader :redis_client, :logger, :max_skew_seconds
+
+    def initialize(redis_client:, logger: Logger.new($stdout), max_skew_seconds: 60)
+      @redis_client = redis_client
+      @logger = logger
+      @max_skew_seconds = Integer(max_skew_seconds)
+    end
+
+    def claim(job_name, window_start)
+      validate!(job_name, window_start)
+
+      key = build_key(job_name, window_start)
+      ttl = default_ttl
+
+      # +SET ... NX EX+ is atomic on a single Redis instance and is the
+      # idiomatic primitive for "claim this slot for at most N seconds".
+      # Transport errors (connection refused, timeout, ...) raise out of
+      # this method so the caller knows the store is unavailable — silently
+      # returning +false+ would skip every job while Redis is down.
+      #
+      # Why not Redlock? Redlock (the algorithm used by +RedisLocker+) is
+      # designed for cluster-wide consensus across multiple Redis masters.
+      # For this dedup, a single +SET NX EX+ is already atomic per
+      # instance and sufficient for exactly-once across the cluster of
+      # *schedulers* — the scheduler cluster itself uses one Redis (or a
+      # single master with replicas).
+      redis_client.call("SET", key, "1", "NX", "EX", ttl) == "OK"
+    end
+
+    def cleanup(_older_than)
+      # Native Redis TTL handles expiration; nothing to do here.
+      nil
+    end
+
+    private
+
+    def default_ttl
+      # The key only needs to outlive the contention window — the interval
+      # (up to +max_skew+, plus scheduling jitter) during which instances
+      # race to claim the same slot. Expiry between windows is harmless:
+      # each window gets its own key. The floor keeps a minimum protective
+      # period for one-shot +at+/+in+ claims against instances that boot
+      # with a delay.
+      [10 * @max_skew_seconds, 3600].max
+    end
+
+    def build_key(job_name, window_start)
+      ts = window_start.is_a?(Time) ? window_start.to_i : Integer(window_start)
+      "#{KEY_PREFIX}:#{job_name}:#{ts}"
+    end
+
+    def validate!(job_name, window_start)
+      raise ArgumentError, "job_name must be a non-empty String" if job_name.to_s.empty?
+      raise ArgumentError, "window_start must not be nil" if window_start.nil?
+    end
+  end
+end

data/lib/schked/schedule_dsl.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rufus/scheduler"
+
+module Schked
+  # Wraps the rufus-scheduler DSL so deduplication mode (+job_run_store+ is
+  # configured) makes +every+ jobs grid-aligned (via injected +first_at+) and
+  # rejects +interval+ jobs (their phase drifts with job duration and cannot
+  # be deduplicated).
+  #
+  # In the default (non-dedup) mode the wrapper is transparent and forwards
+  # every call to the underlying scheduler.
+  class ScheduleDSL
+    class IntervalNotSupportedError < StandardError; end
+
+    attr_reader :scheduler
+
+    def initialize(scheduler:, dedup_enabled:, max_skew_seconds: 60, logger: Logger.new(File::NULL))
+      @scheduler = scheduler
+      @dedup_enabled = dedup_enabled
+      @max_skew_seconds = Integer(max_skew_seconds)
+      @logger = logger
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @scheduler.respond_to?(name, include_private) || super
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      case name
+      when :every
+        every_with_alignment(*args, **kwargs, &block)
+      when :interval
+        raise IntervalNotSupportedError, interval_error_message if @dedup_enabled
+
+        @scheduler.interval(*args, **kwargs, &block)
+      else
+        @scheduler.public_send(name, *args, **kwargs, &block)
+      end
+    end
+
+    private
+
+    def every_with_alignment(duration, *args, **kwargs, &block)
+      if @dedup_enabled
+        seconds = Rufus::Scheduler.parse_duration(duration)
+        # Shift "now" backward by +max_skew+ so that two instances whose
+        # clocks differ by up to +max_skew+ still land on the same grid
+        # point. Without this shift, an instance that is half a skew
+        # ahead could pick a different slot than one that is half a skew
+        # behind, and both would claim the job.
+        first_at = Time.at(next_grid_point_epoch(seconds, Time.now.to_f - @max_skew_seconds))
+        if kwargs.key?(:first_at)
+          @logger.warn(
+            "Schked: ignoring `first_at: #{kwargs[:first_at].inspect}` for `every` job " \
+            "in deduplication mode — grid alignment is required for claims"
+          )
+        end
+        kwargs = kwargs.merge(first_at: first_at)
+      end
+
+      @scheduler.every(duration, *args, **kwargs, &block)
+    end
+
+    def next_grid_point_epoch(seconds, shifted_now)
+      grid_point = (shifted_now / seconds).ceil * seconds
+      # When the interval is comparable to or smaller than +max_skew+, the
+      # grid point closest to "now − max_skew" may still lie in the past,
+      # and rufus-scheduler rejects a past +first_at+. Advance by whole
+      # periods until the slot is strictly in the future: every step keeps
+      # the value on the absolute (epoch-multiple) grid, so all instances
+      # stay phase-aligned regardless of how many steps they take.
+      grid_point += seconds while grid_point <= Time.now.to_f
+      grid_point
+    end
+
+    def interval_error_message
+      "`interval` jobs are not supported when `Schked.config.job_run_store` is configured. " \
+        "Their phase depends on job duration and cannot be aligned to a stable grid. " \
+        "Use `every` or `cron` instead."
+    end
+  end
+end

data/lib/schked/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Schked
-  VERSION = "1.5.0"
+  VERSION = "2.0.0"
 end

data/lib/schked/worker.rb

@@ -4,17 +4,24 @@ require "rufus/scheduler"
 
 module Schked
   class Worker
+    DEFAULT_CLEANUP_INTERVAL = "60s"
+    DEFAULT_CLEANUP_RETENTION = 24 * 60 * 60 # seconds before cutoff
+
     def initialize(config:)
       @config = config
       @liveness_probe = nil
 
-      @locker = RedisLocker.new(config.redis, lock_ttl: 40_000, logger: config.logger) unless config.standalone?
+      config.validate!
+      @job_run_store = build_job_run_store
+      @locker = build_locker
 
-      @scheduler = Rufus::Scheduler.new(trigger_lock: locker)
+      scheduler_opts = {trigger_lock: locker}.compact
+      @scheduler = Rufus::Scheduler.new(**scheduler_opts)
 
       watch_signals
-      define_callbacks
-      define_extend_lock unless config.standalone?
+      Callbacks.new(config: config, job_run_store: @job_run_store).install(@scheduler)
+      define_extend_lock if locker
+      define_cleanup_job if database_backed_store?
       load_schedule
       start_liveness_probe
     end
@@ -47,41 +54,33 @@ module Schked
 
     private
 
-    attr_reader :config, :scheduler, :locker, :liveness_probe
-
-    def define_callbacks
-      cfg = config
-
-      scheduler.define_singleton_method(:extract_job_name) do |job|
-        if job
-          job.opts[:as] || job.job_id
-        else
-          "unknown"
-        end
-      end
-
-      scheduler.define_singleton_method(:on_error) do |job, error|
-        cfg.logger.fatal("Task #{extract_job_name(job)} failed with error: #{error.message}")
-        cfg.logger.error(error.backtrace.join("\n")) if error.backtrace
-
-        cfg.fire_callback(:on_error, job, error)
-      end
-
-      scheduler.define_singleton_method(:on_pre_trigger) do |job, time|
-        cfg.logger.info("Started task: #{extract_job_name(job)}")
-
-        cfg.fire_callback(:before_start, job, time)
-      end
-
-      scheduler.define_singleton_method(:around_trigger) do |job, &block|
-        cfg.fire_around_callback(:around_job, job, &block)
+    attr_reader :config, :scheduler, :locker, :liveness_probe, :job_run_store
+
+    def build_job_run_store
+      return nil unless config.dedup_enabled?
+
+      case config.job_run_store
+      when :redis
+        RedisJobRunStore.new(
+          redis_client: RedisClientFactory.build(config.redis),
+          logger: config.logger,
+          max_skew_seconds: config.max_skew
+        )
+      when :database
+        DatabaseConnection.detect(
+          connection: config.database_connection,
+          logger: config.logger
+        )
+      else
+        config.job_run_store
       end
+    end
 
-      scheduler.define_singleton_method(:on_post_trigger) do |job, time|
-        cfg.logger.info("Finished task: #{extract_job_name(job)}")
+    def build_locker
+      return nil if config.standalone?
+      return nil if config.dedup_enabled?
 
-        cfg.fire_callback(:after_finish, job, time)
-      end
+      RedisLocker.new(config.redis, lock_ttl: 40_000, logger: config.logger)
     end
 
     def watch_signals
@@ -112,8 +111,36 @@ module Schked
       end
     end
 
+    def define_cleanup_job
+      store = @job_run_store
+      logger = config.logger
+
+      scheduler.every(DEFAULT_CLEANUP_INTERVAL, as: "Schked::Worker#cleanup_job_runs", overlap: false) do
+        cutoff = Time.now.to_i - (DEFAULT_CLEANUP_RETENTION + config.max_skew)
+        logger.debug("Cleaning up database job runs older than #{cutoff}")
+        store.cleanup(cutoff)
+      rescue => e
+        logger.error("Failed to clean up database job runs: #{e.message}")
+      end
+    end
+
+    # Only stores whose +#cleanup+ actually deletes rows need the sweep.
+    # +RedisJobRunStore#cleanup+ is a no-op (native TTL handles retention),
+    # so scheduling it would just log noise on every instance. Custom
+    # stores keep the sweep because they implemented +#cleanup+ for it.
+    # Returns +false+ when no store is configured (default mode).
+    def database_backed_store?
+      !job_run_store.nil? && !job_run_store.is_a?(RedisJobRunStore)
+    end
+
     def load_schedule
-      scheduler.instance_eval(schedule)
+      dsl = ScheduleDSL.new(
+        scheduler: scheduler,
+        dedup_enabled: config.dedup_enabled?,
+        max_skew_seconds: config.max_skew,
+        logger: config.logger
+      )
+      dsl.instance_eval(schedule)
     end
 
     def start_liveness_probe

data/lib/schked.rb

@@ -6,6 +6,14 @@ require "redlock"
 require "schked/version"
 require "schked/liveness_probe"
 require "schked/config"
+require "schked/job_run_store"
+require "schked/redis_job_run_store"
+require "schked/adapters/sequel"
+require "schked/adapters/active_record"
+require "schked/database_connection"
+require "schked/schedule_dsl"
+require "schked/callbacks"
+require "schked/migration_generator"
 require "schked/worker"
 require "schked/redis_locker"
 require "schked/redis_client_factory"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schked
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Misha Merkushin
@@ -209,12 +209,20 @@ files:
 - README.md
 - exe/schked
 - lib/schked.rb
+- lib/schked/adapters/active_record.rb
+- lib/schked/adapters/sequel.rb
+- lib/schked/callbacks.rb
 - lib/schked/cli.rb
 - lib/schked/config.rb
+- lib/schked/database_connection.rb
+- lib/schked/job_run_store.rb
 - lib/schked/liveness_probe.rb
+- lib/schked/migration_generator.rb
 - lib/schked/railtie.rb
 - lib/schked/redis_client_factory.rb
+- lib/schked/redis_job_run_store.rb
 - lib/schked/redis_locker.rb
+- lib/schked/schedule_dsl.rb
 - lib/schked/version.rb
 - lib/schked/worker.rb
 homepage: https://github.com/bibendi/schked
@@ -229,7 +237,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="