redis-rb Ruby Client

The redis-rb library acts as a high-level DSL. It depends on redis-client (by Shopify) for RESP parsing, socket management, and pipelines.

If you are using redis-clustering, note that it depends on redis (the main gem) and is pinned to the exact same version. redis-cluster-client is a peer driver that handles cluster topology and slot routing but is unaware of the redis-rb DSL; it receives raw command arrays (e.g., ["INCR", "k"]) and routes them based on the Redis server's COMMAND introspection.

The Redis Query Engine (RediSearch, FT.* commands) is available in redis-rb through two interoperable approaches:

1. Low-level ft_* methods: These are thin wrappers around raw Redis commands (e.g., ft_search, ft_create). They are always available and represent the most current feature set. Use these when you need direct control or the highest level of fidelity to the Redis protocol.
2. High-level Abstractions: Classes like Schema, Query, Index, and AggregateRequest sit on top of the low-level methods. These builders make common tasks (like defining schemas or building complex queries) more readable and type-safe. Use these for standard workflows to improve code maintainability.

You can mix and match these approaches freely; for example, you can call ft_search with a hand-built query string and still receive a reshaped SearchResult object.

For Redis versions 7.* and newer, you can use SSL/TLS by providing rediss:// URLs.

For Redis versions prior to 6.*, if you are connecting to a single endpoint via SSL/TLS that represents the cluster, you must provide the fixed_hostname option. This prevents certificate verification failures when the cluster returns IP addresses instead of the expected FQDN.

To use Redis Cluster support in Ruby, install the redis-clustering gem via rubygems.

$ gem install redis-clustering

The client supports automatic failover via Redis Sentinel. You must provide a list of sentinels and the name of the master group. You can optionally specify a role (:master or :slave).

Important Authentication Note: If you provide a password or username at the top level, it applies to the Redis instance, NOT the sentinels. To authenticate against both, you must explicitly provide sentinel_password (and sentinel_username if applicable).

When adding commands that only exist in newer Redis versions, use the provided helpers in test/helper.rb to prevent breaking CI runs on older Redis versions.

• target_version(version): Wraps a block so it only executes if the server version is at least the specified version.
• omit_version(min_ver): Skips the entire current test if the server version is below min_ver.

def test_set_with_exat
  target_version "6.2" do
    r.set("foo", "bar", exat: Time.now.to_i + 2)
    assert_in_range 0..2, r.ttl("foo")
  end
end

def test_my_command
  omit_version("7.4")
  r.my_new_command(...)
end

Starting with version 6.0, redis-rb negotiates the RESP3 protocol (HELLO 3) by default. Most wrapped commands automatically reshape RESP3 replies to match the Ruby objects used in RESP2, ensuring backward compatibility.

Key Changes:

• GEO coordinates: GEOPOS and GEOSEARCH/GEORADIUS with WITHCOORD now return coordinates as Float instead of String.
• Raw/Unwrapped commands: Commands called via redis.call(...) or through method_missing (unwrapped) will return native RESP3 types (e.g., Hash instead of flat Array for maps, true/false instead of 1/0 for booleans) rather than the reshaped RESP2-compatible objects.

In Redis Cluster, commands involving multiple keys (like MGET, MSET, or DEL) will fail with a Redis::CommandError (CROSSSLOT Keys in request don't hash to the same slot) if the keys do not belong to the same hash slot.

To ensure multiple keys are handled in the same slot, use hash tags (e.g., {key}name). While redis-clustering provides an internal implementation to allow these commands without hash tags by preventing cross-slot errors, it is highly recommended to use hash tags for better performance.

redis = Redis::Cluster.new(nodes: %w[redis://127.0.0.1:7000])

# This will fail if keys are in different slots
redis.mget('key1', 'key2')
#=> Redis::CommandError (CROSSSLOT Keys in request don't hash to the same slot)

# This succeeds because of the hash tag
redis.mget('{key}1', '{key}2')
#=> [nil, nil]