Connect to a Redis server:

 -- connects to localhost:6379
 conn <- connect defaultConnectInfo

Send commands to the server:

 {-# LANGUAGE OverloadedStrings #-}
 ...
 runRedis conn $ do
      set "hello" "hello"
      set "world" "world"
      hello <- get "hello"
      world <- get "world"
      liftIO $ print (hello,world)

Redis commands behave differently when issued in- or outside of a transaction. To make them work in both contexts, most command functions have a type signature similar to the following:

  echo :: (RedisCtx m f) => ByteString -> m (f ByteString)

Here is how to interpret this type signature:

• The argument types are independent of the execution context. echo always takes a ByteString parameter, whether in- or outside of a transaction. This is true for all command functions.
• All Redis commands return their result wrapped in some "container". The type f of this container depends on the commands execution context m. The ByteString return type in the example is specific to the echo command. For other commands, it will often be another type.
• In the "normal" context Redis, outside of any transactions, results are wrapped in an Either Reply.
• Inside a transaction, in the RedisTx context, results are wrapped in a Queued.

In short, you can view any command with a RedisCtx constraint in the type signature, to "have two types". For example echo "has both types":

  echo :: ByteString -> Redis (Either Reply ByteString)
  echo :: ByteString -> RedisTx (Queued ByteString)

Exercise

What are the types of expire inside a transaction and lindex outside of a transaction? The solutions are at the very bottom of this page.

Lua values returned from the eval and evalsha functions will be converted to Haskell values by the decode function from the RedisResult type class.

  Lua Type      | Haskell Type       | Conversion Example
  --------------|--------------------|-----------------------------
  Number        | Integer            | 1.23   => 1
  String        | ByteString, Double | "1.23" => "1.23" or 1.23
  Boolean       | Bool               | false  => False
  Table         | List               | {1,2}  => [1,2]

Additionally, any of the Haskell types from the table above can be wrapped in a Maybe:

  42  => Just 42 :: Maybe Integer
  nil => Nothing :: Maybe Integer

Note that Redis imposes some limitations on the possible conversions:

• Lua numbers can only be converted to Integers. Only Lua strings can be interpreted as Doubles.
• Associative Lua tables can not be converted at all. Returned tables must be "arrays", i.e. indexed only by integers.

The Redis Scripting website (http://redis.io/commands/eval) documents the exact semantics of the scripting commands and value conversion.

Commands are automatically pipelined as much as possible. For example, in the above "hello world" example, all four commands are pipelined. Automatic pipelining makes use of Haskell's laziness. As long as a previous reply is not evaluated, subsequent commands can be pipelined.

Automatic pipelining also works across several calls to runRedis, as long as replies are only evaluated outside the runRedis block.

To keep memory usage low, the number of requests "in the pipeline" is limited (per connection) to 1000. After that number, the next command is sent only when at least one reply has been received. That means, command functions may block until there are less than 1000 outstanding replies.

Operations against keys holding the wrong kind of value:

Outside of a transaction, if the Redis server returns an Error, command functions will return Left the Reply. The library user can inspect the error message to gain information on what kind of error occured.

Connection to the server lost:

In case of a lost connection, command functions throw a ConnectionLostException. It can only be caught outside of runRedis.

Exceptions:

Any exceptions can only be caught outside of runRedis. This way the connection pool can properly close the connection, making sure it is not left in an unusable state, e.g. closed or inside a transaction.

Authenticate to the server (http://redis.io/commands/auth).

Echo the given string (http://redis.io/commands/echo).

Ping the server (http://redis.io/commands/ping).

Close the connection (http://redis.io/commands/quit).

Change the selected database for the current connection (http://redis.io/commands/select).

Delete a key (http://redis.io/commands/del).

Return a serialized version of the value stored at the specified key. (http://redis.io/commands/dump).

Determine if a key exists (http://redis.io/commands/exists).

Set a key's time to live in seconds (http://redis.io/commands/expire).

Set the expiration for a key as a UNIX timestamp (http://redis.io/commands/expireat).

Find all keys matching the given pattern (http://redis.io/commands/keys).

Atomically transfer a key from a Redis instance to another one. (http://redis.io/commands/migrate).

Move a key to another database (http://redis.io/commands/move).

Inspect the internals of Redis objects (http://redis.io/commands/object). The Redis command OBJECT is split up into objectRefcount, objectEncoding, objectIdletime.

Inspect the internals of Redis objects (http://redis.io/commands/object). The Redis command OBJECT is split up into objectRefcount, objectEncoding, objectIdletime.

Inspect the internals of Redis objects (http://redis.io/commands/object). The Redis command OBJECT is split up into objectRefcount, objectEncoding, objectIdletime.

Remove the expiration from a key (http://redis.io/commands/persist).

Set a key's time to live in milliseconds (http://redis.io/commands/pexpire).

Set the expiration for a key as a UNIX timestamp specified in milliseconds (http://redis.io/commands/pexpireat).

Get the time to live for a key in milliseconds (http://redis.io/commands/pttl).

Return a random key from the keyspace (http://redis.io/commands/randomkey).

Rename a key (http://redis.io/commands/rename).

Rename a key, only if the new key does not exist (http://redis.io/commands/renamenx).

Create a key using the provided serialized value, previously obtained using DUMP. (http://redis.io/commands/restore).

Sort the elements in a list, set or sorted set (http://redis.io/commands/sort). The Redis command SORT is split up into sort, sortStore.

Sort the elements in a list, set or sorted set (http://redis.io/commands/sort). The Redis command SORT is split up into sort, sortStore.

Get the time to live for a key (http://redis.io/commands/ttl).

Determine the type stored at key (http://redis.io/commands/type).

Delete one or more hash fields (http://redis.io/commands/hdel).

Determine if a hash field exists (http://redis.io/commands/hexists).

Get the value of a hash field (http://redis.io/commands/hget).

Get all the fields and values in a hash (http://redis.io/commands/hgetall).

Increment the integer value of a hash field by the given number (http://redis.io/commands/hincrby).

Increment the float value of a hash field by the given amount (http://redis.io/commands/hincrbyfloat).

Get all the fields in a hash (http://redis.io/commands/hkeys).

Get the number of fields in a hash (http://redis.io/commands/hlen).

Get the values of all the given hash fields (http://redis.io/commands/hmget).

Set multiple hash fields to multiple values (http://redis.io/commands/hmset).

Set the string value of a hash field (http://redis.io/commands/hset).

Set the value of a hash field, only if the field does not exist (http://redis.io/commands/hsetnx).

Get all the values in a hash (http://redis.io/commands/hvals).

Remove and get the first element in a list, or block until one is available (http://redis.io/commands/blpop).

Remove and get the last element in a list, or block until one is available (http://redis.io/commands/brpop).

Pop a value from a list, push it to another list and return it; or block until one is available (http://redis.io/commands/brpoplpush).

Get an element from a list by its index (http://redis.io/commands/lindex).

Insert an element before or after another element in a list (http://redis.io/commands/linsert). The Redis command LINSERT is split up into linsertBefore, linsertAfter.

Insert an element before or after another element in a list (http://redis.io/commands/linsert). The Redis command LINSERT is split up into linsertBefore, linsertAfter.

Get the length of a list (http://redis.io/commands/llen).

Remove and get the first element in a list (http://redis.io/commands/lpop).

Prepend one or multiple values to a list (http://redis.io/commands/lpush).

Prepend a value to a list, only if the list exists (http://redis.io/commands/lpushx).

Get a range of elements from a list (http://redis.io/commands/lrange).

Remove elements from a list (http://redis.io/commands/lrem).

Set the value of an element in a list by its index (http://redis.io/commands/lset).

Trim a list to the specified range (http://redis.io/commands/ltrim).

Remove and get the last element in a list (http://redis.io/commands/rpop).

Remove the last element in a list, append it to another list and return it (http://redis.io/commands/rpoplpush).

Append one or multiple values to a list (http://redis.io/commands/rpush).

Append a value to a list, only if the list exists (http://redis.io/commands/rpushx).

Execute a Lua script server side (http://redis.io/commands/eval).

Execute a Lua script server side (http://redis.io/commands/evalsha).

Check existence of scripts in the script cache. (http://redis.io/commands/script-exists).

Remove all the scripts from the script cache. (http://redis.io/commands/script-flush).

Kill the script currently in execution. (http://redis.io/commands/script-kill).

Load the specified Lua script into the script cache. (http://redis.io/commands/script-load).

Asynchronously rewrite the append-only file (http://redis.io/commands/bgrewriteaof).

Asynchronously save the dataset to disk (http://redis.io/commands/bgsave).

Get the value of a configuration parameter (http://redis.io/commands/config-get).

Reset the stats returned by INFO (http://redis.io/commands/config-resetstat).

Set a configuration parameter to the given value (http://redis.io/commands/config-set).

Return the number of keys in the selected database (http://redis.io/commands/dbsize).

Get debugging information about a key (http://redis.io/commands/debug-object).

Remove all keys from all databases (http://redis.io/commands/flushall).

Remove all keys from the current database (http://redis.io/commands/flushdb).

Get information and statistics about the server (http://redis.io/commands/info).

Get the UNIX time stamp of the last successful save to disk (http://redis.io/commands/lastsave).

Synchronously save the dataset to disk (http://redis.io/commands/save).

Make the server a slave of another instance, or promote it as master (http://redis.io/commands/slaveof).

Manages the Redis slow queries log (http://redis.io/commands/slowlog). The Redis command SLOWLOG is split up into slowlogGet, slowlogLen, slowlogReset.

Manages the Redis slow queries log (http://redis.io/commands/slowlog). The Redis command SLOWLOG is split up into slowlogGet, slowlogLen, slowlogReset.

Manages the Redis slow queries log (http://redis.io/commands/slowlog). The Redis command SLOWLOG is split up into slowlogGet, slowlogLen, slowlogReset.

Return the current server time (http://redis.io/commands/time).

Add one or more members to a set (http://redis.io/commands/sadd).

Get the number of members in a set (http://redis.io/commands/scard).

Subtract multiple sets (http://redis.io/commands/sdiff).

Subtract multiple sets and store the resulting set in a key (http://redis.io/commands/sdiffstore).

Intersect multiple sets (http://redis.io/commands/sinter).

Intersect multiple sets and store the resulting set in a key (http://redis.io/commands/sinterstore).

Determine if a given value is a member of a set (http://redis.io/commands/sismember).

Get all the members in a set (http://redis.io/commands/smembers).

Move a member from one set to another (http://redis.io/commands/smove).

Remove and return a random member from a set (http://redis.io/commands/spop).

Get a random member from a set (http://redis.io/commands/srandmember).

Remove one or more members from a set (http://redis.io/commands/srem).

Add multiple sets (http://redis.io/commands/sunion).

Add multiple sets and store the resulting set in a key (http://redis.io/commands/sunionstore).

Add one or more members to a sorted set, or update its score if it already exists (http://redis.io/commands/zadd).

Get the number of members in a sorted set (http://redis.io/commands/zcard).

Count the members in a sorted set with scores within the given values (http://redis.io/commands/zcount).

Increment the score of a member in a sorted set (http://redis.io/commands/zincrby).

Intersect multiple sorted sets and store the resulting sorted set in a new key (http://redis.io/commands/zinterstore). The Redis command ZINTERSTORE is split up into zinterstore, zinterstoreWeights.

Intersect multiple sorted sets and store the resulting sorted set in a new key (http://redis.io/commands/zinterstore). The Redis command ZINTERSTORE is split up into zinterstore, zinterstoreWeights.

Return a range of members in a sorted set, by index (http://redis.io/commands/zrange). The Redis command ZRANGE is split up into zrange, zrangeWithscores.

Return a range of members in a sorted set, by index (http://redis.io/commands/zrange). The Redis command ZRANGE is split up into zrange, zrangeWithscores.

Return a range of members in a sorted set, by score (http://redis.io/commands/zrangebyscore). The Redis command ZRANGEBYSCORE is split up into zrangebyscore, zrangebyscoreWithscores, zrangebyscoreLimit, zrangebyscoreWithscoresLimit.

Return a range of members in a sorted set, by score (http://redis.io/commands/zrangebyscore). The Redis command ZRANGEBYSCORE is split up into zrangebyscore, zrangebyscoreWithscores, zrangebyscoreLimit, zrangebyscoreWithscoresLimit.

Return a range of members in a sorted set, by score (http://redis.io/commands/zrangebyscore). The Redis command ZRANGEBYSCORE is split up into zrangebyscore, zrangebyscoreWithscores, zrangebyscoreLimit, zrangebyscoreWithscoresLimit.

Return a range of members in a sorted set, by score (http://redis.io/commands/zrangebyscore). The Redis command ZRANGEBYSCORE is split up into zrangebyscore, zrangebyscoreWithscores, zrangebyscoreLimit, zrangebyscoreWithscoresLimit.

Determine the index of a member in a sorted set (http://redis.io/commands/zrank).

Remove one or more members from a sorted set (http://redis.io/commands/zrem).

Remove all members in a sorted set within the given indexes (http://redis.io/commands/zremrangebyrank).

Remove all members in a sorted set within the given scores (http://redis.io/commands/zremrangebyscore).

Return a range of members in a sorted set, by index, with scores ordered from high to low (http://redis.io/commands/zrevrange). The Redis command ZREVRANGE is split up into zrevrange, zrevrangeWithscores.

Return a range of members in a sorted set, by index, with scores ordered from high to low (http://redis.io/commands/zrevrange). The Redis command ZREVRANGE is split up into zrevrange, zrevrangeWithscores.

Return a range of members in a sorted set, by score, with scores ordered from high to low (http://redis.io/commands/zrevrangebyscore). The Redis command ZREVRANGEBYSCORE is split up into zrevrangebyscore, zrevrangebyscoreWithscores, zrevrangebyscoreLimit, zrevrangebyscoreWithscoresLimit.

Return a range of members in a sorted set, by score, with scores ordered from high to low (http://redis.io/commands/zrevrangebyscore). The Redis command ZREVRANGEBYSCORE is split up into zrevrangebyscore, zrevrangebyscoreWithscores, zrevrangebyscoreLimit, zrevrangebyscoreWithscoresLimit.

Return a range of members in a sorted set, by score, with scores ordered from high to low (http://redis.io/commands/zrevrangebyscore). The Redis command ZREVRANGEBYSCORE is split up into zrevrangebyscore, zrevrangebyscoreWithscores, zrevrangebyscoreLimit, zrevrangebyscoreWithscoresLimit.

Return a range of members in a sorted set, by score, with scores ordered from high to low (http://redis.io/commands/zrevrangebyscore). The Redis command ZREVRANGEBYSCORE is split up into zrevrangebyscore, zrevrangebyscoreWithscores, zrevrangebyscoreLimit, zrevrangebyscoreWithscoresLimit.

Determine the index of a member in a sorted set, with scores ordered from high to low (http://redis.io/commands/zrevrank).

Get the score associated with the given member in a sorted set (http://redis.io/commands/zscore).

Add multiple sorted sets and store the resulting sorted set in a new key (http://redis.io/commands/zunionstore). The Redis command ZUNIONSTORE is split up into zunionstore, zunionstoreWeights.

Add multiple sorted sets and store the resulting sorted set in a new key (http://redis.io/commands/zunionstore). The Redis command ZUNIONSTORE is split up into zunionstore, zunionstoreWeights.

Append a value to a key (http://redis.io/commands/append).

Count set bits in a string (http://redis.io/commands/bitcount). The Redis command BITCOUNT is split up into bitcount, bitcountRange.

Count set bits in a string (http://redis.io/commands/bitcount). The Redis command BITCOUNT is split up into bitcount, bitcountRange.

Perform bitwise operations between strings (http://redis.io/commands/bitop). The Redis command BITOP is split up into bitopAnd, bitopOr, bitopXor, bitopNot.

Perform bitwise operations between strings (http://redis.io/commands/bitop). The Redis command BITOP is split up into bitopAnd, bitopOr, bitopXor, bitopNot.

Perform bitwise operations between strings (http://redis.io/commands/bitop). The Redis command BITOP is split up into bitopAnd, bitopOr, bitopXor, bitopNot.

Perform bitwise operations between strings (http://redis.io/commands/bitop). The Redis command BITOP is split up into bitopAnd, bitopOr, bitopXor, bitopNot.

Decrement the integer value of a key by one (http://redis.io/commands/decr).

Decrement the integer value of a key by the given number (http://redis.io/commands/decrby).

Get the value of a key (http://redis.io/commands/get).

Returns the bit value at offset in the string value stored at key (http://redis.io/commands/getbit).

Get a substring of the string stored at a key (http://redis.io/commands/getrange).

Set the string value of a key and return its old value (http://redis.io/commands/getset).

Increment the integer value of a key by one (http://redis.io/commands/incr).

Increment the integer value of a key by the given amount (http://redis.io/commands/incrby).

Increment the float value of a key by the given amount (http://redis.io/commands/incrbyfloat).

Get the values of all the given keys (http://redis.io/commands/mget).

Set multiple keys to multiple values (http://redis.io/commands/mset).

Set multiple keys to multiple values, only if none of the keys exist (http://redis.io/commands/msetnx).

Set the value and expiration in milliseconds of a key (http://redis.io/commands/psetex).

Set the string value of a key (http://redis.io/commands/set).

Sets or clears the bit at offset in the string value stored at key (http://redis.io/commands/setbit).

Set the value and expiration of a key (http://redis.io/commands/setex).

Set the value of a key, only if the key does not exist (http://redis.io/commands/setnx).

Overwrite part of a string at key starting at the specified offset (http://redis.io/commands/setrange).

Get the length of the value stored in a key (http://redis.io/commands/strlen).

These commands are not implemented, as of now. Library users can implement these or other commands from experimental Redis versions by using the sendRequest function.

• MONITOR (http://redis.io/commands/monitor)
• SYNC (http://redis.io/commands/sync)
• SHUTDOWN (http://redis.io/commands/shutdown)
• DEBUG SEGFAULT (http://redis.io/commands/debug-segfault)

Solution to Exercise

Type of expire inside a transaction:

 expire :: ByteString -> Integer -> RedisTx (Queued Bool)

Type of lindex outside of a transaction:

 lindex :: ByteString -> Integer -> Redis (Either Reply ByteString)