yar

Yet another Redis client for Elixir

Monthly Downloads: 3

Programming language: Elixir

License: MIT License

Tags: ORM And Datamapping    

Latest version: v0.1.0

README

YAR

Yet Another Redis client for Elixir

YAR is a Redis client written in Elixir. It is not a wrapper around the excellent Erlang client eredis, it is implemented from scratch in Elixir using elixir-socket (which is itself a wrapper around Erlang's gen_tcp) for TCP/IP communication.

This project is probably not ready for production, though I would greatly appreciate any feedback and bug reports.

If you are looking for a solid Elixir Redis client, check out exredis. exredis is a wrapper around eredis, which is an Erlang Redis client that has been around for quite some time.

Usage

Create a new Redis connection process with YAR.connect/2 and then use YAR.execute/2 to execute raw Redis commands.

{:ok, redis} = YAR.connect("localhost", 6379)
"PONG" = YAR.execute(redis, "PING")
"OK" = YAR.execute(redis, "SET FOO 1")
2 = YAR.execute(redis, "INCR FOO")
"2" = YAR.execute(redis, "GET FOO")
"OK" = YAR.execute(redis, "SET BAR BAZ")
"OK" = YAR.execute(redis, ["SET", "BAR", "BAZ"])
["2", "BAZ"] = YAR.execute(redis, "MGET FOO BAR")
{:error, "unknown command 'SUP'"} = YAR.execute(redis, "SUP")

YAR.connect/2 takes host and port as arguments, with default values of "localhost" and 6379. {:ok, redis} = Yar.connect should connect to a default local instance of redis-server on most installations. Multiple connections can be made by simply calling Yar.connect/2 multiple times.

In theory, YAR supports arbitrary Redis commands via YAR.execute/2. All of the basic return types should be supported.

YAR.execute/2 is synchronous. The underlying connection uses elixir-socket and stores the connection information in a GenServer.

The list form of execute should be favored for performance reasons. That is, YAR.execute(redis, ["GET", "FOO"]) is slightly more performant than YAR.execute(redis, "GET FOO").

Helpers

YAR has built-in helpers for some Redis commands.

"OK" == YAR.set(c, "foo", "bar")
"bar" == YAR.get(c, "foo")
# note keys/values are interleaved
"OK" == YAR.mset(c, ["foo", 1, "bar", 2])
["1", "2"] == YAR.mget(c, ["foo"], ["bar"])

Pipelining

YAR supports simple Redis pipelining via YAR.pipeline/2. The second argument is a list of commands. The responses are returned as a list in order corresponding to the commands.

["OK", "PING"] == YAR.pipeline(redis, [["SET", "FOO", "42"], ["PING"]])
["42", "OK"] == YAR.pipeline(redis, [["GET", "FOO"], ["SET", "FOO", "1"]])

Pubsub

YAR supports simple Redis subscribing via YAR.subscribe/4. The first argument is a pid to receive messages, the second argument is a list of routing keys, the third and fourth arguments are the Redis host and port, respectively (default "localhost" and 5379). Messages are delivered as tuples where the first element is :yarsub and the second argument is the message string.

{:ok, subscriber_pid} = YAR.subscribe(self, ["foo"])
YAR.execute(redis, ["PUBLISH", "foo", "hullo"])
flush # => {:yarsub, "hullo"}

Testing

Launch a Redis server instance on port 5000 (redis-server -- port 5000) then run mix test.

CAUTION - The test executes FLUSHALL between test cases. DO NOT test on a production server! If you must, take care that no data is kept on a Redis instance on port 5000, or change the test port in test/yar_test.exs.