NebulexRedisAdapter v1.1.0 NebulexRedisAdapter View Source

Nebulex adapter for Redis.

This adapter is implemented using Redix, a Redis driver for Elixir.

NebulexRedisAdapter brings with three setup alternatives: standalone (default) and two more for cluster support:

  • Standalone - This is the default mode, the adapter establishes a pool of connections against a single Redis node.

  • Redis Cluster - Redis can be setup in distributed fashion by means of Redis Cluster, which is a built-in feature since version 3.0 (or greater). This adapter provides the :redis_cluster mode to setup Redis Cluster from client-side automatically and be able to use it transparently.

  • Built-in client-side cluster based on sharding - This adapter provides a simple client-side cluster implementation based on Sharding as distribution model and consistent hashing for node resolution.

Shared Options

In addition to Nebulex.Cache shared options, this adapters supports the following options:

  • :mode - Defines the mode Redis will be set up. It can be one of the next values: :standalone | :cluster | :redis_cluster. Defaults to :standalone.

  • :pool_size - number of connections to keep in the pool. Defaults to System.schedulers_online().

  • :conn_opts - Redis client options (Redix options in this case). For more information about the options (Redis and connection options), please check out Redix docs.

Standalone Example

We can define our cache to use Redis adapter as follows:

defmodule MyApp.RedisCache do
  use Nebulex.Cache,
    otp_app: :nebulex,
    adapter: NebulexRedisAdapter
end

The configuration for the cache must be in your application environment, usually defined in your config/config.exs:

config :my_app, MyApp.RedisCache,
  conn_opts: [
    host: "127.0.0.1",
    port: 6379
  ]

Redis Cluster Options

In addition to shared options, :redis_cluster mode supports the following options:

  • :master_nodes - The list with the configuration for the Redis cluster master nodes. The configuration for each master nodes contains the same options as :conn_opts. The adapter traverses the list trying to establish connection at least with one of them and get the cluster slots to finally setup the Redis cluster from client side properly. If one fails, the adapter retries with the next in the list, that's why at least one master node must be set.

  • :conn_opts - Same as shared options (optional). The :conn_opts will be applied to each connection pool with the cluster (they will override the host and port retrieved from cluster slots info). For that reason, be careful when setting :host or :port options since they will be used globally and can cause connection issues. Normally, we add here the desired client options except :host and :port. If you have a cluster with the same host for all nodes, in that case make sense to add also the :host option.

  • :pool_size - Same as shared options (optional). It applies to all cluster slots, meaning all connection pools will have the same size.

Redis Cluster Example

config :my_app, MayApp.RedisClusterCache,
  mode: :redis_cluster,
  master_nodes: [
    [
      host: "127.0.0.1",
      port: 7000
    ],
    [
      url: "redis://127.0.0.1:7001"
    ],
    [
      url: "redis://127.0.0.1:7002"
    ]
  ],
  conn_opts: [
    # Redix options, except `:host` and `:port`; unless we have a cluster
    # of nodes with the same host and/or port, which doesn't make sense.
  ]

Client-side Cluster Options

In addition to shared options, :cluster mode supports the following options:

  • :nodes - The list of nodes the adapter will setup the cluster with; a pool of connections is established per node. The :cluster mode enables resilience, be able to survive in case any node(s) gets unreachable. For each element of the list, we set the configuration for each node, such as :conn_opts, :pool_size, etc.

Clustered Cache Example

config :my_app, MayApp.ClusteredCache,
  mode: :cluster,
  nodes: [
    node1: [
      pool_size: 10,
      conn_opts: [
        host: "127.0.0.1",
        port: 9001
      ]
    ],
    node2: [
      pool_size: 4,
      conn_opts: [
        url: "redis://127.0.0.1:9002"
      ]
    ],
    node3: [
      conn_opts: [
        host: "127.0.0.1",
        port: 9003
      ]
    ]
  ]

Queryable API

The queryable API is implemented by means of KEYS command, but it has some limitations we have to be aware of:

  • Only strings (String.t()) are allowed as query parameter.

  • Only keys can be queried. Therefore, :return option has not any affects, since keys are always returned. In the case you want to return the value for the given key pattern (query), you can perform get_many with the returned keys.

Examples

iex> MyApp.RedisCache.set_many(%{
...>   "firstname" => "Albert",
...>   "lastname" => "Einstein",
...>   "age" => 76
...> })
:ok

iex> MyApp.RedisCache.all("**name**")
["firstname", "lastname"]

iex> MyApp.RedisCache.all("a??")
["age"]

iex> MyApp.RedisCache.all()
["age", "firstname", "lastname"]

iex> stream = TestCache.stream("**name**")
iex> stream |> Enum.to_list()
["firstname", "lastname"]

# get the values for the returned queried keys
iex> "**name**" |> MyApp.RedisCache.all() |> MyApp.RedisCache.get_many()
%{"firstname" => "Albert", "lastname" => "Einstein"}

For more information about the usage, check out Nebulex.Cache as well.