[Awesome Ruby Gem] Use hredis-rb gem to wrap redis-rb gem to manipulate Redis

hredis-rb

Ruby extension that wraps hiredis. Both the synchronous connection API and a separate protocol reader are supported. It is primarily intended to speed up parsing multi bulk replies.

Hiredis is a minimalistic C client library for the Redis database.

It is minimalistic because it just adds minimal support for the protocol, but at the same time it uses a high level printf-alike API in order to make it much higher level than otherwise suggested by its minimal code base and the lack of explicit bindings for every Redis command.

Apart from supporting sending commands and receiving replies, it comes with a reply parser that is decoupled from the I/O layer. It is a stream parser designed for easy reusability, which can for instance be used in higher level language bindings for efficient reply parsing.

Hiredis only supports the binary-safe Redis protocol, so you can use it with any Redis version >= 1.2.0.

The library comes with multiple APIs. There is the synchronous API, the asynchronous API and the reply parsing API.

Installation

You can install it as a gem:

$ gem install hiredis

or add it into a Gemfile (Bundler):

# Gemfile

# redis/hiredis-rb: Ruby wrapper for hiredis
# https://github.com/redis/hiredis-rb
gem 'hiredis', '0.6.3'

# GitHub - redis/redis-rb: A Ruby client library for Redis
# https://github.com/redis/redis-rb
gem 'redis', '4.0.3'

Then, run bundle install.

$ bundle install

Usages

Hiredis can be used as standalone library, or be used together with redis-rb. The latter adds in support for hiredis in 2.2.

redis-rb

To use hiredis from redis-rb, it needs to be available in Ruby’s load path. Using Bundler, this comes down to adding the following lines:

gem "hiredis", "~> 0.6.0"
gem "redis", ">= 3.2.0"

To use hiredis with redis-rb, you need to require redis/connection/hiredis before creating a new connection. This makes sure that hiredis will be used instead of the pure Ruby connection code and protocol parser. Doing so in the Gemfile is done by adding a :require option to the line adding the redis-rb dependency:

gem "redis", ">= 3.2.0", :require => ["redis", "redis/connection/hiredis"]

You can use Redis normally, as you would with the pure Ruby version.

Standalone: Connection

A connection to Redis can be opened by creating an instance of Hiredis::Connection and calling #connect:

conn = Hiredis::Connection.new
conn.connect("127.0.0.1", 6379)

Commands can be written to Redis by calling #write with an array of arguments. You can call write more than once, resulting in a pipeline of commands.

conn.write ["SET", "speed", "awesome"]
conn.write ["GET", "speed"]

After commands are written, use #read to receive the subsequent replies. Make sure not to call #read more than you have replies to read, or the connection will block indefinitely. You can use this feature to implement a subscriber (for Redis Pub/Sub).

>> conn.read
=> "OK"

>> conn.read
=> "awesome"

When the connection was closed by the server, an error of the type Hiredis::Connection::EOFError will be raised. For all I/O related errors, the Ruby built-in Errno::XYZ errors will be raised. All other errors (such as a protocol error) result in a RuntimeError.

You can skip loading everything and just load Hiredis::Connection by requiring hiredis/connection.

Standalone: Reply parser

Only using hiredis for the reply parser can be very useful in scenarios where the I/O is already handled by another component (such as EventMachine).

You can skip loading everything and just load Hiredis::Reader by requiring hiredis/reader.

Use #feed on an instance of Hiredis::Reader to feed the stream parser with new data. Use #read to get the parsed replies one by one:

>> reader = Hiredis::Reader.new
>> reader.feed("*2\r\n$7\r\nawesome\r\n$5\r\narray\r\n")
>> reader.gets
=> ["awesome", "array"]

References

[1] redis/hiredis-rb: Ruby wrapper for hiredis - https://github.com/redis/hiredis-rb

[2] hiredis | RubyGems.org | your community gem host - https://rubygems.org/gems/hiredis/

[3] redis/hiredis: Minimalistic C client for Redis >= 1.2 - https://github.com/redis/hiredis

[4] Redis - https://redis.io/