CloudAMQP with Ruby Getting started

Ruby Client Libraries

Ruby developers have several options for AMQP client libraries:

  • AMQP::Client - CloudAMQP’s official high-level client with automatic reconnection, message encoding, and RPC support. Fast, modern, and zero dependencies.

  • Bunny - A well-established synchronous client with a large user base.

  • March Hare - An idiomatic JRuby client built on the RabbitMQ Java client.

  • Kicks - A high-performance background job processing framework.

AMQP::Client

AMQP::Client is CloudAMQP’s official Ruby client. It provides a high-level API with automatic connection management, built-in message encoding/decoding, RPC patterns, and excellent performance. It’s the recommended choice for new Ruby projects.

Installation

$ bundle init && bundle add amqp-client

Publishing Messages

Create a file named publish.rb:

require "amqp-client"

# Connect to CloudAMQP
client = AMQP::Client.new(ENV.fetch("CLOUDAMQP_URL")).start

# Publish a message
client.queue("my_queue").publish("Hello World")

puts "Message published"

Consuming Messages

Create a file named subscribe.rb:

require "amqp-client"

# Connect to CloudAMQP
client = AMQP::Client.new(ENV.fetch("CLOUDAMQP_URL")).start

# Consume messages
puts "[*] Waiting for messages. To exit press CTRL+C"
client.queue("my_queue").subscribe do |msg|
  puts "[x] Received: #{msg.body}"
end

sleep

Running the Application

In separate terminal windows, run:

# Terminal 1
$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby subscribe.rb
[*] Waiting for messages. To exit press CTRL+C

# Terminal 2
$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby publish.rb
Message published

Expected output in Terminal 1:

[x] Received: Hello World

Advanced Features

The high-level API includes built-in support for:

  • Automatic message encoding/decoding (JSON, gzip, deflate)

  • RPC client/server patterns

  • Automatic error handling and message acknowledgment

  • Connection pooling and thread-safety

See the GitHub repository for complete documentation. For advanced use cases, a low-level API is also available.

Bunny

Bunny is a popular synchronous AMQP client with a large community. It’s a solid choice if you prefer explicit control over connections and channels.

Installation

$ bundle init && bundle add logger bunny

Publishing Messages

Create a file named publish.rb:

require "bunny"

connection = Bunny.new(ENV.fetch("CLOUDAMQP_URL"), verify_peer: true)
connection.start
channel = connection.create_channel
queue = channel.queue("bunny_queue")

# Publish a message
channel.default_exchange.publish("Hello everybody!", routing_key: queue.name)

connection.close

Consuming Messages

Create a file named subscribe.rb:

require "bunny"

connection = Bunny.new(ENV.fetch("CLOUDAMQP_URL"), verify_peer: true)
connection.start
channel = connection.create_channel
queue = channel.queue("bunny_queue")

begin
  puts "[*] Waiting for messages. To exit press CTRL+C"
  queue.subscribe(block: true) do |_delivery_info, _properties, body|
    puts "[x] Received: #{body}"
  end
rescue Interrupt
  connection.close
  exit(0)
end

Running the Application

In separate terminal windows, run:

# Terminal 1
$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby subscribe.rb
[*] Waiting for messages. To exit press CTRL+C

# Terminal 2
$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby publish.rb

Expected output in Terminal 1:

[x] Received: Hello everybody!

For more information, see the Bunny documentation guides.

March Hare

March Hare is an idiomatic JRuby DSL built on top of the RabbitMQ Java client. It’s the recommended choice for JRuby applications.

Prerequisites

Make sure you have JRuby 9.x or later installed:

$ rvm install jruby

Installation

$ bundle init && bundle add logger march_hare

Publishing Messages

Create a file named publish.rb:

require "march_hare"

connection = MarchHare.connect(uri: ENV.fetch("CLOUDAMQP_URL"))
channel = connection.create_channel
queue = channel.queue("hare_queue")

# Publish a message
channel.default_exchange.publish("Hello Hare!", routing_key: queue.name)

connection.close

Consuming Messages

Create a file named subscribe.rb:

require "march_hare"

connection = MarchHare.connect(uri: ENV.fetch("CLOUDAMQP_URL"))
channel = connection.create_channel
queue = channel.queue("hare_queue")

begin
  puts "[*] Waiting for messages. To exit press CTRL+C"
  queue.subscribe do |metadata, payload|
    puts "[x] Received: #{payload}"
  end
  sleep
rescue Interrupt
  connection.close
  exit(0)
end

Running the Application

In separate terminal windows, run:

# Terminal 1
$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby subscribe.rb
[*] Waiting for messages. To exit press CTRL+C

# Terminal 2
$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby publish.rb

Expected output in Terminal 1:

[x] Received: Hello Hare!

For more information, visit rubymarchhare.info.

Kicks

Kicks (previously named Sneakers) is a high-performance background job processing framework built on RabbitMQ. It’s ideal for building worker-based architectures.

Installation

$ bundle init && bundle add kicks

Creating a Worker

Create a file named kicks_app.rb:

require "sneakers"
require "sneakers/runner"

class MessageProcessor
  include Sneakers::Worker
  from_queue "my_queue"

  def work(msg)
    puts "Processing: #{msg}"
    ack!
  end
end

Sneakers.configure(
  amqp: ENV.fetch("CLOUDAMQP_URL"),
  exchange: "sneakers",
  exchange_type: :direct
)

Sneakers::Runner.new([MessageProcessor]).run

Running the Worker

$ export CLOUDAMQP_URL=amqps://user:pass@change-me.rmq.cloudamqp.com/user
$ bundle exec ruby kicks_app.rb

The worker will create a queue named my_queue and wait for messages. You can publish messages through the RabbitMQ management console or using any AMQP client.

Video Tutorial

Watch this video tutorial showing how to set up a CloudAMQP instance and connect using Ruby:

Additional Resources