Sidekiq-Cron: The Basics and a Quick Tutorial

What Is Sidekiq-Cron?

Sidekiq-Cron is an extension for Sidekiq, a background job processing library for Ruby. It enables users to schedule jobs in a recurring fashion, much like traditional UNIX cron jobs, directly inside Ruby applications. By leveraging Redis as the backing storage, Sidekiq-Cron can reliably enqueue tasks at designated intervals, supporting time-based automation within Rails or other Ruby projects. This bridges the gap between ad hoc scheduling and fully integrated background processing. It is worth noting that the Sidekiq Enterprise version also offers the cron job feature out of the box.

Unlike relying on operating system-level cron, Sidekiq-Cron allows job schedules to be managed within the same context and technology stack as the application’s business logic. Schedules can be tracked, modified, or disabled programmatically. This centralization reduces operational overhead and makes scheduled jobs visible and tunable via the application’s own configuration or web-based dashboard instead of requiring DevOps access to underlying infrastructure.

You can download Sidekiq-Cron from the official GitHub repo.

This is part of a series of articles about Sidekiq.

Why Use Sidekiq-Cron?

Sidekiq-Cron offers several practical advantages for managing recurring background jobs within a Ruby or Rails application:

• Centralized scheduling: Keeps job definitions and schedules within the application codebase, eliminating the need for external cron configurations or system-level access.
• Dynamic configuration: Job schedules can be added, removed, or updated at runtime through Ruby code or the web UI, making it easy to adjust behavior without redeploying or accessing the server.
• Visibility and monitoring: Provides clear insight into scheduled jobs via the Sidekiq web dashboard, helping developers and operators track when jobs will run and whether they are succeeding.
• Redis integration: Uses Redis for storing schedule metadata, ensuring fast access and compatibility with Sidekiq’s job queueing mechanism.
• Code-level control: Enables conditional scheduling based on application state or environment, making it easier to adapt job behavior during development, testing, or production.
• Error handling and retry: Leverages Sidekiq’s built-in retry and error handling features, offering a more reliable alternative to traditional cron, which lacks such support.
• Environment consistency: Ensures the same scheduling logic applies across development, staging, and production environments, reducing discrepancies between environments.

Key Features of Sidekiq-Cron 

Cron-like Scheduling

Sidekiq-Cron lets developers define job schedules using familiar cron expressions, providing control over job timing. Patterns like 0 2 * * * (for 2 AM nightly), */10 * * * * (every ten minutes), or more complex expressions can be assigned to different classes of jobs. This syntax mirrors traditional cron, making migration and onboarding straightforward for those familiar with server-side cron.

Using cron expressions enables flexible scheduling, supporting hourly, daily, weekly, or even irregular intervals. This flexibility benefits complex applications needing varied background process timing. Rather than scripting around system crontab limitations, developers can declare sophisticated schedules directly in application code or configuration files, reducing operational friction and minimizing risks of human error.

Integration with Sidekiq

Sidekiq-Cron operates as a seamless add-on to Sidekiq, integrating closely with its job processing and Redis-backed storage. When a scheduled time arrives, Sidekiq-Cron enqueues the specified job into the appropriate Sidekiq queue, allowing jobs to be executed, retried, or monitored just like standard Sidekiq jobs. There’s no need for separate toolchains or adapters; everything utilizes Sidekiq’s existing infrastructure, simplifying deployment and monitoring.

This tight integration also benefits from Sidekiq’s resilience to system failures. Because job definitions and schedules live in Redis, Sidekiq-Cron can continue to function properly even across server restarts or scaling events. Jobs get picked up by any available Sidekiq worker, and their state persists in the system, removing single points of failure common with system cron.

Concurrency Safety

One concern in distributed systems is ensuring that scheduled jobs execute once and only once at their designated time, even with multiple Sidekiq processes running. Sidekiq-Cron addresses this by using a Redis sorted set, ensuring that only one process enqueues a scheduled job during a given interval. This guarantees concurrency safety, so jobs don’t run multiple times due to race conditions.

YAML Configuration

Sidekiq-Cron supports YAML-based job schedule configuration. Teams can define their entire recurring job schedule in a single YAML file, specifying cron expressions, job class names, and queue details. This structure integrates well with Rails and modern infrastructure-as-code approaches, making job schedules easy to manage alongside the rest of the project’s configuration.

YAML configuration improves transparency and collaboration. Schedules can be placed under version control, reviewed during code audits, and promoted across environments via standard deployment workflows. Developers can also leverage Rails’ environment-merging features to apply different job schedules for development, staging, or production with minimal duplication or risk.

Web UI Integration

Sidekiq-Cron extends the Sidekiq web dashboard with a dedicated interface for scheduled jobs. Administrators and developers can view all current cron jobs, see their next scheduled runtime, and verify if any are disabled or failing. Schedules can be added, edited, or removed in real time via the browser, reducing operational friction and empowering non-infrastructure team members to fine-tune job scheduling.

This UI-driven approach helps with troubleshooting and auditability. Job histories, errors, and execution logs are accessible alongside the schedules themselves, streamlining diagnostic workflows. By exposing job management in the web dashboard, Sidekiq-Cron democratizes access to scheduling and keeps repetitive tasks or critical background flows visible and under control.

Sidekiq-Cron Use Cases 

Nightly Data Cleanup

A common scenario for Sidekiq-Cron is automating routine data cleanup tasks, such as purging expired sessions, deleting temporary files, or archiving stale records. Developers can schedule jobs to run during off-peak hours, ensuring that database maintenance doesn’t interfere with active user traffic. By using Sidekiq-Cron, teams can codify these routines as background jobs, making them both predictable and monitorable.

Periodic API Synchronization

Many web applications depend on integrating data from external APIs, such as updating user records, synchronizing product catalogs, or pulling analytics snapshots. Sidekiq-Cron enables these synchronization jobs to be scheduled at predictable intervals—every few minutes, hourly, or daily—ensuring that the system remains up-to-date with external sources without manual triggers. Developers avoid the pitfalls of manual cron integration, such as environment inconsistencies or authentication errors.

Recurring User Notifications or Digest Emails

Email notifications—such as weekly digests, monthly summaries, or daily reminders—are ideal candidates for scheduling via Sidekiq-Cron. Developers can set up jobs that aggregate data and trigger notification sends at precise times, balancing user engagement needs with infrastructure efficiency. By managing these schedules in-app, teams reduce the need for third-party tools or external marketing automation platforms.

Multi-Tenant or Dynamic Schedule Jobs

In SaaS applications, requirements often arise for custom schedules—such as per-customer report generation or per-tenant data exports. Sidekiq-Cron allows dynamic schedule creation, updating, and deletion at runtime, leveraging its API and YAML structure. An application can offer self-service tools for end users to define their report or export intervals, translating those to cron jobs managed by the backend.

Quick Tutorial: Getting Started with Sidekiq-Cron 

To start using Sidekiq-Cron in a Ruby or Rails project, follow these basic steps to install, configure, and create scheduled jobs. Instructions are adapted from the project GitHub repo.

1. Install the Gem

Add Sidekiq-Cron to your Gemfile:

gem 'sidekiq-cron'

Then run:

bundle install

If you are not using Rails, ensure you require the library manually:

require 'sidekiq'
require 'sidekiq-cron'

2. Define a Job

Create a Sidekiq job that performs some background tasks. For example:

class HardJob
  include Sidekiq::Job

  def perform(name, count)
    puts "Working with #{name}, count: #{count}"
  end
end

This class defines the logic that will be executed on the schedule you configure.

3. Create a Scheduled Job

You can schedule jobs dynamically using Sidekiq::Cron::Job.create:

Sidekiq::Cron::Job.create(
  name: 'HardJob - every 5min',
  cron: '*/5 * * * *',
  class: 'HardJob',
  args: ['Demo', 1]
)

This sets up a job to run the HardJob class every five minutes, passing the specified arguments to the perform method.

4. (Optional) Load Jobs from YAML

Instead of creating jobs in code, you can define them in a YAML file:

# config/schedule.yml
hard_job:
  cron: "*/5 * * * *"
  class: "HardJob"
  queue: default
  args:
    - "From YAML"
    - 2

Then load it automatically on startup by creating an initializer:

# config/initializers/sidekiq-cron.rb
Sidekiq.configure_server do |config|
  config.on(:startup) do
    schedule_file = "config/schedule.yml"
    if File.exist?(schedule_file)
      schedule = YAML.load_file(schedule_file)
      Sidekiq::Cron::Job.load_from_hash!(schedule, source: "schedule")
    end
  end
end

5. (Optional) Additional Configuration Options

You can customize how Sidekiq-Cron behaves through its configuration block:

Sidekiq::Cron.configure do |config|
  config.cron_poll_interval = 10 # check schedules every 10 seconds
  config.cron_schedule_file = 'config/schedule.yml'
  config.default_namespace = 'default'
  config.reschedule_grace_period = 600 # 10 minutes
end

Place this block in an initializer if you’re using Rails.

6. Enable the Web UI

To manage and monitor cron jobs via the Sidekiq web UI, add this line:

require 'sidekiq/web'
require 'sidekiq/cron/web'

This will add a “Cron” tab to the dashboard where you can view, edit, and manually trigger scheduled jobs.

7. Run Sidekiq

Start the Sidekiq process to begin polling and executing scheduled jobs:

bundle exec sidekiq

Make sure Redis is running, as both Sidekiq and Sidekiq-Cron depend on it.

Running Sidekiq with Dragonfly

Dragonfly is a modern, source-available, multi-threaded, Redis-compatible in-memory data store that stands out by delivering unmatched performance and efficiency. Designed from the ground up to disrupt legacy technologies, Dragonfly redefines what an in-memory data store can achieve.

When scaling your Sidekiq deployment to handle a massive amount of jobs, replacing Redis with Dragonfly can be transformative. Dragonfly unlocks superior performance by utilizing a multi-threaded architecture to increase throughput for a large number of Sidekiq clients and servers.

• Read our blog: Running and Optimizing Sidekiq Workloads with Dragonfly
• Watch our video (with Sidekiq creator Mike Perham): Diving Deep into Sidekiq and Dragonfly

Dragonfly Cloud

Dragonfly Cloud is a fully managed service from the creators of Dragonfly, handling all operations and delivering effortless scaling so you can focus on what matters without worrying about in-memory data infrastructure anymore. You can get a Dragonfly data store up and running in just a few minutes with Dragonfly Cloud.