Documentation

RedisCluster
in package
implements ClusterInterface, IteratorAggregate, Countable

Abstraction for a Redis-backed cluster of nodes (Redis >= 3.0.0).

This connection backend offers smart support for redis-cluster by handling automatic slots map (re)generation upon -MOVED or -ASK responses returned by Redis when redirecting a client to a different node.

The cluster can be pre-initialized using only a subset of the actual nodes in the cluster, Predis will do the rest by adjusting the slots map and creating the missing underlying connection instances on the fly.

It is possible to pre-associate connections to a slots range with the "slots" parameter in the form "$first-$last". This can greatly reduce runtime node guessing and redirections.

It is also possible to ask for the full and updated slots map directly to one of the nodes and optionally enable such a behaviour upon -MOVED redirections. Asking for the cluster configuration to Redis is actually done by issuing a CLUSTER SLOTS command to a random node in the pool.

Tags
author

Daniele Alessandri suppakilla@gmail.com

Interfaces, Classes and Traits

ClusterInterface
Defines a cluster of Redis servers formed by aggregating multiple connection instances to single Redis nodes.
IteratorAggregate
Countable

Table of Contents

$connections  : mixed
$pool  : mixed
$retryLimit  : mixed
$slots  : mixed
$slotsMap  : mixed
$strategy  : mixed
$useClusterSlots  : mixed
__construct()  : mixed
add()  : mixed
{@inheritdoc}
askSlotsMap()  : array<string|int, mixed>
Generates an updated slots map fetching the cluster configuration using the CLUSTER SLOTS command against the specified node or a random one from the pool.
buildSlotsMap()  : array<string|int, mixed>
Generates the current slots map by guessing the cluster configuration out of the connection parameters of the connections in the pool.
connect()  : mixed
{@inheritdoc}
count()  : int
disconnect()  : mixed
{@inheritdoc}
executeCommand()  : mixed
{@inheritdoc}
getClusterStrategy()  : StrategyInterface
Returns the underlying command hash strategy used to hash commands by using keys found in their arguments.
getConnection()  : mixed
{@inheritdoc}
getConnectionById()  : mixed
{@inheritdoc}
getConnectionBySlot()  : NodeConnectionInterface
Returns the connection currently associated to a given slot.
getConnectionFactory()  : FactoryInterface
Returns the underlying connection factory used to create new connection instances to Redis nodes indicated by redis-cluster.
getIterator()  : Traversable<int, NodeConnectionInterface>
getSlotsMap()  : array<string|int, mixed>
Returns the current slots map for the cluster.
isConnected()  : mixed
{@inheritdoc}
readResponse()  : mixed
{@inheritdoc}
remove()  : mixed
{@inheritdoc}
removeById()  : bool
Removes a connection instance by using its identifier.
resetSlotsMap()  : mixed
Resets the slots map cache.
setRetryLimit()  : mixed
Sets the maximum number of retries for commands upon server failure.
setSlots()  : mixed
Pre-associates a connection to a slots range to avoid runtime guessing.
useClusterSlots()  : mixed
Enables automatic fetching of the current slots map from one of the nodes using the CLUSTER SLOTS command. This option is enabled by default as asking the current slots map to Redis upon -MOVED responses may reduce overhead by eliminating the trial-and-error nature of the node guessing procedure, mostly when targeting many keys that would end up in a lot of redirections.
writeRequest()  : mixed
{@inheritdoc}
createConnection()  : NodeConnectionInterface
Creates a new connection instance from the given connection ID.
getRandomConnection()  : NodeConnectionInterface|null
Returns a random connection from the pool.
guessNode()  : string
Guesses the correct node associated to a given slot using a precalculated slots map, falling back to the same logic used by Redis to initialize a cluster (best-effort).
move()  : mixed
Permanently associates the connection instance to a new slot.
onAskResponse()  : mixed
Handles -ASK responses by executing again the command against the node indicated by the Redis response.
onErrorResponse()  : mixed
Handles -ERR responses returned by Redis.
onMovedResponse()  : mixed
Handles -MOVED responses by executing again the command against the node indicated by the Redis response.
queryClusterNodeForSlotsMap()  : mixed
Queries the specified node of the cluster to fetch the updated slots map.
retryCommandOnFailure()  : mixed
Ensures that a command is executed one more time on connection failure.

Properties

Methods

askSlotsMap()

Generates an updated slots map fetching the cluster configuration using the CLUSTER SLOTS command against the specified node or a random one from the pool.

public askSlotsMap([NodeConnectionInterface $connection = null ]) : array<string|int, mixed>
Parameters
$connection : NodeConnectionInterface = null

Optional connection instance.

Return values
array<string|int, mixed> —

buildSlotsMap()

Generates the current slots map by guessing the cluster configuration out of the connection parameters of the connections in the pool.

public buildSlotsMap() : array<string|int, mixed>

Generation is based on the same algorithm used by Redis to generate the cluster, so it is most effective when all of the connections supplied on initialization have the "slots" parameter properly set accordingly to the current cluster configuration.

Return values
array<string|int, mixed> —

connect()

{@inheritdoc}

public connect() : mixed
Return values
mixed —

disconnect()

{@inheritdoc}

public disconnect() : mixed
Return values
mixed —

getConnectionById()

{@inheritdoc}

public getConnectionById(mixed $connectionID) : mixed
Parameters
$connectionID : mixed
Return values
mixed —

getConnectionFactory()

Returns the underlying connection factory used to create new connection instances to Redis nodes indicated by redis-cluster.

public getConnectionFactory() : FactoryInterface
Return values
FactoryInterface —

getSlotsMap()

Returns the current slots map for the cluster.

public getSlotsMap() : array<string|int, mixed>

The order of the returned $slot => $server dictionary is not guaranteed.

Return values
array<string|int, mixed> —

isConnected()

{@inheritdoc}

public isConnected() : mixed
Return values
mixed —

removeById()

Removes a connection instance by using its identifier.

public removeById(string $connectionID) : bool
Parameters
$connectionID : string

Connection identifier.

Return values
bool —

True if the connection was in the pool.

resetSlotsMap()

Resets the slots map cache.

public resetSlotsMap() : mixed
Return values
mixed —

setRetryLimit()

Sets the maximum number of retries for commands upon server failure.

public setRetryLimit(int $retry) : mixed

-1 = unlimited retry attempts 0 = no retry attempts (fails immediatly) n = fail only after n retry attempts

Parameters
$retry : int

Number of retry attempts.

Return values
mixed —

setSlots()

Pre-associates a connection to a slots range to avoid runtime guessing.

public setSlots(int $first, int $last, NodeConnectionInterface|string $connection) : mixed
Parameters
$first : int

Initial slot of the range.

$last : int

Last slot of the range.

$connection : NodeConnectionInterface|string

ID or connection instance.

Tags
throws
OutOfBoundsException
Return values
mixed —

useClusterSlots()

Enables automatic fetching of the current slots map from one of the nodes using the CLUSTER SLOTS command. This option is enabled by default as asking the current slots map to Redis upon -MOVED responses may reduce overhead by eliminating the trial-and-error nature of the node guessing procedure, mostly when targeting many keys that would end up in a lot of redirections.

public useClusterSlots(bool $value) : mixed

The slots map can still be manually fetched using the askSlotsMap() method whether or not this option is enabled.

Parameters
$value : bool

Enable or disable the use of CLUSTER SLOTS.

Return values
mixed —

guessNode()

Guesses the correct node associated to a given slot using a precalculated slots map, falling back to the same logic used by Redis to initialize a cluster (best-effort).

protected guessNode(int $slot) : string
Parameters
$slot : int

Slot index.

Return values
string —

Connection ID.

move()

Permanently associates the connection instance to a new slot.

protected move(NodeConnectionInterface $connection, int $slot) : mixed

The connection is added to the connections pool if not yet included.

Parameters
$connection : NodeConnectionInterface

Connection instance.

$slot : int

Target slot index.

Return values
mixed —

onAskResponse()

Handles -ASK responses by executing again the command against the node indicated by the Redis response.

protected onAskResponse(CommandInterface $command, string $details) : mixed
Parameters
$command : CommandInterface

Command that generated the -ASK response.

$details : string

Parameters of the -ASK response.

Return values
mixed —

onMovedResponse()

Handles -MOVED responses by executing again the command against the node indicated by the Redis response.

protected onMovedResponse(CommandInterface $command, string $details) : mixed
Parameters
$command : CommandInterface

Command that generated the -MOVED response.

$details : string

Parameters of the -MOVED response.

Return values
mixed —

queryClusterNodeForSlotsMap()

Queries the specified node of the cluster to fetch the updated slots map.

private queryClusterNodeForSlotsMap(NodeConnectionInterface $connection) : mixed

When the connection fails, this method tries to execute the same command on a different connection picked at random from the pool of known nodes, up until the retry limit is reached.

Parameters
$connection : NodeConnectionInterface

Connection to a node of the cluster.

Return values
mixed —

retryCommandOnFailure()

Ensures that a command is executed one more time on connection failure.

private retryCommandOnFailure(CommandInterface $command, string $method) : mixed

The connection to the node that generated the error is evicted from the pool before trying to fetch an updated slots map from another node. If the new slots map points to an unreachable server the client gives up and throws the exception as the nodes participating in the cluster may still have to agree that something changed in the configuration of the cluster.

Parameters
$command : CommandInterface

Command instance.

$method : string

Actual method.

Return values
mixed —

Search results