README.md in redis_cluster-0.3.0 vs README.md in redis_cluster-0.3.1
- old
+ new
@@ -1,83 +1,162 @@
# RedisCluster
-First see: [https://redis.io/topics/cluster-tutorial](https://redis.io/topics/cluster-tutorial)
+Support: Ruby 2.0+
-RedisCluster for ruby is rewrited from [https://github.com/antirez/redis-rb-cluster](https://github.com/antirez/redis-rb-cluster)
+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`](https://github.com/redis/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](https://github.com/antirez/redis-rb-cluster) (which
+is not maintained).
## Installation
-Add this line to your application's Gemfile:
+Add it to your `Gemfile`:
```ruby
gem 'redis_cluster'
```
-And then execute:
+## Usage
- $ bundle
+Initialize `RedisCluster` with an array of Redis Cluster host nodes:
-Or install it yourself as:
+```ruby
+rs = RedisCluster.new([
+ {host: '127.0.0.1', port: 7000},
+ {host: '127.0.0.1', port: 7001}
+])
+rs.set "test", 1
+rs.get "test"
+```
- $ gem install redis_cluster
+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.
-## Usage
+### Other options
-First you need to configure redis cluster with some nodes! Please see: [https://redis.io/topics/cluster-tutorial](https://redis.io/topics/cluster-tutorial)
+Most options are forwarded onto underlying `Redis` clients. If for example
+`masterauth` and `requirepass` are enabled, the password can be set like this:
```ruby
-# Don't need all, gem can auto detect all nodes, and process failover if some master nodes down
-hosts = [{host: '127.0.0.1', port: 7000}, {host: '127.0.0.1', port: 7001}]
-rs = RedisCluster.new hosts
-rs.set "test", 1
-rs.get "test"
+RedisCluster.new(hosts, password: 'password')
```
-At development environment with single redis node, you can set hosts a hash value: {host: 'xx', port: 6379}.
+### Standalone Redis
-If masterauth & requirepass configed, you can initialize below:
+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:
+
```ruby
-RedisCluster.new hosts, password: 'password'
+rs = RedisCluster.new({host: '127.0.0.1', port: 7000})
```
-now support keys command with scanning all nodes:
+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.
+
```ruby
+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.
+
+```ruby
+require 'logger'
+logger = Logger.new(STDOUT)
+logger.level = Logger::WARN
+RedisCluster.new(hosts, logger: logger)
+```
+
+### `KEYS`
+
+The `KEYS` command will scan all nodes:
+
+```ruby
rs.keys 'test*'
```
-limited support commands: pipelined, multi
+### Pipelining, `MULTI`
+
+There is limited support for pipelining and `MULTI`:
+
```ruby
-# Only support pipeline commands to one redis node once
-# You must ensure keys at one slot: use same key or hash tags
-# If you don't, not raise any errors now
rs.pipelined do
rs.set "{foo}one", 1
rs.set "{foo}two", 2
end
```
-script, eval, evalsha
+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.
+
```ruby
+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:
+
+```ruby
# script commands will run on all nodes
rs.script :load, "return redis.call('get', KEYS[1])"
rs.script :exists, '4e6d8fc8bb01276962cce5371fa795a7763657ae'
rs.script :flush
+```
-# eval/evalsha must executed at one node with hash tag keys in same slot
-# and must use KEYS to fetch keys in lua script
-rs.eval "return redis.call('get', KEYS[1]) + ARGV[1]", [:test], [3]
-rs.evalsha '727fc2fb7c0f11ec134d998654e3dadaacf31a97', [:test], [5]
+## Development
-# if lua script don't depend on any keys and argvs, you also need execute with a key
-rs.eval "return 'hello redis!'", [:foo]
+Clone the repository and then install dependencies:
+
+```sh
+bin/setup
```
-## Benchmark test
+Run tests:
+```sh
+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
+
```ruby
Benchmark.bm do |x|
x.report do
1.upto(100_000).each do |i|
redis.set "test#{i}", i
@@ -94,21 +173,20 @@
end
end
end
```
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/zhchsf/redis_cluster. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+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](http://contributor-covenant.org) code
+of conduct.
-
## License
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).
+<!--
+# vim: set tw=79:
+-->