Sidekiq-Cron Upgrade Guide (1.10.1 → 2.3.1)

This guide documents the upgrade of sidekiq-cron from version 1.10.1 to 2.3.1 in the Reports application.

Summary

On October 29, 2024, we upgraded sidekiq-cron from version 1.10.1 to 2.3.1. This major version upgrade brings several improvements and requires awareness of breaking changes, though our application code did not require modifications.

What Changed

Gem Versions Updated

Gem	Old Version	New Version
sidekiq-cron	1.10.1	2.3.1
sidekiq	7.1.4	7.3.9
fugit	1.11.1	1.12.1
et-orbi	1.2.11	1.4.0
globalid	1.2.1	1.3.0
redis-client	0.17.0	0.26.1
connection_pool	2.4.1	2.5.4
minitest	5.25.5	5.26.0

New Dependency

• cronex (0.15.0) - A new dependency added in sidekiq-cron 2.x for enhanced cron expression parsing

Breaking Changes

1. Minimum Sidekiq Version

Requirement: Sidekiq 6.5.0 or higher

Our application was already using Sidekiq 7.1.4, so this requirement was already met.

2. Minimum Redis Version

Requirement: Redis 4.0 or higher

Ensure your Redis server is at least version 4.0.

3. New Configuration Options

Sidekiq-cron 2.x introduces new configuration options that can be used in job definitions:

Retry Configuration

You can now specify retry behavior directly in your cron job definition:

Sidekiq::Cron::Job.new(
  name: 'my_job',
  cron: '0 * * * *',
  class: 'MyJob',
  retry: 5  # or false to disable retries
)

Namespace Support

Jobs can now be organized into namespaces:

Sidekiq::Cron::Job.new(
  name: 'my_job',
  cron: '0 * * * *',
  class: 'MyJob',
  namespace: 'default'  # organize jobs by namespace
)

4. Enhanced Cron Expression Support

Sidekiq-cron 2.x uses fugit 1.11.1+ which provides improved natural language support for cron schedules. Our existing cron expressions continue to work without modification.

Impact on Our Application

Configuration Files

• config/schedule.yml: No changes required. All existing cron job definitions work without modification.
• config/initializers/sidekiq.rb: No changes required. The initialization code is compatible with both versions.

Application Code

• app/models/email_campaign.rb: No changes required. The _schedule and _unschedule methods continue to work as expected.

Tests

All existing tests pass without modification:

• spec/models/email_campaign_spec.rb (37 examples, 0 failures)
• spec/controllers/email_campaigns_controller_spec.rb

Verification Steps

To verify the upgrade was successful:

1. Check gem version:

   bundle show sidekiq-cron
   # Should output: .../sidekiq-cron-2.3.1

2. Run tests:

   bundle exec rspec spec/models/email_campaign_spec.rb

3. Verify scheduled jobs load correctly:

   bundle exec rails console
   > Sidekiq::Cron::Job.all

4. Check Sidekiq Web UI:

   • Navigate to /sidekiq/cron in your application
   • Verify all scheduled jobs are listed and active

Migration Checklist

• Verify Sidekiq version >= 6.5.0 (We had 7.1.4)
• Update Gemfile to specify sidekiq-cron ~> 2.3
• Run bundle update sidekiq-cron
• Review cron job definitions (No changes needed)
• Run test suite (All tests pass)
• Verify jobs load in console (Confirmed)
• Document breaking changes (This guide)

Recommendations for Future Jobs

When creating new cron jobs, consider using the new features:

1. Explicit Retry Configuration: Set the retry option to control retry behavior:

   job = Sidekiq::Cron::Job.new(
     name: 'my_job',
     cron: '0 * * * *',
     class: 'MyJob',
     active_job: true,
     retry: 3  # Retry up to 3 times on failure
   )

2. Namespaces for Organization: Use namespaces to group related jobs:

   job = Sidekiq::Cron::Job.new(
     name: 'import_job',
     cron: '0 * * * *',
     class: 'ImportJob',
     active_job: true,
     namespace: 'imports'  # Group import-related jobs
   )

Resources

• Sidekiq-cron GitHub Repository
• Sidekiq-cron v2.0.0 Release Notes
• fugit Documentation

Support

If you encounter issues related to scheduled jobs after this upgrade, check:

1. Redis server logs for connection issues
2. Sidekiq logs for job execution errors
3. Sidekiq Web UI (/sidekiq/cron) for job status
4. Rails logs for application-specific errors

Rollback Procedure

If you need to rollback to the previous version:

1. Update Gemfile to use the old version:

   gem 'sidekiq-cron', '~> 1.10'

2. Run bundle update:

   bundle update sidekiq-cron

3. Restart the application and Sidekiq workers

Note: Rolling back is not recommended as version 2.x is actively maintained and includes security updates.