[![Build Status](](
[![]( "WTFPL Licensed")](
[![Hex version]( "Hex version")](

# ex_sider

Elixir <-> Redis datastructure adapter

## setup

In your `mix.exs` file:

def deps do
  [{:ex_sider, "~> 0.1"},
   # the following is only needed if using a Redix pool:
   {:poolboy, "~> 1.5"},
   {:redix, ">= 0.0.0"}]

In your config file:

config ex_sider,
  redis_adapter: MyApp.RedixPool # currently the only supported adapter, see below

# also make sure to configure the redis adapter correctly

## use case: redis interface

This can be used (potentially, if necessary) with different Redis adapters, but for
now I'll stick with [Redix]( From the example
we can create a new RedixPool e.g. like so:

# Copied from
defmodule MyApp.RedixPool do
  use Supervisor

  @redis_connection_params host: "localhost", password: ""

  def start_link do
    Supervisor.start_link(__MODULE__, [])

  def init([]) do
    pool_opts = [
      name: {:local, :redix_poolboy},
      worker_module: Redix,
      size: 10,
      max_overflow: 5,

    children = [
      :poolboy.child_spec(:redix_poolboy, pool_opts, @redis_connection_params)

    supervise(children, strategy: :one_for_one, name: __MODULE__)

  def command(command) do
    :poolboy.transaction(:redix_poolboy, &Redix.command(&1, command))

  def pipeline(commands) do
    :poolboy.transaction(:redix_poolboy, &Redix.pipeline(&1, commands))

We now update our `ex_sider` config with the correct module name (see above), and also make sure that the RedixPool is started when we start our Application:

defmodule MyApp do
  use Application

  def start(_type, _args) do
    import Supervisor.Spec, warn: false

    children = [
      # ...
      supervisor(MyApp.RedixPool, [[]]),
      # ...

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)

Finally, after this setup, we can use the `ex_redis` modules like any normal Map, Set or List, e.g.:
(Actually, take this with a grain of salt: Since this is an ongoing effort, interfaces might be incomplete - but please request specific improvements or contribute!)

redis_set ="my-set-name")

# by default, ex_sider uses a 'binary' mode, where it pipes all
# terms given to it into :erlang.term_to_binary/1, and all terms
# that it retrieves through :erlang.binary_to_term/1
data = ["surprisingly", :we_can_store, "all kinds of data!!!", 1, 1, 1]

# we can use for comprehensions:
for x <- data, into: redis_set, do: x

# and any kind of Enum operation, e.g.:
# => ["surprisingly", :we_can_store, "all kinds of data!!!", 1]
# note the missing 1's because we are using a RedisSet

## use case directly dump data into a redis hash

_Note that this functionality might be made more implicit in the future by implementing the Access, Enumerable and Collectable functionality_

redis_hash ="my-hash-name") # initializes the redishash with the korrekt key
RedisHash.push(redis_hash, %{"some_value" => 123, "abc" => :abc}) # note: keys must be binaries!
# => :ok
# => %{"some_value" => 123, "abc" => :abc}

## use case: simple local & redis cache

Essentially, this is a RedisHash under the hood, but caches data and changes locally.
It can be used to remotely cache elixir maps with simple push/pull sync semantics and no strategy for conflict resolution.
The use case for this is to store (also Erlang-Node independant) the state of a process that will only ever be existing once in the cluster, but might be restarted often.

redis_cache ="my-hash-name") # pulls the existing state from the repo automatically if any
redis_cache = RedisCache.merge(redis_cache, %{"some" => :values, "that_i_want" => "to store"}) # does a local caching
# => true

redis_cache = RedisCache.push(redis_cache) # pushes the local changes

# => false

## remarks

**Mutability** - All datastructures implemented here are mutable, that means, that every operation that changes any part of them (i.e. writes data) will change for all parts of the application that have a reference to this datastructure. This is because we actually only implement a thin adapter layer based on Elixir Protocols, that interface with redis in order to store data.

**Binary Data** - Any data will, by default, be stored as an erlang term that is being converted to binary beforehand. That means that - in case you access Redis without `ex_sider` - that you will have to call `:erlang.binary_to_term` on anything that you retrieve from it. If that is not an option for you, simply disable binary mode when initialising the datastructure:

# to disable binary mode (only values that are binaries can be used then, like e.g. elixir strings)
redis_set ="my-set-name", binary_mode: false)

**This Project** - This project is supposed to be a helper to make interfacing with Redis simpler. It is by no means: complete, perfectly documented or otherwise done. Any help is appreciated, just fork & PR, create issues etc. Business as usual.

## is it any good?

bien sûr.