Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dantswain/yar

Yet another Redis client for Elixir
https://github.com/dantswain/yar

Last synced: 3 months ago
JSON representation

Yet another Redis client for Elixir

Awesome Lists containing this project

README 

        
YAR

===



Yet Another Redis client for Elixir



YAR is a [Redis](http://redis.io) client written in Elixir.  It is

not a wrapper around the excellent Erlang client

[eredis](https://github.com/wooga/eredis), it is implemented

from scratch in Elixir using

[elixir-socket](https://github.com/meh/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](https://github.com/artemeff/exredis).

exredis is a wrapper around [eredis](https://github.com/wooga/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.



```elixir

{: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](https://github.com/meh/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.



```elixir

"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](http://redis.io/topics/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.



```elixir

["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](http://redis.io/topics/pubsub)

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.



```elixir

{: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`.