redis 3.3.3 → 5.0.5

data/README.md

@@ -1,46 +1,17 @@
-# redis-rb [![Build Status][travis-image]][travis-link] [![Inline docs][inchpages-image]][inchpages-link]
+# redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][inchpages-image]][inchpages-link]
 
-[travis-image]: https://secure.travis-ci.org/redis/redis-rb.png?branch=master
-[travis-link]: http://travis-ci.org/redis/redis-rb
-[travis-home]: http://travis-ci.org/
-[inchpages-image]: http://inch-ci.org/github/redis/redis-rb.png
-[inchpages-link]: http://inch-ci.org/github/redis/redis-rb
+A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still providing an idiomatic interface.
 
-A Ruby client library for [Redis][redis-home].
-
-[redis-home]: http://redis.io
-
-A Ruby client that tries to match Redis' API one-to-one, while still
-providing an idiomatic interface. It features thread-safety, client-side
-sharding, pipelining, and an obsession for performance.
-
-## Upgrading from 2.x to 3.0
-
-Please refer to the [CHANGELOG][changelog-3.0.0] for a summary of the
-most important changes, as well as a full list of changes.
-
-[changelog-3.0.0]: https://github.com/redis/redis-rb/blob/master/CHANGELOG.md#300
+See [RubyDoc.info][rubydoc] for the API docs of the latest published gem.
 
 ## Getting started
 
-To install **redis-rb**, run the following command:
-
-```
-  gem install redis
-```
-
-Or if you are using **bundler**, add
+Install with:
 
 ```
-  gem 'redis', '~>3.2'
+$ gem install redis
 ```
 
-to your `Gemfile`, and run `bundle install`
-
-As of version 2.0 this client only targets Redis version 2.0 and higher.
-You can use an older version of this client if you need to interface
-with a Redis instance older than 2.0, but this is no longer supported.
-
 You can connect to Redis by instantiating the `Redis` class:
 
 ```ruby
@@ -54,31 +25,34 @@ listening on `localhost`, port 6379. If you need to connect to a remote
 server or a different port, try:
 
 ```ruby
-redis = Redis.new(:host => "10.0.1.1", :port => 6380, :db => 15)
+redis = Redis.new(host: "10.0.1.1", port: 6380, db: 15)
 ```
 
 You can also specify connection options as a [`redis://` URL][redis-url]:
 
 ```ruby
-redis = Redis.new(:url => "redis://:p4ssw0rd@10.0.1.1:6380/15")
+redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15")
 ```
 
-[redis-url]: http://www.iana.org/assignments/uri-schemes/prov/redis
-
-By default, the client will try to read the `REDIS_URL` environment variable
-and use that as URL to connect to. The above statement is therefore equivalent
-to setting this environment variable and calling `Redis.new` without arguments.
+The client expects passwords with special chracters to be URL-encoded (i.e.
+`CGI.escape(password)`).
 
 To connect to Redis listening on a Unix socket, try:
 
 ```ruby
-redis = Redis.new(:path => "/tmp/redis.sock")
+redis = Redis.new(path: "/tmp/redis.sock")
 ```
 
 To connect to a password protected Redis instance, use:
 
 ```ruby
-redis = Redis.new(:password => "mysecret")
+redis = Redis.new(password: "mysecret")
+```
+
+To connect a Redis instance using [ACL](https://redis.io/topics/acl), use:
+
+```ruby
+redis = Redis.new(username: 'myname', password: 'mysecret')
 ```
 
 The Redis class exports methods that are named identical to the commands
@@ -86,8 +60,6 @@ they execute. The arguments these methods accept are often identical to
 the arguments specified on the [Redis website][redis-commands]. For
 instance, the `SET` and `GET` commands can be called like this:
 
-[redis-commands]: http://redis.io/commands
-
 ```ruby
 redis.set("mykey", "hello world")
 # => "OK"
@@ -96,24 +68,42 @@ redis.get("mykey")
 # => "hello world"
 ```
 
-All commands, their arguments and return values are documented, and
-available on [rdoc.info][rdoc].
+All commands, their arguments, and return values are documented and
+available on [RubyDoc.info][rubydoc].
+
+## Connection Pooling and Thread safety
+
+The client does not provide connection pooling. Each `Redis` instance
+has one and only one connection to the server, and use of this connection
+is protected by a mutex.
+
+As such it is heavilly recommended to use the [`connection_pool` gem](https://github.com/mperham/connection_pool), e.g.:
 
-[rdoc]: http://rdoc.info/github/redis/redis-rb/
+```ruby
+module MyApp
+  def self.redis
+    @redis ||= ConnectionPool::Wrapper.new do
+      Redis.new(url: ENV["REDIS_URL"])
+    end
+  end
+end
+
+MyApp.redis.incr("some-counter")
+```
 
 ## Sentinel support
 
-The client is able to perform automatic failovers by using [Redis
+The client is able to perform automatic failover by using [Redis
 Sentinel](http://redis.io/topics/sentinel).  Make sure to run Redis 2.8+
 if you want to use this feature.
 
 To connect using Sentinel, use:
 
 ```ruby
-SENTINELS = [{:host => "127.0.0.1", :port => 26380},
-             {:host => "127.0.0.1", :port => 26381}]
+SENTINELS = [{ host: "127.0.0.1", port: 26380 },
+             { host: "127.0.0.1", port: 26381 }]
 
-redis = Redis.new(:url => "redis://mymaster", :sentinels => SENTINELS, :role => :master)
+redis = Redis.new(url: "redis://mymaster", sentinels: SENTINELS, role: :master)
 ```
 
 * The master name identifies a group of Redis instances composed of a master
@@ -130,21 +120,19 @@ but a few so that if one is down the client will try the next one. The client
 is able to remember the last Sentinel that was able to reply correctly and will
 use it for the next requests.
 
-## Storing objects
-
-Redis only stores strings as values. If you want to store an object, you
-can use a serialization mechanism such as JSON:
+If you want to [authenticate](https://redis.io/topics/sentinel#configuring-sentinel-instances-with-authentication) Sentinel itself, you must specify the `password` option per instance.
 
 ```ruby
-require "json"
+SENTINELS = [{ host: '127.0.0.1', port: 26380, password: 'mysecret' },
+             { host: '127.0.0.1', port: 26381, password: 'mysecret' }]
 
-redis.set "foo", [1, 2, 3].to_json
-# => OK
-
-JSON.parse(redis.get("foo"))
-# => [1, 2, 3]
+redis = Redis.new(name: 'mymaster', sentinels: SENTINELS, role: :master)
 ```
 
+## Cluster support
+
+[Clustering](https://redis.io/topics/cluster-spec). is supported via the [`redis-clustering` gem](cluster/).
+
 ## Pipelining
 
 When multiple commands are executed sequentially, but are not dependent,
@@ -159,13 +147,24 @@ commands to Redis and gathers their replies. These replies are returned
 by the `#pipelined` method.
 
 ```ruby
-redis.pipelined do
-  redis.set "foo", "bar"
-  redis.incr "baz"
+redis.pipelined do |pipeline|
+  pipeline.set "foo", "bar"
+  pipeline.incr "baz"
 end
 # => ["OK", 1]
 ```
 
+Commands must be called on the yielded objects. If you call methods
+on the original client objects from inside a pipeline, they will be sent immediately:
+
+```ruby
+redis.pipelined do |pipeline|
+  pipeline.set "foo", "bar"
+  redis.incr "baz" # => 1
+end
+# => ["OK"]
+```
+
 ### Executing commands atomically
 
 You can use `MULTI/EXEC` to run a number of commands in an atomic
@@ -175,9 +174,9 @@ the regular pipeline, the replies to the commands are returned by the
 `#multi` method.
 
 ```ruby
-redis.multi do
-  redis.set "foo", "bar"
-  redis.incr "baz"
+redis.multi do |transaction|
+  transaction.set "foo", "bar"
+  transaction.incr "baz"
 end
 # => ["OK", 1]
 ```
@@ -185,21 +184,22 @@ end
 ### Futures
 
 Replies to commands in a pipeline can be accessed via the *futures* they
-emit (since redis-rb 3.0). All calls inside a pipeline block return a
+emit. All calls on the pipeline object return a
 `Future` object, which responds to the `#value` method. When the
 pipeline has successfully executed, all futures are assigned their
 respective replies and can be used.
 
 ```ruby
-redis.pipelined do
-  @set = redis.set "foo", "bar"
-  @incr = redis.incr "baz"
+set = incr = nil
+redis.pipelined do |pipeline|
+  set = pipeline.set "foo", "bar"
+  incr = pipeline.incr "baz"
 end
 
-@set.value
+set.value
 # => "OK"
 
-@incr.value
+incr.value
 # => 1
 ```
 
@@ -211,7 +211,7 @@ it can't connect to the server a `Redis::CannotConnectError` error will be raise
 ```ruby
 begin
   redis.ping
-rescue Exception => e
+rescue Redis::BaseError => e
   e.inspect
 # => #<Redis::CannotConnectError: Timed out connecting to Redis on 10.0.1.1:6380>
 
@@ -246,6 +246,7 @@ All timeout values are specified in seconds.
 When using pub/sub, you can subscribe to a channel using a timeout as well:
 
 ```ruby
+redis = Redis.new(reconnect_attempts: 0)
 redis.subscribe_with_timeout(5, "news") do |on|
   on.message do |channel, message|
     # ...
@@ -255,14 +256,41 @@ end
 
 If no message is received after 5 seconds, the client will unsubscribe.
 
+## Reconnections
 
-## SSL/TLS Support
+**By default**, this gem will only **retry a connection once** and then fail, but
+the client allows you to configure how many `reconnect_attempts` it should
+complete before declaring a connection as failed.
+
+```ruby
+Redis.new(reconnect_attempts: 0)
+Redis.new(reconnect_attempts: 3)
+```
+
+If you wish to wait between reconnection attempts, you can instead pass a list
+of durations:
 
-This library supports natively terminating client side SSL/TLS connections
-when talking to Redis via a server-side proxy such as [stunnel], [hitch],
-or [ghostunnel].
+```ruby
+Redis.new(reconnect_attempts: [
+  0, # retry immediately
+  0.25, # retry a second time after 250ms
+  1, # retry a third and final time after another 1s
+])
+```
+
+If you wish to disable reconnection only for some commands, you can use
+`disable_reconnection`:
+
+```ruby
+redis.get("some-key") # this may be retried
+redis.disable_reconnection do
+  redis.incr("some-counter") # this won't be retried.
+end
+```
 
-To enable SSL support, pass the `:ssl => :true` option when configuring the
+## SSL/TLS Support
+
+To enable SSL support, pass the `:ssl => true` option when configuring the
 Redis client, or pass in `:url => "rediss://..."` (like HTTPS for Redis).
 You will also need to pass in an `:ssl_params => { ... }` hash used to
 configure the `OpenSSL::SSL::SSLContext` object used for the connection:
@@ -295,13 +323,7 @@ redis = Redis.new(
 )
 ```
 
-[stunnel]: https://www.stunnel.org/
-[hitch]: https://hitch-tls.org/
-[ghostunnel]: https://github.com/square/ghostunnel
-[OpenSSL::SSL::SSLContext documentation]: http://ruby-doc.org/stdlib-2.3.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html
-
-*NOTE:* SSL is only supported by the default "Ruby" driver
-
+[OpenSSL::SSL::SSLContext documentation]: http://ruby-doc.org/stdlib-2.5.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html
 
 ## Expert-Mode Options
 
@@ -315,17 +337,9 @@ redis = Redis.new(
    Improper use of `inherit_socket` will result in corrupted and/or incorrect
    responses.
 
-## Alternate drivers
+## hiredis binding
 
 By default, redis-rb uses Ruby's socket library to talk with Redis.
-To use an alternative connection driver it should be specified as option
-when instantiating the client object. These instructions are only valid
-for **redis-rb 3.0**. For instructions on how to use alternate drivers from
-**redis-rb 2.2**, please refer to an [older README][readme-2.2.2].
-
-[readme-2.2.2]: https://github.com/redis/redis-rb/blob/v2.2.2/README.md
-
-### hiredis
 
 The hiredis driver uses the connection facility of hiredis-rb. In turn,
 hiredis-rb is a binding to the official hiredis client library. It
@@ -335,76 +349,56 @@ extension, JRuby is not supported (by default).
 It is best to use hiredis when you have large replies (for example:
 `LRANGE`, `SMEMBERS`, `ZRANGE`, etc.) and/or use big pipelines.
 
-In your Gemfile, include hiredis:
+In your Gemfile, include `hiredis-client`:
 
 ```ruby
-gem "redis", "~> 3.0.1"
-gem "hiredis", "~> 0.4.5"
+gem "redis"
+gem "hiredis-client"
 ```
 
-When instantiating the client object, specify hiredis:
+If your application doesn't call `Bundler.require`, you may have
+to require it explictly:
 
 ```ruby
-redis = Redis.new(:driver => :hiredis)
-```
-
-### synchrony
-
-The synchrony driver adds support for [em-synchrony][em-synchrony].
-This makes redis-rb work with EventMachine's asynchronous I/O, while not
-changing the exposed API. The hiredis gem needs to be available as
-well, because the synchrony driver uses hiredis for parsing the Redis
-protocol.
+require "hiredis-client"
+````
 
-[em-synchrony]: https://github.com/igrigorik/em-synchrony
+This makes the hiredis driver the default.
 
-In your Gemfile, include em-synchrony and hiredis:
+If you want to be certain hiredis is being used, when instantiating
+the client object, specify hiredis:
 
 ```ruby
-gem "redis", "~> 3.0.1"
-gem "hiredis", "~> 0.4.5"
-gem "em-synchrony"
-```
-
-When instantiating the client object, specify synchrony:
-
-```ruby
-redis = Redis.new(:driver => :synchrony)
+redis = Redis.new(driver: :hiredis)
 ```
 
 ## Testing
 
-This library is tested using [Travis][travis-home], where it is tested
-against the following interpreters and drivers:
+This library is tested against recent Ruby and Redis versions.
+Check [Github Actions][gh-actions-link] for the exact versions supported.
 
-* MRI 1.8.7 (drivers: ruby, hiredis)
-* MRI 1.9.3 (drivers: ruby, hiredis, synchrony)
-* MRI 2.0 (drivers: ruby, hiredis, synchrony)
-* MRI 2.1 (drivers: ruby, hiredis, synchrony)
-* MRI 2.2 (drivers: ruby, hiredis, synchrony)
-* MRI 2.3 (drivers: ruby, hiredis, synchrony)
-* JRuby 1.7 (1.8 mode) (drivers: ruby)
-* JRuby 1.7 (1.9 mode) (drivers: ruby)
+## See Also
+
+- [async-redis](https://github.com/socketry/async-redis) — An [async](https://github.com/socketry/async) compatible Redis client.
 
 ## Contributors
 
-(ordered chronologically with more than 5 commits, see `git shortlog -sn` for
-all contributors)
-
-* Ezra Zygmuntowicz
-* Taylor Weibley
-* Matthew Clark
-* Brian McKinney
-* Luca Guidi
-* Salvatore Sanfilippo
-* Chris Wanstrath
-* Damian Janowski
-* Michel Martens
-* Nick Quaranto
-* Pieter Noordhuis
-* Ilya Grigorik
+Several people contributed to redis-rb, but we would like to especially
+mention Ezra Zygmuntowicz. Ezra introduced the Ruby community to many
+new cool technologies, like Redis. He wrote the first version of this
+client and evangelized Redis in Rubyland. Thank you, Ezra.
 
 ## Contributing
 
 [Fork the project](https://github.com/redis/redis-rb) and send pull
-requests. You can also ask for help at `#redis-rb` on Freenode.
+requests.
+
+
+[inchpages-image]:  https://inch-ci.org/github/redis/redis-rb.svg
+[inchpages-link]:   https://inch-ci.org/github/redis/redis-rb
+[redis-commands]:   https://redis.io/commands
+[redis-home]:       https://redis.io
+[redis-url]:        http://www.iana.org/assignments/uri-schemes/prov/redis
+[gh-actions-image]: https://github.com/redis/redis-rb/workflows/Test/badge.svg
+[gh-actions-link]:  https://github.com/redis/redis-rb/actions
+[rubydoc]:          http://www.rubydoc.info/gems/redis