README

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

SSL/TLS Configuration

To enable SSL/TLS connections to your Redis cluster, add the ssl and ssl_opts options to your configuration:

config :my_app, MyApp.Redis,
  host: redis_host,
  port: redis_port,
  pool_size: 16,
  ssl: true,
  ssl_opts: [
    verify: :verify_peer,
    cacertfile: "/path/to/ca.crt"
  ]

Common SSL options include:

• verify: :verify_peer - Enable certificate verification (recommended for production)
• verify: :verify_none - Disable certificate verification (not recommended for production)
• cacertfile: path - Path to CA certificate file
• certfile: path - Path to client certificate file (for mutual TLS)
• keyfile: path - Path to client private key file (for mutual TLS)
• server_name_indication: 'hostname' - SNI hostname for certificate verification

These options are passed directly to Erlang's :ssl.connect/3. See the Erlang SSL documentation for all available options.