class Redis::ReplicationClient

• Redis::ReplicationClient
• Reference
• Object

Overview

If you're using Redis replication, you can use ReplicationClient to send read commands to replicas and reduce load on the primary. This can be important when your Redis primary is CPU-bound.

The commands that will be routed to replicas are listed in Redis::READ_ONLY_COMMANDS.

NOTE Redis replication does not provide consistency guarantees. Every mechanism in Redis to improve consistency, such as WAIT, is best-effort, but not guaranteed. If you require strong consistency from Redis, stick to using Redis::Client. if you require strong consistency but your Redis primary is CPU-bound, you may need to either choose between consistency and performance or move that workload out of Redis.

This client is useful for operations where strong consistency isn't typically needed, such as caching, full-text search with Redis::FullText#search, querying time-series data with Redis::TimeSeries#mrange, checking the current state of larger data structures without blocking the primary, etc.

Explicitly routing commands to a primary or replica

This class provides #on_primary and #on_replica methods to ensure your command is routed to the server type you want. This is useful in several scenarios:

• you want to ensure you retrieve a value that is consistent with the state of the primary server — for example a value that changes frequently and you need the canonical state for observability purposes
• a read-only command is routed to a primary because this client does not yet know about it
  • You can add commands to Redis::READ_ONLY_COMMANDS in one-off cases
  • Feel free to open an issue or pull request to add it, as well

Topology changes

If the replication topology changes (for example, new replicas are added, existing ones removed, or the primary failed over), ReplicationClient will automatically pick up the changes. You can set how often it checks for these changes with the #topology_ttl argument to the constructor or leave it at its default of 10 seconds.

EXPERIMENTAL ReplicationClient is currently in alpha testing. There may be rough edges.

Included Modules

• Redis::Commands

Defined in:

Constant Summary

Log = ::Log.for(self)

Constructors

• .new(entrypoint : URI, topology_ttl : Time::Span = 10.seconds)

  Have the ReplicationClient discover the master and replicas on its own when given the URI of a single entrypoint.

• .new(master_uri : URI, replica_uris : Array(URI), topology_ttl : Time::Span = 10.seconds)

  Initialize the client with known master and replica URIs, keeping the toplogy up to date with at most #topology_ttl staleness.

• .new

Instance Method Summary

• #close

  Close all connections to both the primary and all replicas.

• #closed? : Bool

  Returns true if this ReplicationClient has been explicitly closed, false otherwise.

• #on_master(&)

  Alias of #on_primary.

• #on_primary(&)

  Route one or more commands to the primary to avoid consistency issues arising from replication latency.

• #on_replica(&)

  Route one or more commands to replicas.

• #run(command full_command)

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

• #topology_ttl : Time::Span

Constructor Detail

redis = Redis::ReplicationClient.new(

Instance Method Detail

require "redis/replication_client"

redis = Redis::ReplicationClient.new

redis.incr "counter"
value = redis.on_primary &.get("counter")

redis.on_primary &.transaction do |txn|
  txn.incr "counter:#{queue}"
  txn.sadd "queues", queue
  txn.lpush "queue:#{queue}", job_data
end

redis.on_primary do |primary|
  primary.transaction do |txn|
    txn.incr "counter:#{queue}"
    txn.sadd "queues", queue
    txn.lpush "queue:#{queue}", job_data
  end
end

redis.on_primary do |primary|
  counter = primary.incr "counter:#{queue}"
  primary.sadd "queues", queue
end

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