class

Redis::Cluster

Inherits Redis::Commands::Immediate < Redis::Commands < Redis::Commands::Vector < Redis::Commands::HyperLogLog < Redis::Commands::Geo < Redis::Commands::Stream < Redis::Commands::SortedSet < Redis::Commands::Set < Redis::Commands::List < Redis::Commands::Hash < Reference < Object

Use in place of a Redis::Client when talking to Redis clusters. This class will discover all nodes in a Redis cluster when given a URI for any of them, route commands to appropriate shards based on the keys they operate on, and route commands which do not change state to shard replicas to spread the load across the cluster.

As nodes are added or removed, replicas are promoted, or hash slots migrate between shards, the cluster client will adapt to the new topology automatically. Commands that receive a MOVED redirection are retried against the new node, and topology is re-discovered in the background so subsequent commands route correctly without requiring another redirection. Commands that receive an ASK redirection (slot mid-migration) are retried against the importing node with an ASKING prefix.

It's important that, when using commands which operate on multiple keys (for example: MGET, DEL, RPOPLPUSH, etc) that all specified keys reside on the same shard in the cluster. Usually, this means designing your key names with curly braces around parts of them to ensure they hash to the same key slot. For example:

redis.del "{comment}:1", "{comment}:2"
value = redis.rpoplpush "{queue}:default", "{queue}:default:pending"

If you want to use a Redis module that provides custom commands, you can register them as read-only with Redis::Cluster.register_read_only_commands and they will automatically be routed to replicas. See redis/cluster/json.cr for example usage.

Constructors

new(uri : URI = URI.parse(ENV["REDIS_CLUSTER_URL"]? || "redis:///"), topology_refresh_throttle : Time::Span = 1.second)

Pass a URI (defaulting to the REDIS_CLUSTER_URL environment variable) to connect to the specified Redis cluster — the URI can point to any server in the cluster and Redis::Cluster will discover the rest.

topology_refresh_throttle controls the minimum interval between automatic background topology refreshes. When MOVED redirections come in faster than this interval, refreshes are coalesced.

Source

Class methods

register_read_only_command(command : String)

Tell the cluster driver that the specified Redis command can be routed to read-only replicas.

Redis::Cluster.register_read_only_command "mymodule.get"
Source
register_read_only_commands(commands : Enumerable(String))

Tell the cluster driver that all the specified Redis commands can be routed to read-only replicas.

Redis::Cluster.register_read_only_commands %w[
  mymodule.get
  mymodule.mget
]
Source

Instance methods

close

Close all connections to this Redis cluster

Source
flushdb

Executes flushdb on each shard in the cluster.

Source
keys

Get all key across all shards. This executes a keys command on every shard in the cluster. Probably not a good idea in production since this will block every Redis shard or replica for the duration of the query, but we're supporting it because you may have a reasonable use case for it at some point and it's just not easy to do otherwise.

Source
pipeline(key : String, &)

Run a pipeline for the specified key

cluster.pipeline "{widgets}" do |pipe|
  widget_ids.each do |id|
    pipe.get "{widgets}:#{id}"
  end
end

WARNING: All keys that this pipeline operates on MUST reside on the same shard. It's best to pass a pre-hashed key (one containing {}) to this method. See the example above.

Source
psubscribe(*patterns : String, &)

Subscribe to one or more pubsub channel patterns. Like subscribe, messages are propagated across the cluster.

Source
refresh_topology(force : Bool = true) : Nil

Force a refresh of the cluster's topology. This is normally done automatically in response to MOVED redirections, but it can be useful to call this method explicitly when an external process tells you that the cluster has changed.

Source
run(command full_command)

Execute the given command and return the result from the server. Commands must be an Enumerable and its size method must be re-entrant.

run({"set", "foo", "bar"})
Source
scan_each(*args, **kwargs, &) : Nil

Execute Commands#scan_each on each shard, yielding any matching keys.

Source
slot_for(key : String)

Return the Redis hash slot for the given key. This is useful for seeing which shard your command will be routed to.

Source
spublish(channel : String, message : String)

Publish a message to a sharded pubsub channel. The message is delivered only to subscribers on the shard that owns the channel's hash slot — unlike publish, it is not propagated across the cluster.

Source
ssubscribe(*channels : String, &)

Subscribe to one or more sharded pubsub channels. All channels must hash to the same slot (use {} to force co-location). The block yields a Subscription and the underlying Connection, which holds the subscription for its duration.

cluster.ssubscribe "orders" do |subscription, connection|
  subscription.on_message do |channel, message|
    # ...
  end
end
Source
subscribe(*channels : String, &)

Subscribe to one or more pubsub channels. Regular (non-sharded) pub/sub messages are propagated across the cluster, so the subscriber will receive messages regardless of which node a publisher targets.

Source
sunsubscribe(*channels : String)

Unsubscribe from sharded pubsub channels on the shard that owns their hash slot. Typically called from inside an ssubscribe block via the yielded Connection; calling this on the cluster directly routes a standalone SUNSUBSCRIBE to the shard and has no effect on a subscription held by a different connection.

Source

Nested types