A super efficient AWS SQS thread based message processor for Ruby
Latest commit 9fbe6e2 Jan 11, 2017 @phstc committed on GitHub Merge pull request #302 from phstc/hotfix/301
Show a warn message when batch isn't supported

Fix #301



Shoryuken sho-ryu-ken is a super-efficient AWS SQS thread-based message processor.

Build Status Code Climate

Key features

Load balancing

Yeah, Shoryuken load balances the messages consumption!

Given this configuration:

concurrency: 25
delay: 25
  - [high_priority, 6]
  - [default, 2]
  - [low_priority, 1]

And supposing all the queues are full of messages, the configuration above will make Shoryuken to process high_priority 3 times more than default and 6 times more than low_priority, splitting the work among the concurrency: 25 available processors.

If high_priority gets empty, Shoryuken will keep using the 25 processors, but only to process default (2 times more than low_priority) and low_priority.

If high_priority receives a new message, Shoryuken will smoothly increase back the high_priority weight one by one until it reaches the weight of 6 again, which is the maximum configured for high_priority.

If all queues get empty, all processors will be changed to the waiting state and the queues will be checked every delay: 25. If any queue receives a new message, Shoryuken will start processing again. Check the delay option documentation for more information.

Fetch in batches

To be even more performant and cost effective, Shoryuken fetches SQS messages in batches, so a single SQS request can fetch up to 10 messages.


Ruby 2.0 or greater. Ruby 1.9 is no longer supported.


Add this line to your application's Gemfile:

gem 'shoryuken'

Or to get the latest updates:

gem 'shoryuken', github: 'phstc/shoryuken', branch: 'master'

And then execute:

$ bundle

Or install it yourself as:

$ gem install shoryuken


Worker class

class MyWorker
  include Shoryuken::Worker

  shoryuken_options queue: 'default', auto_delete: true
  # shoryuken_options queue: ->{ "#{ENV['environment']}_default" }

  # shoryuken_options body_parser: :json
  # shoryuken_options body_parser: ->(sqs_msg){ REXML::Document.new(sqs_msg.body) }
  # shoryuken_options body_parser: JSON

  def perform(sqs_msg, body)
    puts body

Check the Worker options documention.

Sending a message

Check the Sending a message documentation


class MyMiddleware
  def call(worker_instance, queue, sqs_msg, body)
    puts 'Before work'
    puts 'After work'

Check the Middleware documentation.

Configuration (worker side)

Sample configuration file shoryuken.yml.

concurrency: 25  # The number of allocated threads to process messages. Default 25
delay: 25        # The delay in seconds to pause a queue when it's empty. Default 0
  - [high_priority, 6]
  - [default, 2]
  - [low_priority, 1]

And setup aws options to use configure_client in config/initializers/shoryuken.rb:

Shoryuken.configure_client do |config|
  config.aws = {
    secret_access_key: ...,         # or ENV["AWS_SECRET_ACCESS_KEY"]
    access_key_id:     ...,         # or ENV["AWS_ACCESS_KEY_ID"]
    region:            "us-east-1", # or ENV["AWS_REGION"]
    receive_message: {              # See http://docs.aws.amazon.com/sdkforruby/api/Aws/SQS/Client.html#receive_message-instance_method
      # wait_time_seconds: N,       # The number of seconds to wait for new messages when polling. Defaults to the #wait_time_seconds defined on the queue
      attribute_names: [

If you use Shoryuken with plain ruby worker class (not Rails), please call configure_client at the beginning of the worker file:

Shoryuken.configure_client do |config|
  config.aws = {
    secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"],
    access_key_id:     ENV["AWS_ACCESS_KEY_ID"],
    region:            ENV["AWS_REGION"]

class MyWorker

The aws section is used to configure both the Aws objects used by Shoryuken internally, and also to set up some Shoryuken-specific config. The Shoryuken-specific keys are listed below, and you can expect any other key defined in that block to be passed on untouched to Aws::SQS::Client#initialize:

The sns_endpoint and sqs_endpoint Shoryuken-specific options will also fallback to the environment variables AWS_SNS_ENDPOINT and AWS_SQS_ENDPOINT respectively, if they are set.

Configuration (producer side)

'Producer' processes need permissions to put messages into SQS. There are a few ways:

  • Use the configure_server in Rails initializer
  • Ensure the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY env vars are set.
  • Create a ~/.aws/credentials file.
  • Set Aws.config[:credentials] from Ruby code (e.g. in a Rails initializer)
  • Use the Instance Profiles feature. The IAM role of the targeted machine must have an adequate SQS Policy.

For example, use the configure_server in config/initializers/shoryuken.rb:

Shoryuken.configure_client do |config|
  config.aws = {
    secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"],
    access_key_id:     ENV["AWS_ACCESS_KEY_ID"],
    region:            ENV["AWS_REGION"]

Shoryuken.configure_server do |config|
  config.aws = {
    secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"],
    access_key_id:     ENV["AWS_ACCESS_KEY_ID"],
    region:            ENV["AWS_REGION"]

Note that storing your credentials into Amazon instances represents a security risk. Instance Profiles tends to be the best choice.

You can read about these in more detail here.

Rails Integration

Check the Rails Integration Active Job documention.

Start Shoryuken

bundle exec shoryuken -r worker.rb -C shoryuken.yml

Other options:

shoryuken --help

shoryuken [options]
    -c, --concurrency INT            Processor threads to use
    -d, --daemon                     Daemonize process
    -q, --queue QUEUE[,WEIGHT]...    Queues to process with optional weights
    -r, --require [PATH|DIR]         Location of the worker
    -C, --config PATH                Path to YAML config file
    -R, --rails                      Attempts to load the containing Rails project
    -L, --logfile PATH               Path to writable logfile
    -P, --pidfile PATH               Path to pidfile
    -v, --verbose                    Print more verbose output
    -V, --version                    Print version and exit
    -h, --help                       Show help

More Information

For more information on advanced topics such as signals (shutdown), ActiveJob integration, and so on please check the Shoryuken Wiki.


Mike Perham, creator of Sidekiq, and everybody who contributed to it. Shoryuken wouldn't exist as it is without those contributions.


  1. Fork it ( https://github.com/phstc/shoryuken/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request