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

Posted on Edited on In , , Views: Word count in article: 10k Reading time ≈ 9 mins.

redis-rb

A Ruby client that tries to match Redis’ API one-to-one, while still providing an idiomatic interface.

Installation

You can install it as a gem:

1
$ gem install redis

or add it into a Gemfile (Bundler):

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

Then, run bundle install.

1
$ bundle install

Usages

You can connect to Redis by instantiating the Redis class:

1
2
3
require "redis"

redis = Redis.new

This assumes Redis was started with a default configuration, and is listening on localhost, port 6379. If you need to connect to a remote server or a different port, try:

1
redis = Redis.new(host: "10.0.1.1", port: 6380, db: 15)

You can also specify connection options as a redis:// URL:

1
redis = Redis.new(url: "redis://:[email protected]:6380/15")

The client expects passwords with special chracters to be URL-encoded (i.e. CGI.escape(password)).

By default, the client will try to read the REDIS_URL environment variable and use that as URL to connect to. The above statement is therefore equivalent to setting this environment variable and calling Redis.new without arguments.

To connect to Redis listening on a Unix socket, try:

1
redis = Redis.new(path: "/tmp/redis.sock")

To connect to a password protected Redis instance, use:

1
redis = Redis.new(password: "mysecret")

To connect a Redis instance using ACL, use:

1
redis = Redis.new(username: 'myname', password: 'mysecret')

The Redis class exports methods that are named identical to the commands they execute. The arguments these methods accept are often identical to the arguments specified on the Redis website. For instance, the SET and GET commands can be called like this:

1
2
3
4
5
redis.set("mykey", "hello world")
# => "OK"

redis.get("mykey")
# => "hello world"

All commands, their arguments, and return values are documented and available on File: README — Documentation for redis (4.2.5) - https://www.rubydoc.info/gems/redis.

Sentinel support

The client is able to perform automatic failover by using Redis Sentinel. Make sure to run Redis 2.8+ if you want to use this feature.

To connect using Sentinel, use:

1
2
3
4
SENTINELS = [{ host: "127.0.0.1", port: 26380 },
             { host: "127.0.0.1", port: 26381 }]

redis = Redis.new(url: "redis://mymaster", sentinels: SENTINELS, role: :master)

  • The master name identifies a group of Redis instances composed of a master and one or more slaves (mymaster in the example).

  • It is possible to optionally provide a role. The allowed roles are master and slave. When the role is slave, the client will try to connect to a random slave of the specified master. If a role is not specified, the client will connect to the master.

  • When using the Sentinel support you need to specify a list of sentinels to connect to. The list does not need to enumerate all your Sentinel instances, but a few so that if one is down the client will try the next one. The client is able to remember the last Sentinel that was able to reply correctly and will use it for the next requests.

If you want to authenticate Sentinel itself, you must specify the password option per instance.

1
2
3
4
SENTINELS = [{ host: '127.0.0.1', port: 26380, password: 'mysecret' },
             { host: '127.0.0.1', port: 26381, password: 'mysecret' }]

redis = Redis.new(host: 'mymaster', sentinels: SENTINELS, role: :master)

Cluster support

redis-rb supports clustering.

1
2
3
4
5
6
# Nodes can be passed to the client as an array of connection URLs.
nodes = (7000..7005).map { |port| "redis://127.0.0.1:#{port}" }
redis = Redis.new(cluster: nodes)

# You can also specify the options as a Hash. The options are the same as for a single server connection.
(7000..7005).map { |port| { host: '127.0.0.1', port: port } }

You can also specify only a subset of the nodes, and the client will discover the missing ones using the CLUSTER NODES command.

1
Redis.new(cluster: %w[redis://127.0.0.1:7000])

If you want the connection to be able to read from any replica, you must pass the replica: true. Note that this connection won’t be usable to write keys.

1
Redis.new(cluster: nodes, replica: true)

The calling code is responsible for avoiding cross slot commands.

1
2
3
4
5
6
7
redis = Redis.new(cluster: %w[redis://127.0.0.1:7000])

redis.mget('key1', 'key2')
#=> Redis::CommandError (CROSSSLOT Keys in request don't hash to the same slot)

redis.mget('{key}1', '{key}2')
#=> [nil, nil]

  • The client automatically reconnects after a failover occurred, but the caller is responsible for handling errors while it is happening.

  • The client support permanent node failures, and will reroute requests to promoted slaves.

  • The client supports MOVED and ASK redirections transparently.

Storing objects

Redis “string” types can be used to store serialized Ruby objects, for example with JSON:

1
2
3
4
5
6
7
require "json"

redis.set "foo", [1, 2, 3].to_json
# => OK

JSON.parse(redis.get("foo"))
# => [1, 2, 3]

Pipelining

When multiple commands are executed sequentially, but are not dependent, the calls can be pipelined. This means that the client doesn’t wait for reply of the first command before sending the next command. The advantage is that multiple commands are sent at once, resulting in faster overall execution.

The client can be instructed to pipeline commands by using the #pipelined method. After the block is executed, the client sends all commands to Redis and gathers their replies. These replies are returned by the #pipelined method.

1
2
3
4
5
redis.pipelined do
  redis.set "foo", "bar"
  redis.incr "baz"
end
# => ["OK", 1]

Executing commands atomically

You can use MULTI/EXEC to run a number of commands in an atomic fashion. This is similar to executing a pipeline, but the commands are preceded by a call to MULTI, and followed by a call to EXEC. Like the regular pipeline, the replies to the commands are returned by the #multi method.

1
2
3
4
5
redis.multi do
  redis.set "foo", "bar"
  redis.incr "baz"
end
# => ["OK", 1]

Futures

Replies to commands in a pipeline can be accessed via the futures they emit (since redis-rb 3.0). All calls inside a pipeline block return a Future object, which responds to the #value method. When the pipeline has successfully executed, all futures are assigned their respective replies and can be used.

1
2
3
4
5
6
7
8
9
10
redis.pipelined do
  @set = redis.set "foo", "bar"
  @incr = redis.incr "baz"
end

@set.value
# => "OK"

@incr.value
# => 1

Error Handling

In general, if something goes wrong you’ll get an exception. For example, if it can’t connect to the server a Redis::CannotConnectError error will be raised.

1
2
3
4
5
6
7
8
9
begin
  redis.ping
rescue StandardError => e
  e.inspect
# => #<Redis::CannotConnectError: Timed out connecting to Redis on 10.0.1.1:6380>

  e.message
# => Timed out connecting to Redis on 10.0.1.1:6380
end

See lib/redis/errors.rb for information about what exceptions are possible.

Timeouts

The client allows you to configure connect, read, and write timeouts. Passing a single timeout option will set all three values:

1
Redis.new(:timeout => 1)

But you can use specific values for each of them:

1
2
3
4
5
Redis.new(
  :connect_timeout => 0.2,
  :read_timeout    => 1.0,
  :write_timeout   => 0.5
)

All timeout values are specified in seconds.

When using pub/sub, you can subscribe to a channel using a timeout as well:

1
2
3
4
5
6
redis = Redis.new(reconnect_attempts: 0)
redis.subscribe_with_timeout(5, "news") do |on|
  on.message do |channel, message|
    # ...
  end
end

If no message is received after 5 seconds, the client will unsubscribe.

Reconnections

The client allows you to configure how many reconnect_attempts it should complete before declaring a connection as failed. Furthermore, you may want to control the maximum duration between reconnection attempts with reconnect_delay and reconnect_delay_max.

1
2
3
4
5
Redis.new(
  :reconnect_attempts => 10,
  :reconnect_delay => 1.5,
  :reconnect_delay_max => 10.0,
)

The delay values are specified in seconds. With the above configuration, the client would attempt 10 reconnections, exponentially increasing the duration between each attempt but it never waits longer than reconnect_delay_max.

This is the retry algorithm:

1
attempt_wait_time = [(reconnect_delay * 2**(attempt-1)), reconnect_delay_max].min

SSL/TLS Support

This library supports natively terminating client side SSL/TLS connections when talking to Redis via a server-side proxy such as stunnel, hitch, or ghostunnel.

To enable SSL support, pass the :ssl => true option when configuring the Redis client, or pass in :url => "rediss://..." (like HTTPS for Redis). You will also need to pass in an :ssl_params => { … } hash used to configure the OpenSSL::SSL::SSLContext object used for the connection:

Here is an example of passing in params that can be used for SSL client certificate authentication (a.k.a. mutual TLS):

1
2
3
4
5
6
7
8
redis = Redis.new(
  :url        => "rediss://:[email protected]:6381/15",
  :ssl_params => {
    :ca_file => "/path/to/ca.crt",
    :cert    => OpenSSL::X509::Certificate.new(File.read("client.crt")),
    :key     => OpenSSL::PKey::RSA.new(File.read("client.key"))
  }
)

NOTE: SSL is only supported by the default “Ruby” driver

Alternate drivers

By default, redis-rb uses Ruby’s socket library to talk with Redis. To use an alternative connection driver it should be specified as option when instantiating the client object. These instructions are only valid for redis-rb 3.0. For instructions on how to use alternate drivers from redis-rb 2.2, please refer to an older README.

hiredis

The hiredis driver uses the connection facility of hiredis-rb. In turn, hiredis-rb is a binding to the official hiredis client library. It optimizes for speed, at the cost of portability. Because it is a C extension, JRuby is not supported (by default).

It is best to use hiredis when you have large replies (for example: LRANGE, SMEMBERS, ZRANGE, etc.) and/or use big pipelines.

In your Gemfile, include hiredis:

1
2
gem "redis", "~> 3.0.1"
gem "hiredis", "~> 0.4.5"

When instantiating the client object, specify hiredis:

1
redis = Redis.new(:driver => :hiredis)

synchrony

The synchrony driver adds support for em-synchrony. This makes redis-rbwork with EventMachine's asynchronous I/O, while not changing the exposed API. Thehiredis` gem needs to be available as well, because the synchrony driver uses hiredis for parsing the Redis protocol.

In your Gemfile, include em-synchrony and hiredis:

1
2
3
gem "redis", "~> 3.0.1"
gem "hiredis", "~> 0.4.5"
gem "em-synchrony"

When instantiating the client object, specify synchrony:

1
redis = Redis.new(:driver => :synchrony)

References

[1] GitHub - redis/redis-rb: A Ruby client library for Redis - https://github.com/redis/redis-rb

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

[3] File: README — Documentation for redis (4.2.5) - https://www.rubydoc.info/gems/redis

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