RedisCluster is an Elixir library that extends the popular Redix library to provide seamless support for Redis Cluster. It handles cluster topology discovery, request routing to the correct nodes, and connection pooling, allowing you to interact with a Redis Cluster with the simplicity of a single Redis instance.

This library is built to be robust and performant, leveraging Redix's efficient Redis protocol implementation and OTP principles for supervision and concurrency.

Features

Automatic Cluster Discovery

Dynamically discovers and maintains the cluster topology, including master and replica nodes.

Smart Command Routing

Intelligently routes commands to the appropriate node based on the key's hash slot, transparently handling MOVED redirections.

Connection Pooling

Manages a configurable pool of connections to each cluster node for optimal performance and resource utilization. See RedisCluster.Pool.

Redix Integration

Built on top of Redix, inheriting its reliability and speed for Redis communication.

Telemetry Support

Emits comprehensive telemetry events for monitoring, metrics, and debugging. See RedisCluster.Telemetry.

Pipeline Operations

Supports pipelining of commands for improved performance with batch operations.

Resharding Awareness

Adapts to cluster changes, such as resharding, by updating its internal slot map.

Multi-Get/Set

Conveniently provides basic get/set across many nodes.

Demo

To try out RedisCluster check out the demo notebook.

Installation

Add redis_cluster to your list of dependencies in mix.exs:

defp deps do
  [
    {:redis_cluster, "~> 0.7.0"},
  ]
end

Configuration

There are two ways to configure RedisCluster: a robust, production-ready solution, or a quick and easy solution.

Production Ready Config

First, you need to create a module for your Redis use:

defmodule MyApp.Redis do
  use RedisCluster, otp_app: :my_app
end

Then in your config/runtime.exs you can set the details for your environment:

redis_host = System.get_env("REDIS_HOST", "localhost")
redis_port = System.get_env("REDIS_PORT", "6379") |> String.to_integer()

config :my_app, MyApp.Redis,
  host: redis_host,
  port: redis_port,
  pool_size: 16

Ideally the host should be a "configuration endpoint" as AWS ElastiCache calls it. The configuration endpoint picks a random node to connect to. This ensures one node isn't being hit every time the cluster needs to be discovered.

Quick and Easy Config

For simpler cases, such as with testing and Livebook, you can inline your config.

defmodule MyApp.Redis do
  use RedisCluster, otp_app: :none,
    host: "localhost",
    port: 6379,
    pool_size: 3
end