guile-redis

guile-redis is a Guile module for the redis key-value data store. It provides most of the commands up to redis 2.6.14 and supports multiple commands and pipelining.

Installation

guile-redis is freely available for download under the terms of the GNU Lesser General Public License version 3 (LGPLv3+).

Download the latest tarball and untar it:

• guile-redis-0.1.0.tar.gz

Then, run the typical sequence:

$ ./configure --prefix=<guile-prefix>
$ make
$ sudo make install

Where <guile-prefix> should preferably be the same as your system Guile installation directory (e.g. /usr).

If everything installed successfully you should be up and running:

$ guile
scheme@(guile-user)> (use-modules (redis))
scheme@(guile-user)>

It might be that you installed guile-redis somewhere differently than your system’s Guile. If so, you need to indicate Guile where to find guile-redis, for example:

$ GUILE_LOAD_PATH=/usr/local/share/guile/site guile

Usage

Procedures

The main interface to the redis server is really simply. It consists on three procedures, the most important one being redis-send which basically sends commands to the server. There are other procedures to create new commands and parse replies that you can also use if you are missing anything.

• (redis-connect #:key host port) : Establish a connection to the redis server at the given host and port and return a redis connection.
  • host : it defaults to 127.0.0.1.
  • port : it defaults to 6379.
• (redis-close connection) : Close the connection to the redis server.
• (redis-send commands) : Send the given list of commands to the redis connection. commands can be a single command or a list of commands. For a list of commands, a list of all the replies is returned.
  • throws a redis-error exception if the redis server returns an error. The exception has the error string as an argument.
  • throws a redis-invalid exception with no argument if server’s answer cannot be parsed (hopefully, this is unlikely to happen).

Commands

redis’ commands are defined as procedures that return a command definition, which internally is stored in a record. The record defines the command name, the parameters and the function to read the command reply. For example,

(append "mykey" "hi!")

is the procedure that creates an APPEND command with parameters “mykey” for the key and “hi!” for the value. Commands are sent by redis-send, so the PING command would be sent like this:

(redis-send (ping))

Most commands defined by guile-redis take the same number of arguments an order as defined in the redis manual. However, there are some important differences to take into account:

• Most of the commands’ arguments are strings.
• Arguments that are clearly numeric must be given as numbers (e.g. increment in the INCRBY command).
• When multiple arguments of the same kind can be given in a redis command, a single list argument is used instead (e.g. MGET keys instead of MGET key [key …]”).
• When commands receive multiple key/value pairs as separate arguments, a list of pairs is to be used instead (e.g. MSET pairs instead of MSET key value [key value], where pairs is a list of cons).

Examples

Let’s now see a few examples so we get a grasp of how guile-redis works.

• Load the module:

  > (use-modules (redis))
      

• Create a connection:

  > (define conn (redis-connect))
      

• Send a single PING command:

  > (redis-send conn (ping))
  "PONG"
      

• Send a couple of PING commands:

  > (redis-send conn (list (ping) (ping)))
  ("PONG" "PONG")
      

• Set a couple of keys:

  > (redis-send conn (mset '(("hello" . "world") ("foo" . "bar"))))
  "OK"
      

• Retrieve the keys just set below:

  > (redis-send conn (mget '("hello" "foo")))
  ("world" "bar")
      

• Finally, close the connection:

  > (redis-close conn)