amqp gem 0.8 migration guide

This Documentation Has Moved to rubyamqp.info

amqp gem documentation guides are now hosted on rubyamqp.info.

About this guide

This guide explains how (and why) applications that use amqp gem versions 0.6.x and 0.7.x should migrate to 0.8.0.RCs and future versions. It also outlines deprecated features, when and why they will be removed.

This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.

Covered versions

This guide covers Ruby amqp gem v0.6.x and v0.7.×.

Brief history of amqp gem

amqp gem was born in early July 2008. Since then, it has seen 7 releases, used by all kinds of companies, have been key component to systems that process more than 100 gigabytes of data per day and, despite not being a “1.0 library”, proven to be very usable.

For the most part of 2008 and 2009 the gem did not receive much of attention. In 2010, some other AMQP clients (for example, RabbitMQ Java & .NET clients) switched to AMQP 0.9.1 specification. By the fall of 2010 it became clear that amqp gem needs a new team of maintainers, deep refactoring, new solid test suite and extensive documentation guides. Long story short, by December 2010, the new maintainers group was formed and now maintains number of other libraries in the Ruby AMQP ecosystem, most notably the Bunny gem.

Over first few months of 2011, amqp gem undergone a number of maintenance releases (known as 0.7.x series), a ground up rewrite of the test suite, major documentation update as well as a major refactoring. It was upgraded to AMQP 0.9.1 specification and based on a new, much more efficient AMQP serialization library, amq-protocol.

As part of this transition, amqp gem maintainers team pursued a number of goals:

  • Implement AMQP 0.9.1 spec plus all the RabbitMQ extensions
  • End “300 of 1 patch forks” situation that had gotten especially bad in early 2010
  • Produce a solid end-to-end test suite that imitates real asynchronous applications
  • Resolve many API usability issues: inconsistent behavior, weird class and method naming, heavy reliance on implicit connection objects and so on
  • Produce documentation guides that other AMQP client users will be envious of
  • Define a stable public API
  • Improve memory efficiency and performance
  • Resolve many limitations of the original API and implementation design
  • Drop all the “experimental-stuff-that-was-never-finished”

In the end, several projects like evented-spec were born and became part of the amqp gem family of libraries. “300 one patch forks” hell is a thing of the past. Even initial pure Ruby implementation of the new serialization library is several times as memory efficient. Documentation guides response if very positive. amqp gem 0.8.0.RCs implement all but 1 RabbitMQ extensions as well as AMQP 0.9.1 spec features original gem never implemented fully. Many large users of the gem upgraded to 0.8.0.RCs. The future for amqp gem and its spin-offs is bright.

amqp gem 0.8.0 backwards compatibility policy

amqp gem 0.8.0 is not 100% backwards compatible. That said, for most applications, upgrade path will be easy. Over 90% of the deprecated API classes & methods are still in place and will only be dropped in the 0.9.0 release.

Plenty of incompatibilities between 0.6.x and 0.7.x series were ironed out in 0.8.0.RCs. Finally, this guide will explain what has changed, why, why it is the right thing to do and how you should adapt your application code.

Why developers should upgrade to 0.8.0

  • Great documentation
  • amqp gem 0.8.0 RCs and later versions are actively maintained
  • Largest library users either already switched to amqp gem 0.8.0 RCs or are switching in the near future (2011)
  • AMQP 0.9.1 spec implementation: many other popular clients, for example the RabbitMQ Java client, has dropped support for AMQP 0.8 specification
  • RabbitMQ extensions
  • Several AMQP brokers, including RabbitMQ (by far the most popular from the maintainers team observation), are planning to drop AMQP 0.8 spec support
  • Applications that do not use depricated API features & behaviors will have very seamless upgrade path to the amqp gem 0.9.0 and beyond

AMQP protocol version change

amqp gem before 0.8.0 (0.6.x, 0.7.x) series implemented (most of) AMQP 0.8 specification. amqp gem 0.8.0 implements AMQP 0.9.1 and thus requires RabbitMQ version 2.0 or later. See RabbitMQ versions for more information about RabbitMQ versions support and how obtain up-todate packages for your operating system.

amqp gem 0.8.0 and later versions implement AMQP 0.9.1 and thus requires RabbitMQ version 2.0 or later

Follow established AMQP terminology

require “mq” is deprecated

Instead of the following:


require "amqp"
require "mq"

or


require "mq"

switch to


require "amqp"

mq.rb will be removed before 1.0 release.

MQ class is deprecated

Please use AMQP::Channel instead. MQ class & its methods are implemented in amqp gem 0.8.x for backwards compatibility, but only for transition period (that will end after 0.9 release).

Why is it deprecated? Because it was a poor name choice all along. Both mq.rb and MQ class step away from AMQP terminology and make 8 out of 10 engineers think it has something to do with AMQP queues (in fact, MQ should have been called Channel all along). No other AMQP client library we know of invents its own terminology when it comes to AMQP entities, and amqp gem shouldn’t, too.

MQ class and class methods that use implicit connection (MQ.queue and so on) will be removed before 1.0 release.

MQ class is now AMQP::Channel

MQ class was renamed to AMQP::Channel to follow established AMQP 0.9.1 terminology. Implicit per-thread channels are deprecated so code like this:


# amqp gem 0.6.x code style: connection is implicit, channel is implicit. Error handling & recovery are thus
# not possible.
# Deprecated, do not use.
MQ.queue("search.indexing")

# same for exchanges. Deprecated, do not use.
MQ.direct("services.imaging")
MQ.fanout("services.broadcast")
MQ.topic("services.weather_updates")


# connection object lets you define error handlers
connection = AMQP.connect(:vhost => "myapp/production", :host => "192.168.0.18")
# channek object lets you define error handlers and use multiple channels per application,
# for example, one per thread
channel    = AMQP::Channel.new(connection)
# AMQP::Channel#queue has unchanged otherwise
channel.queue("search.indexing")

# exchanges examples
channel.direct("services.imaging")
channel.fanout("services.broadcast")
channel.topic("services.weather_updates")

MQ.queue, MQ.direct, MQ.fanout and MQ.topic methods will be removed before 1.0 release. Use instance methods on AMQP::Channel (AMQP::Channel#queue, AMQP::Channel#direct, AMQP::Channel#default_exchange and so on) instead.

MQ::Queue is now AMQP::Queue

MQ::Queue is now AMQP::Queue. All the methods from 0.6.x series are still available.

MQ::Queue alias will be removed before 1.0 release. Please switch to AMQP::Queue.

MQ::Exchange is now AMQP::Exchange

MQ::Exchange is now AMQP::Exchange. All the methods from 0.6.x series are still available.

MQ::Exchange alias will be removed before 1.0 release. Please switch to AMQP::Exchange.

MQ::Header is now AMQP::Header

MQ::Header is now AMQP::Header. If you code has any type checks or case matches on MQ::Header, it needs to change to AMQP::Header.

AMQP.error is deprecated

Catch-all solutions for error handling are very difficult to use. Automatic recovery and fine-grained event handling is also not possible. amqp gem 0.8.0.RC14 and later includes fine-grained Error Handling and Recovery API that is both significantly easier to use in real-world cases but also makes automatic recovery mode possible.

AMQP.error method will be removed before 1.0 release.

MQ::RPC is deprecated

It was an experiment that was never finished. Some API design choices are very opinionated as well. amqp gem should not ship with half-baked poorly designed or overly opinionated solutions.

MQ::RPC class will be removed before 1.0 release.

MQ::Logger is removed

It was an experiment that was never finished. Some API design choices are very opinionated as well. amqp gem should not ship with half-baked poorly designed or overly opinionated solutions.

MQ::Logger class was removed in the the amqp gem 0.8.0 development cycle.

AMQP::Buffer is removed

AMQP::Buffer was AMQP 0.8 protocol implementation detail. With the new amq-protocol gem, it is no longer relevant.

AMQP::Buffer class was removed in the the amqp gem 0.8.0 development cycle.

AMQP::Frame is removed

AMQP::Frame was AMQP 0.8 protocol implementation detail. With the new amq-protocol gem, it is no longer relevant.

AMQP::Frame class was removed in the the amqp gem 0.8.0 development cycle.

AMQP::Server is removed

AMQP::Server was (an unfinished) toy implementation of AMQP 0.8 broker in Ruby on top of EventMachine. We believe that Ruby is not an optimal choice for AMQP broker implementations. We also never heard from anyone using it.

AMQP::Server class was removed in the the amqp gem 0.8.0 development cycle.

AMQP::Protocol::* classes are removed

AMQP::Protocol::* classes were AMQP 0.8 protocol implementation detail. With the new amq-protocol gem, they are no longer relevant.

AMQP::Protocol::* classes were removed in the the amqp gem 0.8.0 development cycle.

Authors

This guide was written by Michael Klishin and edited by Chris Duncan.

Tell us what you think!

Please take a moment and tell us what you think about this guide on Twitter or Ruby AMQP mailing list: what was unclear? what wasn’t covered? maybe you don’t like guide style or grammar and spelling are incorrect? Readers feedback is key to making documentation better.

If mailing list communication is not an option for you for some reason, you can contact guides author directly