NAME
Redis::Client - Perl client for Redis 2.4 and up
VERSION
version 0.015
SYNOPSIS
use Redis::Client;
my $client = Redis::Client->new( host => 'localhost', port => 6379 );
# work with strings
$client->set( some_key => 'myval' );
my $str_val = $client->get( 'some_key' );
print $str_val; # myval
# work with lists
$client->lpush( some_list => 1, 2, 3 );
my $list_elem = $client->lindex( some_list => 2 );
print $list_elem; # 3
# work with hashes
$client->hset( 'some_hash', foobar => 42 );
my $hash_val = $client->hget( 'some_hash', 'foobar' );
print $hash_val; # 42DESCRIPTION
Redis::Client is a Perl-native client for the Redis (http://redis.io) key/value store. Redis supports storage and retrieval of strings, ordered lists, hashes, sets, and ordered sets.
Redis::Client uses the new binary-safe Unified Request Protocol to implement all of its commands. This requires that Redis::Client be able to get accurate byte-length counts of all strings passed to it. Therefore, if you are working with character data, it MUST be encoded to a binary form (e.g. UTF-8) before you send it to Redis; otherwise the string lengths may be counted incorrectly and the requests will fail. Redis guarantees round-trip safety for binary data.
This distribution includes classes for working with Redis data via tie based objects that map Redis items to native Perl data types. See the documentation for those modules for usage:
INSTALLATION
Redis::Client can be installed the usual way via CPAN. In order to run the test suite, Redis::Client needs to know about a Redis server that it can talk to. Make sure to set the following environment variables prior to installing this distribution or running the test suite.
PERL_REDIS_TEST_SERVER- the hostname of the Redis server (default localhost).PERL_REDIS_TEST_PORT- the port number of the Redis server (default 6379).PERL_REDIS_TEST_PASSWORD- (optional) the Redis server password (defaultundef).
All keys generated by the test suite will have the prefix perl_redis_test. Unless something goes wrong, they'll all be deleted when each test is completed.
CLASS METHODS
new
Constructor. Returns a new Redis::Client object for talking to a Redis server. Throws a fatal error if a connection cannot be obtained.
hostThe hostname of the Redis server. Defaults to
localhost.portThe port number of the Redis server. Defaults to
6379.
Redis connection passwords are not currently supported.
my $client = Redis::Client->new( host => 'foo.example.com', port => 1234 );KEY METHODS
del
Redis DEL command.
Deletes keys. Takes a list of key names. Returns the number of keys deleted.
$client->del( 'foo', 'bar', 'baz' );type
Redis TYPE command.
Retrieves the type of a key. Takes the key name and returns one of string, list, hash, set, or zset.
my $type = $client->type( 'some_key' );STRING METHODS
get
Redis GET command.
Retrieves a string value associated with a key. Takes one key name. Returns undef if the key does not exist. If the key is associated with something other than a string, a fatal error is thrown.
print $client->get( 'mykey' );append
Redis APPEND command.
Appends a value to the end of a string. Takes the key name and a value to append. Returns the new length of the string. If the key is not a string, a fatal error is thrown.
my $new_length = $client->append( mykey => 'foobar' );decr
Redis DECR command.
Decrements a number stored in a string. Takes the key name and returns the decremented value. If the key does not exist, zero is assumed and decremented to -1. If the key is not a string, a fatal error is thrown.
my $new_val = $client->decr( 'my_num' );decrby
Redis DECRBY command.
Decrements a number stored in a string by a certain amount. Takes the key name and the amount by which to decrement. Returns the new value. If the key is not a string, a fatal error is thrown.
my $new_val = $client->decrby( 'my_num', 3 );get
Redis GET command.
Returns the value of a string. Takes the key name. If the key is not a string, a fatal error is thrown.
my $val = $client->get( 'my_key' );getbit
Redis GETBIT command.
Returns the value of one bit in a string. Takes the key name and the offset of the bit. If the offset is beyond the length of the string, 0 is returned. If the key is not a string, a fatal error is thrown.
my $bit = $client->getbit( 'my_key', 4 ); # fifth bit from leftgetrange
Redis GETRANGE command.
Returns a substring of a string, specified by a range. Takes the key name and the start and end offset of the range. Negative numbers count from the end. If the key is not a string, a fatal error is thrown.
my $substr = $client->getrange( 'my_key', 3, 5 );
my $substr = $client->getrange( 'my_key', -5, -1 ); # last five getset
Redis GETSET command.
Sets the value of a string and returns the old value atomically. Takes the key name and the new value. If the key is not a string, a fatal error is thrown. If the key does not exist, it is created and undef is returned.
my $old_val = $client->getset( my_key => 'new value' );incr
Redis INCR command.
Increments a number stored in a string. Takes the key name and returns the incremented value. If the key does not exist, zero is assumed and incremented to 1. If the key is not a string, a fatal error is thrown.
my $new_val = $client->incr( 'my_num' );incrby
Redis INCRBY command.
Increments a number stored in a string by a certain amount. Takes the key name and the amount by which to increment. Returns the new value. If the key is not a string, a fatal error is thrown.
my $new_val = $client->incrby( 'my_num', 3 );mget
Redis MGET command.
Gets the values of multiple strings. Takes the list of key names to get. If a key does not exist or if it is not a string, undef will be returned in its place.
my @vals = $client->mget( 'foo', 'bar', baz' );
print $vals[2]; # value of bazmset
Redis MSET command.
Sets the values of multiple strings. Takes a list of key/value pairs to set. If a key does not exist, it will be created. If a key is not a string, it will be silently converted to one. Therefore, use with caution.
$client->mset( foo => 1, bar => 2, baz => 3 );msetnx
Redis MSETNX command.
Atomically sets the values of multiple strings, only if none of the keys yet exist. Returns 1 on success, 0 otherwise.
my $it_worked = $client->msetnx( foo => 1, bar => 2, baz => 3 );set
Redis SET command.
Sets the value of a string. Takes the key name and a value.
$client->set( my_key => 'foobar' );setbit
Redis SETBIT command.
Sets the value of one bit in a string. Takes the key name, offset of the bit, and new value. Returns the original value of the bit. If the key is not a string or if the bit value is not 0 or 1, a fatal error is thrown.
my $old_bit = $client->setbit( 'my_key', 3, 1 );setex
Redis SETEX command.
Sets the value of a string and its expiration time in seconds. Takes the key name, the expiration time, and the value.
$client->setex( 'my_key', 5, 'foo' ); # goes bye-bye in 5 secs.setnx
Redis SETNX command.
Sets the value of a string, only if it does not yet exist. Takes the key name and value. Returns 1 on success, 0 otherwise.
my $key_was_set = $client->setnx( my_key => 'foobar' ); setrange
Redis SETRANGE command.
Sets the value of a substring of a string. Takes the key name, the offset, and a replacement string. Returns the length of the modified string. If the key is not a string, a fatal error is thrown.
$client->set( my_key => "I'm a teapot." );
my $new_length = $client->setrange( 'my_key', 6, 'foobar' ); # I'm a foobar.strlen
Redis STRLEN command.
Returns the length of a string. Takes the key name. If the key is not a string, a fatal error is thrown.
my $length = $client->strlength( 'my_key' );LIST METHODS
blpop
Redis BLPOP command.
Blocking left list pop. Takes a list of keys to poll and a timeout in seconds. Returns a two-element list containing the name of the list and the popped value on success, undef otherwise. Returns immediately if a value is waiting on any of the specified lists, otherwise waits for a value to appear or the timeout to expire. A timeout of zero waits forever.
my ( $list, $value ) = $client->blpop( 'list1', 'list2', 5 ); # wait 5 secsSee lpop for the non-blocking version.
brpop
Redis BRPOP command.
Blocking right list pop. Takes a list of keys to poll and a timeout in seconds. Returns a two-element list containing the name of the list and the popped value on success, undef otherwise. Returns immediately if a value is waiting on any of the specified lists, otherwise waits for a value to appear or the timeout to expire. A timeout of zero waits forever.
my ( $list, $value ) = $client->brpop( 'list1', 'list2', 5 ); # wait 5 secsSee rpop for the non-blocking version.
brpoplpush
Redis BRPOPLPUSH command.
Blocking atomic right list pop with left list push. Takes the source to pop, the destination list to push, and a timeout value. Returns the element being popped from the source and pushed to the destination, or undef if it times out. A timeout of zero waits forever.
my $val = $client->brpoplpush( 'source_list', 'dest_list', 5 ); See rpoplpush for the non-blocking version.
lindex
Redis LINDEX command.
Retrieves the value stored at a particular index in a list. Takes the list name and the numeric index.
my $val = $client->lindex( 'my_list', 42 );lset
Redis LSET command.
Sets the value at a particular index in a list. Takes the list name, the numeric index, and the new value.
$client->lset( 'my_list', 42, 'yippee!' );llen
Redis LLEN command.
Retrieves the number of items in a list. Takes the list name.
my $length = $client->llen( 'my_list' );ltrim
Redis LTRIM command.
Removes all elements of a list outside of the specified range. Takes the list name, start index, and stop index. All keys between the start and stop indices (inclusive) will be preserved. The rest will be deleted. The list is shifted down if the start index is not zero. The stop index -1 can be used to select everything until the end of the list.
# get rid of first two elements.
$client->ltrim( 'my_list', 2, -1 );rpush
Redis RPUSH command.
Adds items to the end of a list, analogous to the Perl push operator. Takes the list name and a list of items to add. Returns the length of the list when done.
my $new_length = $client->rpush( my_list => 42, 43, 'narf', 'poit' );rpop
Redis RPOP command.
Removes and returns the last element of a list, analogous to the Perl pop operator.
my $last = $client->rpop( 'my_list' );lpush
Redis LPUSH command.
Adds items to the beginning of a list, analogous to the Perl unshift operator. Takes the list name and a list of items to add. Returns the length of the list when done.
my $new_length = $client->lpush( my_list => 1, 2, 3 );lpop
Redis LPOP command.
Removes and returns the first element of a list, analogous to the Perl shift operator.
my $first = $client->lpop( 'my_list' );HASH METHODS
hdel
Redis HDEL command.
Deletes keys from a hash. Takes the name of a hash and a list of key names to delete. Returns the number of keys deleted. Returns zero if the hash does not exist, or if none of the keys specified exist in the hash.
$client->hdel( 'myhash', 'foo', 'bar', 'baz' );hexists
Redis HEXISTS command.
Returns a true value if a key exists in a hash. Takes a hash name and the key name.
blah() if $client->hexists( 'myhash', 'foo' );hget
Redis HGET command.
Retrieves a value associated with a key in a hash. Takes the name of the hash and the key within the hash. Returns undef if the hash or the key within the hash does not exist. (Use "hexists" to determine if a key exists at all.)
# sets the value for 'key' in the hash 'foo'
$client->hset( 'foo', key => 42 );
print $client->hget( 'foo', 'key' ); # 42hgetall
Redis HGETALL command.
Retrieves all of the keys and values in a hash. Takes the name of the hash and returns a list of key/value pairs.
my %hash = $client->hgetall( 'myhash' );hkeys
Redis HKEYS command.
Retrieves a list of all the keys in a hash. Takes the name of the hash and returns a list of keys.
my @keys = $client->hkeys( 'myhash' );hlen
Redis HLEN command.
Retrieves the number of keys in a hash. Takes the name of the hash.
my $size = $client->hlen( 'myhash' );hmget
Redis HMGET command.
Retrieves a list of values associated with the given keys in a hash. Takes the name of the hash and a list of keys. If a given key does not exist, undef will be returned in the corresponding location in the result list.
my @values = $client->hmget( 'myhash', 'key1', 'key2', 'key3' );hmset
Redis HMSET command.
Sets a list of key/value pairs in a hash. Takes the hash name and a list of keys and values to set.
$client->hmset( 'myhash', foo => 1, bar => 2, baz => 3 );hvals
Redis HVALS command.
Retrieves a list of all the values in a given hash. Takes the hash name.
my @values = $client->hvals( 'myhash' );SET METHODS
sadd
Redis SADD command.
Adds members to a set. Takes the names of the set and the members to add.
$client->sadd( 'myset', 'foo', 'bar', 'baz' );srem
Redis SREM command.
Removes members from a set. Takes the names of the set and the members to remove.
$client->srem( 'myset', 'foo', 'baz' );smembers
Redis SMEMBERS command.
Returns a list of all members in a set, in no particular order. Takes the name of the set.
my @members = $client->smembers( 'myset' );sismember
Redis SISMEMBER command.
Returns a true value if the given member is in a set. Takes the names of the set and the member.
if ( $client->sismember( 'myset', foo' ) ) { ... }SORTED SET METHODS
zadd
Redis ZADD command.
Adds members to a sorted set (zset). Takes the sorted set name and a list of score/member pairs.
$client->zadd( 'myzset', 1 => 'foo', 2 => 'bar', 3 => 'baz' );(The ordering of the scores and member names may seem backwards if you think of zsets as rough analogs of hashes. That's just how Redis does it.)
zcard
Redis ZCARD command.
Returns the cardinality (size) of a sorted set. Takes the name of the sorted set.
my $size = $client->zcard( 'myzset' );zcount
Redis ZCOUNT command.
Returns the number of members in a sorted set with scores between two values. Takes the name of the sorted set and the minimum and maximum
my $count = $client->zcount( 'myzset', $min, $max );zrange
Redis ZRANGE command.
Returns all the members of a sorted set with scores between two values. Takes the name of the sorted set, a minimum and maximum, and an optional boolean to control whether or not the scores are returned along with the members.
my @members = $client->zrange( 'myzset', $min, $max );
my %members_scores = $client->zrange( 'myzset', $min, $max, 1 );zrank
Redis ZRANK command.
Returns the index of a member within a sorted. set. Takes the names of the sorted set and the member.
my $rank = $client->zrank( 'myzset', 'foo' );zscore
Redis ZSCORE command.
Returns the score associated with a member in a sorted set. Takes the names of the sorted set and the member.
my $score = $client->zscore( 'myzset', 'foo' );CONNECTION METHODS
echo
Redis ECHO command.
Returns whatever you send it. Useful for testing only. Takes one argument.
print $client->echo( "Hello, World!" );CAVEATS
This early release is not feature-complete. I've implemented all the Redis commands that I use, but there are several that are not yet implemented. There is also no support for Redis publish/subscribe, but I intend to add that soon. Patches welcome. :)
The MONITOR command will probably not be supported any time soon since it would require some kind of asynchronous solution and does not use the URP.
EXTENDS
CONSUMES
AUTHOR
Mike Friedman <friedo@friedo.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Mike Friedman.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.