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:

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:

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

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

redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15")

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

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

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

To connect to a password protected Redis instance, use:

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

To connect a Redis instance using ACL, use:

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:

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.

Language and server support

redis-rb targets actively supported runtimes on both the language and the server side:

• Ruby: Ruby 3.2 and newer. See the Ruby maintenance branches page for each version's status and dates.
• Redis server: the versions designated for support by Redis. See Supported Redis database versions.

Protocol (RESP3)

Starting in 6.0, the client negotiates the RESP3 protocol (HELLO 3) by default. Command return values are unchanged from 5.x, with one exception: GEOPOS and GEOSEARCH/GEORADIUS with WITHCOORD now return coordinates as Float instead of String.

To keep the previous RESP2 behavior, pass protocol: 2:

redis = Redis.new(protocol: 2)

Servers without RESP3 support (Redis < 6.0, or anything replying NOPROTO) are detected on connect and the client transparently falls back to RESP2, so no configuration is needed for older servers.

Why RESP3 is the default

RESP3's richer wire types let the parser deliver replies already in their final Ruby shape. Under RESP2, structured replies arrive as flat arrays of bulk strings and the client re-shapes them in Ruby: HGETALL turns a flat [field, value, field, value, ...] array into a Hash, and sorted-set scores are converted from String to Float pair by pair. Under RESP3 the server tags these replies as native maps and doubles, so the final Hash and Float values come straight out of the parser and the Ruby-side re-shaping pass disappears entirely.

How much that saves depends on where parsing happens. In our benchmarks (bench/resp_comparison.rb, Ruby 3.4, 100-element replies), hash reads (HGETALL) consistently use ~10–25% less client CPU per call on both drivers. With the hiredis driver, where parsing runs in C, sorted-set reads with scores gain up to 16% throughput and ~20% less CPU per call on top of that; with the pure-Ruby driver they are unchanged, since the parser then spends in Ruby roughly what the re-shaping pass used to cost. Simple string commands and stream commands are unaffected either way — their reply shapes are the same in both protocols. In short: RESP3 is never slower where it matters, and it pairs best with hiredis — that combination moves all reply construction out of Ruby and into C.

Beyond performance, RESP3 unlocks protocol capabilities RESP2 simply doesn't have. The most important is out-of-band push messages: the server can send notifications on a connection without the client asking, which is the foundation for server-assisted client-side caching (CLIENT TRACKING invalidation events), pub/sub messages delivered over the regular command connection instead of a dedicated one, and other server-initiated notifications. Defaulting to RESP3 in 6.0 lays the groundwork for building these features in future releases without another protocol migration.

See the RESP3 migration guide for full details.

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 heavily recommended to use the connection_pool gem, e.g.:

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:

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 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 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 request.

To authenticate with Sentinel itself, you can specify the sentinel_username and sentinel_password. Exclude the sentinel_username option if you're using password-only authentication.

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 use those credentials.

# 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 credentials and Redis explicitly even if they are the same.

# 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 the Redis instance can be passed as a URL:

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

Cluster support

Clustering](https://redis.io/topics/cluster-spec). 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.

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:

redis.pipelined do |pipeline|
  pipeline.set "foo", "bar"
  redis.incr "baz" # => 1
end
# => ["OK"]

Exception management

The exception flag in the #pipelined is a feature that modifies the pipeline execution behavior. When set to false, it doesn't raise an exception when a command error occurs. Instead, it allows the pipeline to execute all commands, and any failed command will be available in the returned array. (Defaults to true)

results = redis.pipelined(exception: false) do |pipeline|
  pipeline.set('key1', 'value1')
  pipeline.lpush('key1', 'something') # This will fail
  pipeline.set('key2', 'value2')
end
# results => ["OK", #<RedisClient::WrongTypeError: WRONGTYPE Operation against a key holding the wrong kind of value>, "OK"]

results.each do |result|
  if result.is_a?(Redis::CommandError)
    # Do something with the failed result
  end
end

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.

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.

set = incr = nil
redis.pipelined do |pipeline|
  set = pipeline.set "foo", "bar"
  incr = pipeline.incr "baz"
end

set.value
# => "OK"

incr.value
# => 1

Bulk hash ingestion (HIMPORT)

Experimental: HIMPORT support is experimental. The client API (method signatures, reply aggregation on cluster, and the automatic re-prepare behavior) may change in a future minor release without a major version bump.

Redis 8.10 adds the HIMPORT command family for loading many hashes that share the same set of field names: register the field names once with himport_prepare, then create each hash by sending only its values. Keys written this way are regular hashes — every hash command works on them.

redis.himport_prepare("users", ["name", "email", "age"])
redis.himport_set("user:1", "users", ["alice", "alice@example.com", "25"])
redis.himport_set("user:2", "users", ["bob", "bob@example.com", "30"])
redis.himport_discard("users") # => 1

Values pair positionally with the prepared fields. Note that hash enumeration order (HGETALL, HKEYS) is not guaranteed to match the prepare order.

Fieldsets are connection state

A prepared fieldset lives in the server-side session of the physical connection that prepared it: it is invisible to other connections and destroyed by a disconnect or RESET. A himport_set on a connection without the fieldset fails with ERR no such fieldset.

Because a Redis instance transparently replaces a dead connection (see Reconnections), the client keeps the last schema prepared for each fieldset name and, when a himport_set reports the fieldset is gone, re-prepares it and retries the command once. Explicitly discarded fieldsets are never restored. To keep the fieldset lifecycle fully explicit instead, disable the recovery:

redis = Redis.new(himport_auto_prepare: false)

For the highest ingestion throughput, send the PREPARE and its SETs as one pipeline — a single batch always executes on a single connection:

redis.pipelined do |pipeline|
  pipeline.himport_prepare("users", ["name", "email", "age"])
  rows.each { |id, row| pipeline.himport_set("user:#{id}", "users", row) }
end

If the PREPARE in a batch fails, every SET in it fails with no such fieldset — the PREPARE error is the root cause. Note that the automatic re-prepare applies to direct calls only, not to commands inside pipelined/multi blocks.

When using the connection_pool gem, each checkout may hand you a different underlying connection: run himport_prepare and its himport_set calls within one checkout (pool.with { |redis| ... }), ideally as one pipelined block.

With ::Redis::Distributed, himport_prepare, himport_discard and himport_discard_all fan out to every ring node and return an array with one reply per node; himport_set routes by key. With Redis::Cluster, the same commands fan out to every master node and return a single aggregated reply, matching the standalone API.

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.

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. Starting in version 5.0, the default for each is 1. Before that, it was 5. Passing a single timeout option will set all three values:

Redis.new(:timeout => 1)

But you can use specific values for each of them:

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:

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.

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:

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:

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:

redis = Redis.new(
  :url        => "rediss://:p4ssw0rd@10.0.1.1: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):

redis = Redis.new(
  :url        => "rediss://:p4ssw0rd@10.0.1.1: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 alive

  Improper 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:

gem "redis"
gem "hiredis-client"

If your application doesn't call Bundler.require, you may have to require it explicitly:

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:

redis = Redis.new(driver: :hiredis)

See Also

• async-redis](https://github.com/socketry/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.