Redis::ClusterRider - Daring Redis Cluster client
use Redis::ClusterRider; my $cluster = Redis::ClusterRider->new( startup_nodes => [ 'localhost:7000', 'localhost:7001', 'localhost:7002', ], ); $cluster->set( 'foo', 'bar' ); my $value = $cluster->get('foo'); print "$value\n";
Redis::ClusterRider is the Redis Cluster client built on top of the Redis.
Requires Redis 3.0 or higher.
For more information about Redis Cluster see here:
http://redis.io/topics/cluster-tutorial
http://redis.io/topics/cluster-spec
my $cluster = Redis::ClusterRider->new( startup_nodes => [ 'localhost:7000', 'localhost:7001', 'localhost:7002', ], username => 'yourname', password => 'yourpass', fallback => 1, cnx_timeout => 5, read_timeout => 5, refresh_interval => 5, lazy => 1, on_node_connect => sub { my $hostport = shift; # handling... }, on_node_error => sub { my $err = shift; my $hostport = shift; # error handling... }, );
Specifies the list of startup nodes. Parameter should contain the array of addresses of some nodes in the cluster. The client will try to connect to random node from the list to retrieve information about all cluster nodes and slots mapping. If the client could not connect to first selected node, it will try to connect to another random node from the list.
If the password is specified, the AUTH command is sent to all nodes of the cluster after connection.
AUTH
Authenticate to the server using Redis 6.0+ ACL System (see https://redis.io/commands/auth)
If enabled, the client will try to send read-only commands to slave nodes.
If enabled, perform additional quick Redis connection to startup_nodes[0] on new() call and return Redis object if it has cluster support disabled.
startup_nodes[0]
new()
Disabled by default.
The cnx_timeout option enables connection timeout. The client will wait at most that number of seconds (can be fractional) before giving up connecting to a server.
cnx_timeout
cnx_timeout => 10.5,
By default the client use kernel's connection timeout.
The read_timeout option enables read timeout. The client will wait at most that number of seconds (can be fractional) before giving up when reading from the server.
read_timeout
Not set by default.
If enabled, the initial connection to the startup node establishes at time when you will send the first command to the cluster. By default the initial connection establishes after calling of the new method. lazy for startup_nodes[0] has no sense if fallback is enabled.
new
lazy
fallback
Cluster state refresh interval. If set to zero, cluster state will be updated only on MOVED redirect.
By default is 15 seconds.
The on_node_connect callback is called when the connection to particular node is successfully established. To callback is passed address of the node to which the client was connected.
on_node_connect
The on_node_error callback is called when occurred an error on particular node. To callback are passed two arguments: error message, and address of the node on which an error occurred.
on_node_error
See documentation on Redis for more options.
Attention, Redis options reconnect and every are redefined inside the Redis::ClusterRider for own purproses. User defined values for this options will be ignored.
reconnect
every
To execute the command you must call particular method with corresponding name. If any error occurred during the command execution, the client throw an exception.
Before the command execution, the client determines the pool of nodes, on which the command can be executed. The pool can contain the one or more nodes depending on the cluster and the client configurations, and the command type. The client will try to execute the command on random node from the pool and, if the command failed on selected node, the client will try to execute it on another random node.
If the connection to the some node was lost, the client will try to restore the connection when you execute next command. The client will try to reconnect only once and, if attempt fails, the client throw an exception. If you need several attempts of the reconnection, you must catch the exception and retry a command as many times, as you need. Such behavior allows to control reconnection procedure.
The full list of the Redis commands can be found here: http://redis.io/commands.
my $value = $cluster->get('foo'); my $list = $cluster->lrange( 'list', 0, -1 ); my $counter = $cluster->incr('counter');
The alternative way of command execution is explicit run_command() call. This approach is the only way if Redis commands contain punctuation, such as GRAPH.QUERY command of RedisGraph module.
run_command()
GRAPH.QUERY
my $list = $cluster->run_command( 'GRAPH.QUERY', $graph, $cypher_query );
To perform the transaction you must get the master node by the key using nodes method. Then you need to execute ECHO command or any other command before MULTI command to avoid the error "reconnect disabled inside transaction or watch" because all connection in the cluster client are lazy.
nodes
ECHO
MULTI
my $node = $cluster->nodes('foo'); $node->echo('ping'); $node->multi; $node->set( '{foo}bar', "some\r\nstring" ); $node->set( '{foo}car', 42 ); my $reply = $node->exec;
The detailed information about the Redis transactions can be found here: http://redis.io/topics/transactions.
Gets particular nodes of the cluster. In scalar context method returns the first node from the list.
Getting all master nodes of the cluster:
my @master_nodes = $cluster->nodes;
Getting all nodes of the cluster, including slave nodes:
my @nodes = $cluster->nodes( undef, 1 );
Getting master node by the key:
my $master_node = $cluster->nodes('foo');
Getting nodes by the key, including slave nodes:
my @nodes = $cluster->nodes( 'foo', 1 );
Gets or sets the refresh_interval of the client. The undef value resets the refresh_interval to default value.
refresh_interval
undef
Service functions provided by Redis::ClusterRider can be imported.
use Redis::ClusterRider qw( crc16 hash_slot );
Compute CRC16 for the specified data as defined in Redis Cluster specification.
Returns slot number by the key.
Redis, AnyEvent::RipeRedis, AnyEvent::RipeRedis::Cluster
Eugene Ponizovsky, <ponizovsky@gmail.com>
Sponsored by SMS Online, <dev.opensource@sms-online.com>
Copyright (c) 2017-2023, Eugene Ponizovsky, SMS Online. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Redis::ClusterRider, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Redis::ClusterRider
CPAN shell
perl -MCPAN -e shell install Redis::ClusterRider
For more information on module installation, please visit the detailed CPAN module installation guide.