wangdvp/redis_cluster

A redis cluster ruby client gem

RedisCluster

Support: Ruby 2.0+

Redis Cluster is a Redis configuration that allows data to be automatically sharded across a number of different nodes. You can find its main documentation at https://redis.io/topics/cluster-tutorial.

redis-rb, the most common Redis gem for Ruby, doesn't offer Redis Cluster support. This gem works in conjunction with redis-rb to add the missing functionality. It's based on antirez's prototype reference implementation (which is not maintained).

Installation

Add it to your Gemfile:

gem 'redis_cluster'

Usage

Initialize RedisCluster with an array of Redis Cluster host nodes:

rs = RedisCluster.new([
  {host: '127.0.0.1', port: 7000},
  {host: '127.0.0.1', port: 7001}
])
rs.set "test", 1
rs.get "test"

The library will issue the CLUSTER SLOTS command to configured hosts it it receives a MOVED response, so it's safe to configure it with only a subset of the total nodes in the cluster.

Other options

Most options are forwarded onto underlying Redis clients. If for example masterauth and requirepass are enabled, the password can be set like this:

RedisCluster.new(hosts, password: 'password')

Standalone Redis

If initialized with a host hash instead of an array, the library will assume that it's operating on a standalone Redis, and cluster functionality will be disabled:

rs = RedisCluster.new({host: '127.0.0.1', port: 7000})

When configured with an array of hosts the library normally requires that they be part of a Redis Cluster, but that check can be disabled by setting force_cluster: false. This may be useful for development or test environments where a full cluster isn't available, but where a standalone Redis will do just as well.

rs = RedisCluster.new([
  {host: '127.0.0.1', port: 7000},
], force_cluster: false)

Logging

A logger can be specified with the logger option. It should be compatible with the interface of Ruby's Logger from the standard library.

require 'logger'
logger = Logger.new(STDOUT)
logger.level = Logger::WARN
RedisCluster.new(hosts, logger: logger)

KEYS

The KEYS command will scan all nodes:

rs.keys 'test*'

Pipelining, MULTI

There is limited support for pipelining and MULTI:

rs.pipelined do
  rs.set "{foo}one", 1
  rs.set "{foo}two", 2
end

Note that all keys used in a pipeline must map to the same Redis node. This is possible through the use of Redis Cluster "hash tags" where only the section of a key name wrapped in {} when calculating a key's hash.

EVAL, EVALSHA, SCRIPT

EVAL and EVALSHA must only rely on keys that map to a single slot (again, possible with hash tags). KEYS should be used to retrieve keys in Lua scripts.

rs.eval "return redis.call('get', KEYS[1]) + ARGV[1]", [:test], [3]
rs.evalsha '727fc2fb7c0f11ec134d998654e3dadaacf31a97', [:test], [5]

# Even if a Lua script doesn't need any keys or argvs, you'll still need to
specify a dummy key.
rs.eval "return 'hello redis!'", [:foo]

SCRIPT commands will run on all nodes:

# script commands will run on all nodes
rs.script :load, "return redis.call('get', KEYS[1])"
rs.script :exists, '4e6d8fc8bb01276962cce5371fa795a7763657ae'
rs.script :flush

Development

Clone the repository and then install dependencies:

bin/setup

Run tests:

rake spec

bin/console will bring up an interactive prompt for other experimentation.

Releases

To release a new version, update the version number in version.rb and run bundle exec rake release. This will create a Git tag for the version, push Git commits and tags to GitHub, and push the .gem file to Rubygems.

The gem can be installed locally with bundle exec rake install.

Benchmark test

Benchmark.bm do |x|
  x.report do
    1.upto(100_000).each do |i|
      redis.set "test#{i}", i
    end
  end
  x.report do
    1.upto(100_000).each do |i|
      redis.get "test#{i}"
    end
  end
  x.report do
    1.upto(100_000).each do |i|
      redis.del "test#{i}"
    end
  end
end

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.