A Racket Redis client

6.0.0.3

A Racket Redis client

Stephen Chang <stchang@racket-lang.org>

Marc Burns <m4burns@csclub.uwaterloo.ca>

(require redis)

package: redis

A Redis client for Racket.

1 Getting a Connection: Connection Pools

To connect to a Redis database, first create a connection pool, then lease a connection from the pool.

procedure
(redis-connection-pool? pool) → bool/c
pool : any/c

Indicates whether pool is a Redis connection pool.

procedure
(redis-connection? conn) → bool/c
conn : any/c

Indicates whether conn is a Redis connection.

procedure
(make-connection-pool [ #:host host
#:port port
#:max-connections max
#:max-idle max-idle])
→ redis-connection-pool?
  host : string? = "127.0.0.1"
  port : (integer-in 1 65535) = 6379
  max : exact-nonnegative-integer? = 100
  max-idle : exact-nonnegative-integer? = 10

Makes a Redis connection pool with the given parameters.

A connection pool maintains one connection per thread. Thus, a new connection is created on the first call to connection-pool-lease in a thread. Calling connection-pool-lease a second time from the same thread will return the same connection as the first lease call (as long as the connection was not returned in between).

procedure
(kill-connection-pool pool) → void?
pool : redis-connection-pool?

Kills a connection pool. All the connections are disconnected.

procedure
(connection-pool-lease [pool]) → redis-connection?
pool : redis-connection-pool? = (current-redis-pool)

Leases a connection from the specified pool. current-redis-pool is used if no pool is given.

The pool maintains one connection per thread. Therefore, if no connection exists for the current thread, then a new connection is created. If a connection already exists for the current thread, then that connection is returned.

Examples:

> (define pool (make-connection-pool))
> (eq? (connection-pool-lease pool) (connection-pool-lease pool))
#t
> (eq-hash-code (connection-pool-lease pool))
30889
> (define ch (make-async-channel))
> (thread (lambda () (async-channel-put ch (eq-hash-code (connection-pool-lease pool)))))
#<thread>
> (async-channel-get ch)
30915

procedure
(connection-pool-return conn [pool]) → void?
conn : redis-connection?
pool : redis-connection-pool? = (current-redis-connection)

Returns a connection to the specified pool. current-redis-pool is used if no pool is given.

UNSUBSCRIBE, PUNSUBSCRIBE, and UNWATCH are called on the channel before it’s returned to the pool.

Returning an already returned pool does nothing.

parameter
(current-redis-pool) → redis-connection-pool?
(current-redis-pool pool) → void?
pool : redis-connection-pool?
= #f

Represents the current connection pool.

The parameter is initially false, but gets set if send-cmd or send-cmd/no-reply is called with no connection argument.

2 Sending Commands: General

procedure
(send-cmd [ #:rconn conn
#:host host
#:port port]
cmd
arg ...) → any/c
  conn : bool/c = #f
  host : string? = "127.0.0.1"
  port : (integer-in 1 6535) = 6379
  cmd : (or/c string? bytes? symbol?)
  arg : (or/c string? bytes? symbol? number?)

Sends the given command, with the given arguments, using the given connection parameters. Waits for a reply from Redis and returns it.

The conn connection is used if given.
Otherwise a new connection is leased from the current-redis-pool.
If no pool exists, then a new one is created using the given host and port and set as the current-redis-pool.

A command can either be a string, a byte string, or a symbol. An arguments can take the form of a string, byte string, symbol, or number.

Examples:

> (define pool (make-connection-pool))
> (define conn (connection-pool-lease pool))
> (send-cmd #:rconn conn 'dbsize)
2024

procedure
(send-cmd/no-reply [ #:rconn conn
#:host host
#:port port]
cmd
arg ...) → redis-connection?
  conn : bool/c = #f
  host : string? = "127.0.0.1"
  port : (integer-in 1 6535) = 6379
  cmd : (or/c string? bytes? symbol?)
  arg : (or/c string? bytes? symbol? number?)

Same as send-cmd except does not wait for a reply. The connection used to send the command is returned.

procedure
(get-reply conn) → any/c
conn : (connection-pool-lease (current-redis-pool))

Gets a reply from Redis using the given connection.

Examples:

> (define pool (make-connection-pool))
> (define conn (connection-pool-lease pool))
> (send-cmd #:rconn conn 'set 'testing 101)
"OK"
> (get-reply (send-cmd/no-reply #:rconn conn 'get 'testing))
#"101"

procedure
(get-reply-evt conn) → evt?
conn : (connection-pool-lease (current-redis-pool))

Returns an event that is ready for synchronization when the given connection has a reply.

3 Sending Commands: Specific

Functions for specific Redis commands are also defined. These functions have the same arguments as send-cmd, minus the cmd argument.

Check the Redis documentation for what return values to expect.

The following functions are available: APPEND DEL GETSET MGET SETRANGE STRLEN EXISTS MSETNX RENAMENX GET GETRANGE RANDOMKEY SET MSET RENAME DUMP RESTORE SETBIT GETBIT BITCOUNT BITOP LPUSH LPUSHX LRANGE LLEN LREM RPUSH RPUSHX LINDEX LPOP RPOP RPOPLPUSH BLPOP BRPOP BRPOPL PUSH LINSERT LSET LTRIM HDEL HGETALL HINCRBY HINCRBYFLOAT HMGET HVALS HMSET HSET HEXISTS HSETNX HGET SADD SCARD SDIFF SDIFFSTORE SINTER SINTERSTORE SMEMBERS SREM SUNION SUNIONSTORE SISMEMBER SMOVE SPOP SRANDMEMBER ZADD ZCARD ZCOUNT ZINCRBY ZINTERSTORE ZRANGE ZRANGEBYSCORE ZREM ZREMRANGEBYRANK ZREMRANGEBYSCORE ZREVRANGE ZREVRANGEBYSCORE ZUNIONSTORE ZRANK ZREVRANK ZSCORE DECR DECRBY INCR INCRBY INCRBYFLOAT HKEYS HLEN EXPIRE EXPIREAT PERSIST PEXPIRE PEXPIREAT TTL PTTL MULTI DISCARD WATCH UNWATCH EXEC SUBSCRIBE UNSUBSCRIBE PSUBSCRIBE PUNSUBSCRIBE PUBLISH DBSIZE ECHO FLUSHALL FLUSHDB KEYS PING TIME TYPE AUTH QUIT SELECT
The following GET variations, which return different types of results, are defined: GET/str GET/num GETRANGE/str GET/list GET/set GET/hash GET/heap
Examples:
> (SET 'testing2 101)
#t
> (GET 'testing2)
#"101"
> (GET/str 'testing2)
"101"
> (GET/num 'testing2)
101
The following SET variations, which allow different types of input, are defined: SET/list SET/set SET/hash SET/heap
The following hash variations are defined: HGET/str
The following POP variations are defined: POP/list
(do-MULTI c ...) wraps MULTI and EXEC around the given commands.
The following functions are not currently available:
- SETNX, SETEX, PSETEX (use SET + options instead)
- BGREWRITEAOF BGSAVE INFO LASTSAVE MIGRATE MONITOR MOVE SAVE SHUTDOWN SLAVEOF SLOWLOG SYNC CLIENT CONFIG DEBUG EVAL EVALSHA SCRIPT

4 PubSub-specific Connections

To help manage pubsub patterns, this client supports pubsub-specific connections.

procedure
(pubsub-connection? conn) → bool/c
conn : any/c

Indicates whether a connection is a pubsub-specific connection.

procedure
(lease-pubsub-conn [pool]) → pubsub-connection?
pool : redis-connection-pool? = (current-redis-pool)

Leases a pubsub-specific connection from the pool.

Creates a thread that monitors the connection for (p)subscribe and (p)unsubscribe messages. Currently prints (un)subscription notices to stdout.

A custodian is created to manage the threads of the pubsub connection.

procedure
(make-subscribe-chan conn
key
[ pool
#:psubscribe psub?]) → async-channel?
  conn : pubsub-connection?
  key : (or/c string? symbol?)
  pool : redis-connection-pool? = (current-redis-connection)
  psub? : bool/c = #f

(P)Subscribes to a specified key or pattern. Returns an async-channel where subscription messages are sent.

Creates a thread that monitors the connection for subscription messages.

To (p)unsubscribe from a subscription, use send-cmd or UNSUBSCRIBE, or PUNSUBSCRIBE with the appropriate pubsub-specific connection.

Examples:

> (define pool (make-connection-pool))
> (define pubsubconn (lease-pubsub-conn pool))
> (redis-connection? pubsubconn)
#t
> (pubsub-connection? pubsubconn)
#t
> (define foo-chan (make-subscribe-chan pubsubconn 'foo pool))
> (define bar-chan (make-subscribe-chan pubsubconn 'bar pool))
> (sleep 0.1)
SUBSCRIBE (#1) foo confirmed.
SUBSCRIBE (#2) bar confirmed.
> (thread (λ () (PUBLISH 'foo "Hello")))
#<thread>
> (thread (λ () (PUBLISH 'bar "World!")))
#<thread>
> (async-channel-get foo-chan)
#"Hello"
> (async-channel-get bar-chan)
#"World!"

procedure
(return-pubsub-conn conn [pool]) → void?
conn : pubsub-connection?
pool : redis-connection-pool? = (current-redis-connection)

Returns the pubsub-specific connection to the pool.

Calls custodian-shutdown-all on the custodian associated with the connection, killing all the threads associated with the connection.

5 Errors

procedure
(exn:fail:redis? exn) → bool/c
exn : any/c

Identifies a Redis exception.

procedure
(redis-error msg) → exn:fail:redis?
msg : string?

Raises a Redis exception with the given message.

6 Raw Connection

NOTE: It’s not recommended to use the forms in this section.

The functions in this section enable basic connection and disconnection from a Redis database. The user is responsible for managing the connection.

In particular, using the same connection in different threads may require some synchronization when sending commands and checking replies.

procedure
(connect [host port]) → redis-connection?
host : string? = "127.0.0.1"
port : (integer-in 1 65535) = 6379

Connects to a Redis database at host host and port port. If no host and port is provided, then localhost and 6379 are used, respectively.

procedure
(disconnect conn) → void?
conn : redis-connection?

Disconnects a Redis connection.

struct
(struct redis-connection (in out owner pubsub?))
  in : input-port?
  out : output-port?
  owner : thread?
  pubsub? : bool/c

Redis connection data structure. The owner field is mutable. The pubsub? field is mutable and optional.

1	Getting a Connection: Connection Pools
2	Sending Commands: General
3	Sending Commands: Specific
4	Pub Sub-specific Connections
5	Errors
6	Raw Connection