Home

Awesome

Ruby amqp gem: the asynchronous Ruby RabbitMQ client

Ruby amqp gem is a feature-rich, EventMachine-based RabbitMQ client with batteries included.

It's the original RabbitMQ client for Ruby. These days there are very solid alternatives available: Bunny for MRI and March Hare for JRuby.

It implement AMQP 0.9.1 and support RabbitMQ extensions to AMQP 0.9.1.

A Word of Warning: Use This Only If You Already Use EventMachine

Unless you already use EventMachine, there is no real reason to use this client. Consider Bunny or March Hare instead.

amqp gem brings in a fair share of EventMachine complexity which cannot be fully eliminated. Event loop blocking, writes that happen at the end of loop tick, uncaught exceptions in event loop silently killing it: it's not worth the pain unless you've already deeply invested in EventMachine and understand how it works.

So, just use Bunny or March Hare. You will be much happier.

I know what RabbitMQ is, how do I get started?

See Getting started with amqp gem and other amqp gem documentation guides. We recommend that you read AMQP 0.9.1 Model Explained, too.

What is RabbitMQ?

RabbitMQ is an open source messaging middleware that emphasizes interoperability between different technologies (for example, Java, .NET, Ruby, Python, Node.js, Erlang, Go, C and so on).

Key features of RabbitMQ are very flexible yet simple routing and binary protocol efficiency. RabbitMQ supports many sophisticated features, for example, message acknowledgements, queue length limit, message TTL, redelivery of messages that couldn't be processed, load balancing between message consumers and so on.

What is amqp gem good for?

One can use amqp gem to make Ruby applications interoperate with other applications (both Ruby and not). Complexity and size may vary from simple work queues to complex multi-stage data processing workflows that involve dozens or hundreds of applications built with all kinds of technologies.

Specific examples:

Getting started with Ruby amqp gem

Install RabbitMQ

Please refer to the RabbitMQ installation guides. Note that for Ubuntu and Debian we strongly advice that you use the Cloudsmith apt repository that has recent versions of RabbitMQ.

Install the gem

On Microsoft Windows

gem install eventmachine
gem install amqp

On other OSes

gem install amqp

"Hello, World" example

#!/usr/bin/env ruby
# encoding: utf-8

require 'amqp'

EventMachine.run do
  connection = AMQP.connect(:host => '127.0.0.1')
  puts "Connecting to RabbitMQ. Running #{AMQP::VERSION} version of the gem..."

  ch  = AMQP::Channel.new(connection)
  q   = ch.queue("amqpgem.examples.hello_world", :auto_delete => true)
  x   = ch.default_exchange

  q.subscribe do |metadata, payload|
    puts "Received a message: #{payload}. Disconnecting..."

    connection.close {
      EventMachine.stop { exit }
    }
  end

  x.publish "Hello, world!", :routing_key => q.name
end

Getting started guide explains this and two more examples in detail, and is written in a form of a tutorial. See AMQP 0.9.1 Model Explained if you want to learn more about RabbitMQ protocol principles & concepts.

Supported Ruby Versions

Modern amqp gem release series support

The last series to support Ruby 1.9 was 1.5.x.

JRuby users should use March Hare.

Documentation: tutorials, guides & API reference

We believe that in order to be a library our users really love, we need to care about documentation as much as (or more) code readability, API beauty and autotomated testing across 5 Ruby implementations on multiple operating systems. We do care about our documentation: if you don't find your answer in documentation, we consider it a high severity bug that you should file to us. Or just complain to @rubyamqp on Twitter.

Tutorials

Getting started guide is written as a tutorial that walks you through 3 examples:

all in under 20 minutes. AMQP 0.9.1 Concepts will introduce you to protocol concepts in less than 5 minutes.

Guides

Documentation guides describe the library itself as well as AMQP concepts, usage scenarios, topics like working with exchanges and queues, error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on. Most of the documentation is in these guides.

Examples

You can find many examples (both real-world cases and simple demonstrations) under examples directory in the repository. Note that those examples are written against version 0.8.0.rc1 and later. 0.6.x and 0.7.x may not support certain AMQP protocol or "DSL syntax" features.

There is also a work-in-progress Messaging Patterns and Use Cases With AMQP documentation guide.

API reference

API reference is up on rubydoc.info and is updated daily.

How to use AMQP gem with Ruby on Rails, Sinatra and other Web frameworks

We cover Web application integration for multiple Ruby Web servers in Connecting to the broker guide.

Community

Maintainer Information

amqp gem is maintained by Michael Klishin.

Continuous Integration

Continuous Integration status

Links

License

amqp gem is licensed under the Ruby License.

Credits and copyright information

Currently maintained by ruby-amqp group members Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.

How can I learn more about RabbitMQ and messaging in general?

Documentation Resources