class Redis::Cluster

• Redis::Cluster
• Reference
• Object

Overview

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.

Included Modules

• Redis::Commands
• Redis::Commands::Immediate

Defined in:

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.

Class Method Summary

• .register_read_only_command(command : String)

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

• .register_read_only_commands(commands : Enumerable(String))

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

Instance Method Summary

• #close

  Close all connections to this Redis cluster

• #flushdb

  Executes #flushdb on each shard in the cluster.

• #keys : Array(String)

  Get all key across all shards.

• #pipeline(key : String, &)

  Run a pipeline for the specified key

• #psubscribe(*patterns : String, &)

  Subscribe to one or more pubsub channel patterns.

• #refresh_topology(force : Bool = true) : Nil

  Force a refresh of the cluster's topology.

• #run(command full_command)

  Execute the given command and return the result from the server.

• #scan_each(*args, **kwargs, &) : Nil

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

• #slot_for(key : String)

  Return the Redis hash slot for the given key.

• #spublish(channel : String, message : String)

  Publish a message to a sharded pubsub channel.

• #ssubscribe(*channels : String, &)

  Subscribe to one or more sharded pubsub channels.

• #subscribe(*channels : String, &)

  Subscribe to one or more pubsub channels.

• #sunsubscribe(*channels : String)

  Unsubscribe from sharded pubsub channels on the shard that owns their hash slot.

Constructor Detail

Class Method Detail

Redis::Cluster.register_read_only_command "mymodule.get"

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

Instance Method Detail

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

run({"set", "foo", "bar"})

cluster.ssubscribe "orders" do |subscription, connection|
  subscription.on_message do |channel, message|
    # ...
  end
end