Raq Build Status Dependency Status Code Climate

Raq makes it easy to create durable message queue consumers. It tries to learn from Thin and Rack in order to provide a reasonably familiar way of creating and running AMQP consumers.

Raq expresses the opinion that, like database configuration, queue configuration should handled by the environment. Raq offers the ability to specify message broker connection information and queue names as command line flags, or in a separate configuration file.


Add this to your Gemfile:

gem 'raq'

Then install it by running Bundler:

$ bundle


Raq provides a Rack-like api for creating consumers and message middleware by implementing run and use.

However, unlike Rack, Raq does not infer anything about the payload. It exposes the protocol level meta information, and the unmodified payload body directly as arguments to your consumers. Though, you can quickly chain together middleware to satisfy your application.

Consider this example.rb:

require 'raq'

class Echo < Struct.new(:app)
  def call(meta, payload)
    puts "Echo: #{payload}"

runner = Raq::Runner.new(ARGV)
server = Raq::Server.new(
  connection: runner.connection_options,
  queues: runner.options[:queue]) do

  use Echo

  run do |meta, payload|
    puts "Acknowledging #{payload}"

    # Not for long lived processes...
    server.connection.close { EM.stop }


When run like so:

$ ruby example.rb --queue a.queue.with.messages

It will print the payload to stdout a couple times, acknowledge the message, and exit.


You can choose to configure Raq with either commandline flags or a configuration file. The configuration file is a simple YAML file. The keys should be the same as the long form commandline flags.

For example, consider this sample.yml:

queue: RabbitEmergencyRoom

When you run the above example.rb like so:

$ ruby example.rb --config sample.yml

It will connect to the RabbitEmergencyRoom queue!

Contributing to Raq

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
  • Fork the project.
  • Start a feature/bugfix branch.
  • Commit and push until you are happy with your contribution.
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright (c) 2013 Caleb Buxton. See LICENSE.txt for further details.