Welcome to the SQS page at RubyForge

This page was updated 2008-07-01:

This library is not compatible with the most recent version of the SQS API. If you want to use API v. 2008-01-01 and not 2007-05-01, then please use a different library, like RightScale's right_aws. Given the availability of other Ruby libraries, and the constraints on my time, it doesn't make sense for me to continue development on SQS right now. If you would like to take this project over, let me know.

This page was updated 2007-07-18
This page was updated 2007-06-12

Introduction
Project Page
Copyright
Installation
Tests
Usage
Source
Bugs
Contact

Introduction

SQS is a Ruby interface to Amazon's Simple Queue Service, a distributed, highly available queue. To avoid confusion, this document refers to the Ruby interface as 'SQS' and to the web service as 'ASQS.'

Project Page

http://rubyforge.org/projects/sqs/

Copyright

Installation

gem install SQS or sudo gem install SQS

Tests

If you want to run the unit tests, you will need to edit the test/unit/test_setup.rb file in your gem installation. Once those settings are correct, you can gem check -t SQS
or ruby test/all_tests.rb
Note that SQS allows you to specify whether to make live calls to ASQS. At last count, there were roughly 250 560 calls to ASQS in the unit tests. Choosing not to make live calls, then, would save you $0.025 $0.056 (plus the bandwidth costs) each time you run the unit tests.

Note that the tests require the assert_statistically gem. However, the rest of the library does not—while you won't be able to run the tests without assert_statistically, you should be able to use the library proper just fine.

Usage

Once you've installed the gem, you can do the following:

require 'rubygems'
require 'sqs'

SQS.access_key_id = 'YOURACCESSKEYID'
SQS.secret_access_key = 'YOURSECRETACCESSKEY'

q = SQS.create_queue 'myFantasticQ'
puts q.url

SQS.each_queue do |q|
  puts q.name
end

q = SQS.get_queue 'myFantasticQ'

q.send_message 'This is a message!'

m = q.receive_message
puts m.body
m.delete

q.each_message do |m|
  # note that #each_message is an infinite loop!
  # you must either break out of it, or delete each message you receive
  m.delete
end

q.approximate_number_of_messages
q.visibility_timeout
q.visibiltit_timeout = 3

q.delete

Note that SQS will raise an exception (through version 0.1.4, all exceptions raised by SQS are RuntimeErrors; since version 0.1.5, each exception is an SQS::[AWSErrorCode]) upon any response status from ASQS other than 'Success.'

SQS.add_reasons_to_retry( 'MonkeyInTheSystem', 'TheSystemIsDown' )
SQS.remove_reasons_to_retry( 'ServiceUnavailable' )
SQS.retry_attempts = 42

Since version 0.1.5, the above snippet first adds two reasons to retry a failed call to the web service. Then it removes one reason to retry. Finally, it sets the number of times to retry to 42. Note that if every attempt fails, there will have been 43 attempts (attempt plus 42 retries).

Furthermore, note that out of the box, the number of retries is 10, and 'ServiceUnavailable' errors will prompt a retry, as recommended in this thread: http://developer.amazonwebservices.com/connect/thread.jspa?messageID=56888&#56888