redis-rb
A Ruby client that tries to match Redis‘ API one-to-one, while still providing an idiomatic interface.
See RubyDoc.info for the API docs of the latest published gem.
Getting started
Install with:
“ gem install redis
“
You can connect to Redis by instantiating the Redis
class:
“by 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:
“by redis = Redis.new(host: “10.0.1.1”, port: 6380, db: 15)
“
You can also specify connection options as a redis://
URL:
“by 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)
).
To connect to Redis listening on a Unix socket, try:
“by redis = Redis.new(path: “/tmp/redis.sock”)
“
To connect to a password protected Redis instance, use:
“by redis = Redis.new(password: “mysecret”)
“
To connect a Redis instance using ACL, use:
“by 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:
“by redis.set(“mykey”, “hello world”)
=> “OK”
redis.get(“mykey”)
=> “hello world”
“
All commands, their arguments, and return values are documented and available on RubyDoc.info.
Connection Pooling and Thread safety
The client does not provide connection pooling. Each Redis
instance has one and only one connection to the server, and use of this connection is protected by a mutex.
As such it is heavilly recommended to use the connection_pool
gem, e.g.:
“by module MyApp def self.redis @redis ||= ConnectionPool::Wrapper.new do Redis.new(url: ENV[REDIS_URL]) end end end
MyApp.redis.incr(“some-counter”)
“
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:
“by SENTINELS = [{ host: 127.0.0.1, port: 26380 }, { host: 127.0.0.1, port: 26381 }]
redis = Redis.new(name: “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
andslave
. When the role isslave
, 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.
To authenticate Sentinel itself, you can specify the sentinel_username
and sentinel_password
. Exclude the sentinel_username
option if you’re using password-only authentication.
“by SENTINELS = [{ host: 127.0.0.1, port: 26380}, { host: 127.0.0.1, port: 26381}]
redis = Redis.new(name: ‘mymaster’, sentinels: SENTINELS, sentinel_username: ‘appuser’, sentinel_password: ‘mysecret’, role: :master)
“
If you specify a username and/or password at the top level for your main Redis instance, Sentinel will not using thouse credentials
“by
Use ‘mysecret’ to authenticate against the mymaster instance, but skip authentication for the sentinels:
SENTINELS = [{ host: 127.0.0.1, port: 26380 }, { host: 127.0.0.1, port: 26381 }]
redis = Redis.new(name: ‘mymaster’, sentinels: SENTINELS, role: :master, password: ‘mysecret’)
“
So you have to provide Sentinel credential and Redis explictly even they are the same
“by
Use ‘mysecret’ to authenticate against the mymaster instance and sentinel
SENTINELS = [{ host: 127.0.0.1, port: 26380 }, { host: 127.0.0.1, port: 26381 }]
redis = Redis.new(name: ‘mymaster’, sentinels: SENTINELS, role: :master, password: ‘mysecret’, sentinel_password: ‘mysecret’)
“
Also the name
, password
, username
and db
for Redis instance can be passed as an url:
“by redis = Redis.new(url: “redis://appuser:mysecret@mymaster/10”, sentinels: SENTINELS, role: :master)
“
Cluster support
Clustering. is supported via the redis-clustering
gem.
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.
“by redis.pipelined do |pipeline| pipeline.set “foo”, “bar” pipeline.incr “baz” end
=> [OK, 1]
“
Commands must be called on the yielded objects. If you call methods on the original client objects from inside a pipeline, they will be sent immediately:
“by redis.pipelined do |pipeline| pipeline.set “foo”, “bar” redis.incr “baz” # => 1 end
=> [OK]
“
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.
“by redis.multi do |transaction| transaction.set “foo”, “bar” transaction.incr “baz” end
=> [OK, 1]
“
Futures
Replies to commands in a pipeline can be accessed via the futures they emit. All calls on the pipeline object 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.
“by set = incr = nil redis.pipelined do |pipeline| set = pipeline.set “foo”, “bar” incr = pipeline.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.
“by begin redis.ping rescue Redis::BaseError => 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:
“by Redis.new(:timeout => 1)
“
But you can use specific values for each of them:
- “by
- 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:
“by 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
By default, this gem will only retry a connection once and then fail, but the client allows you to configure how many reconnect_attempts
it should complete before declaring a connection as failed.
“by Redis.new(reconnect_attempts: 0) Redis.new(reconnect_attempts: 3)
“
If you wish to wait between reconnection attempts, you can instead pass a list of durations:
“by Redis.new(reconnect_attempts: [0, # retry immediately 0.25, # retry a second time after 250ms 1, # retry a third and final time after another 1s])
“
If you wish to disable reconnection only for some commands, you can use disable_reconnection
:
“by redis.get(“some-key”) # this may be retried redis.disable_reconnection do redis.incr(“some-counter”) # this won’t be retried. end
“
SSL/TLS Support
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:
- “by
- redis = Redis.new(
- url => “rediss://:[email protected]:6381/15”,
- ssl_params =>
:ca_file => "/path/to/ca.crt"
)
“
The options given to :ssl_params
are passed directly to the OpenSSL::SSL::SSLContext#set_params
method and can be any valid attribute of the SSL context. Please see the OpenSSL::SSL::SSLContext documentation for all of the available attributes.
Here is an example of passing in params that can be used for SSL client certificate authentication (a.k.a. mutual TLS):
- “by
- 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"))
)
“
Expert-Mode Options
-
inherit_socket: true
: disable safety check that prevents a forked child from sharing a socket with its parent; this is potentially useful in order to mitigate connection churn when: - many short-lived forked children of one process need to talk to redis, AND - your own code prevents the parent process from using the redis connection while a child is aliveImproper use of
inherit_socket
will result in corrupted and/or incorrect responses.
hiredis binding
By default, redis-rb uses Ruby’s socket library to talk with Redis.
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-client
:
“by gem “redis” gem “hiredis-client”
“
If your application doesn’t call Bundler.require
, you may have to require it explictly:
“by require “hiredis-client”
“
This makes the hiredis driver the default.
If you want to be certain hiredis is being used, when instantiating the client object, specify hiredis:
“by redis = Redis.new(driver: :hiredis)
“
Testing
This library is tested against recent Ruby and Redis versions. Check Github Actions for the exact versions supported.
See Also
- async-redis — An async compatible Redis client.
Contributors
Several people contributed to redis-rb, but we would like to especially mention Ezra Zygmuntowicz. Ezra introduced the Ruby community to many new cool technologies, like Redis. He wrote the first version of this client and evangelized Redis in Rubyland. Thank you, Ezra.
Contributing
Fork the project and send pull requests.