Sidecloq

Recurring / Periodic / Scheduled / Cron job extension for Sidekiq

Why

There are several options for running periodic tasks with Sidekiq, including sidekiq-scheduler, sidekiq-cron, as well as Sidekiq Enterprise. Each tackles the problem slightly differently. Sidecloq is inspired by various facets of these projects, as well as resque-scheduler. I urge you to take a look at all of these options to see what works best for you.

Sidecloq is:

• Clean: Sidecloq leverages only the public API of Sidekiq, and does not pollute the Sidekiq namespace.
• Easy to deploy: Sidecloq boots with all Sidekiq processes, automatically. Leader election ensures only one process enqueues jobs, and a new leader is automatically chosen should the current leader die.
• Easy to configure: Schedule configuration is done in YAML, using the familiar cron syntax. No special DSL or job class mixins required.

Installation

Add this line to your application's Gemfile:

gem 'sidecloq'

Requires sidekiq version >= 6.4. MRI < 2.7 and jruby < 9.4 are not supported.

Configuration

Quickstart

Tell Sidecloq where your schedule file is located:

Sidecloq.configure do |config|
  config[:schedule_file] = "path/to/myschedule.yml"
end

Rails

If using Rails, and your schedule is located at config/sidecloq.yml, Sidecloq will find the schedule automatically (ie, you don't have to use the above configuration block).

Schedule file format

Example:

my_scheduled_job: # a unique name for this schedule
  class: Jobs::DoWork # the job class
  args: [100]       # (optional) set of arguments
  cron: "* * * * *" # cron formatted schedule
  queue: "queue_name" # Sidekiq queue for job

my_scheduled_job_with_args:
  class: Jobs::WorkerWithArgs
  args:
    batch_size: 100
  cron: "1 1 * * *"
  queue: "queue_name"

my_other_scheduled_job:
  class: Jobs::AnotherClassName
  cron: "1 1 * * *"
  queue: "a_different_queue"

Rails

If using Rails, you can nest the schedules under top-level environment keys, and Sidecloq will select the correct group based on the Rails environment. This is useful for development/staging scenarios. For example:

production:
  # these will only run in production
  my_scheduled_job:
    class: Jobs::ClassName
    cron: "* * * * *"
    queue: "queue_name"

staging:
  # this will only run in staging
  my_other_scheduled_job:
    class: Jobs::AnotherClassName
    cron: "1 1 * * *"
    queue: "a_different_queue"

Web Extension

Add Sidecloq::Web after Sidekiq::Web:

require 'sidekiq/web'
require 'sidecloq/web'

This will add a "Recurring" tab to the sidekiq web ui, where the loaded schedules are displayed. You can enqueue a job immediately by clicking it's corresponding "Enqueue now" button.

Contributing

Bug reports and pull requests are welcome.

License

The gem is available as open source under the terms of the MIT License.