redis 4.7.1 → 5.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 185ccbe36adc1e1561474af65d0e0b8d246e9c161757c9218f5ac7b6c1d24bb9
-  data.tar.gz: 03a4203747503b971551500ea40f996cb9620e5d9a693231d7a63944a9f73bf8
+  metadata.gz: a8bcabf5f725061ad3fba18ed42eed7ce26788cf41b78f2091e6033530e124e0
+  data.tar.gz: 6b22ffde2abc13f944641c17972013cb4084dd91989127d6a3f9232b1b21ec5d
 SHA512:
-  metadata.gz: 3354c910dcf3feb76b7f4ed7adb5bcce4f1cfc3ef7c58347897ba4705337a89052d2db67a8a71765f34e16f01a7ab2c8894bba60a3a89e1f36b6487f3fe0089b
-  data.tar.gz: 0b23396f9ecf62dd952536b94107a7748bb5ee225e7c7ac1da36e813e7fffc588c5939abe1800fc440e173acc54a9ac3649037b62b3ff59aa946ffc9a3e11180
+  metadata.gz: 21141ffa7c06d44599ba93097ec2000abd6325afe2e7175a15f0c0dddfae7b2a120b8acd5f14937f1c58fb971e2fd04603721388a53f6ea42b66031f8b1f9058
+  data.tar.gz: 1b0996205f973aba8c7db27726eacbe2a03e4339d0444eee80e68958a5226b70349437a518a5f8d0a7b419106e9c9ae546d349dbf7c639ca9a51a721ca96a51c

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Unreleased
 
+# 5.0.0.beta3
+
+- Use `MD5` for hashing server nodes in `Redis::Distributed`. This should improve keys distribution among servers. See #1089.
+- Changed `sadd` and `srem` to now always return an Integer.
+- Added `sadd?` and `srem?` which always return a Boolean.
+- Added support for `IDLE` paramter in `xpending`.
+- Cluster support has been moved to a `rediscluster` companion gem.
+- `select` no longer record the current database. If the client has to reconnect after `select` was used, it will reconnect to the original database.
+- Better support Float timeout in blocking commands. See #977.
+- Removed positional timeout in blocking commands (`BLPOP`, etc). Timeout now must be passed as an option: `r.blpop("key", timeout: 2.5)`
+- Removed `logger` option.
+- Removed `reconnect_delay_max` and `reconnect_delay`, you can pass precise sleep durations to `reconnect_attempts` instead.
+- Require Ruby 2.5+.
+- Removed the deprecated `queue` and `commit` methods. Use `pipelined` instead.
+- Removed the deprecated `Redis::Future#==`.
+- Removed the deprecated `pipelined` and `multi` signature. Commands now MUST be called on the block argument, not the original redis instance.
+- Removed `Redis.current`. You shouldn't assume there is a single global Redis connection, use a connection pool instead,
+  and libaries using Redis should accept a Redis instance (or connection pool) as a config. E.g. `MyLibrary.redis = Redis.new(...)`.
+- Removed the `synchrony` driver.
+- Removed `Redis.exists_returns_integer`, it's now always enabled.
+
 # 4.7.1
 
 * Gracefully handle OpenSSL 3.0 EOF Errors (`OpenSSL::SSL::SSLError: SSL_read: unexpected eof while reading`). See #1106

data/README.md

@@ -1,7 +1,6 @@
 # redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][inchpages-image]][inchpages-link]
 
-A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still
-providing an idiomatic interface.
+A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still providing an idiomatic interface.
 
 See [RubyDoc.info][rubydoc] for the API docs of the latest published gem.
 
@@ -38,10 +37,6 @@ redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15")
 The client expects passwords with special chracters to be URL-encoded (i.e.
 `CGI.escape(password)`).
 
-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.
-
 To connect to Redis listening on a Unix socket, try:
 
 ```ruby
@@ -76,6 +71,28 @@ redis.get("mykey")
 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], e.g.:
+
+```ruby
+module MyApp
+  def self.redis
+    @redis ||= ConnectionPool.new do
+      Redis.new(url: ENV["REDIS_URL"])
+    end
+  end
+end
+
+MyApp.redis.incr("some-counter")
+```
+
+[`connection_pool` gem](https://github.com/mperham/connection_pool)
+
 ## Sentinel support
 
 The client is able to perform automatic failover by using [Redis
@@ -111,79 +128,12 @@ If you want to [authenticate](https://redis.io/topics/sentinel#configuring-senti
 SENTINELS = [{ host: '127.0.0.1', port: 26380, password: 'mysecret' },
              { host: '127.0.0.1', port: 26381, password: 'mysecret' }]
 
-redis = Redis.new(host: 'mymaster', sentinels: SENTINELS, role: :master)
+redis = Redis.new(name: 'mymaster', sentinels: SENTINELS, role: :master)
 ```
 
 ## Cluster support
 
-`redis-rb` supports [clustering](https://redis.io/topics/cluster-spec).
-
-```ruby
-# Nodes can be passed to the client as an array of connection URLs.
-nodes = (7000..7005).map { |port| "redis://127.0.0.1:#{port}" }
-redis = Redis.new(cluster: nodes)
-
-# You can also specify the options as a Hash. The options are the same as for a single server connection.
-(7000..7005).map { |port| { host: '127.0.0.1', port: port } }
-```
-
-You can also specify only a subset of the nodes, and the client will discover the missing ones using the [CLUSTER NODES](https://redis.io/commands/cluster-nodes) command.
-
-```ruby
-Redis.new(cluster: %w[redis://127.0.0.1:7000])
-```
-
-If you want [the connection to be able to read from any replica](https://redis.io/commands/readonly), you must pass the `replica: true`. Note that this connection won't be usable to write keys.
-
-```ruby
-Redis.new(cluster: nodes, replica: true)
-```
-
-The calling code is responsible for [avoiding cross slot commands](https://redis.io/topics/cluster-spec#keys-distribution-model).
-
-```ruby
-redis = Redis.new(cluster: %w[redis://127.0.0.1:7000])
-
-redis.mget('key1', 'key2')
-#=> Redis::CommandError (CROSSSLOT Keys in request don't hash to the same slot)
-
-redis.mget('{key}1', '{key}2')
-#=> [nil, nil]
-```
-
-* The client automatically reconnects after a failover occurred, but the caller is responsible for handling errors while it is happening.
-* The client support permanent node failures, and will reroute requests to promoted slaves.
-* The client supports `MOVED` and `ASK` redirections transparently.
-
-## Cluster mode with SSL/TLS
-Since Redis can return FQDN of nodes in reply to client since `7.*` with CLUSTER commands, we can use cluster feature with SSL/TLS connection like this:
-
-```ruby
-Redis.new(cluster: %w[rediss://foo.example.com:6379])
-```
-
-On the other hand, in Redis versions prior to `6.*`, you can specify options like the following if cluster mode is enabled and client has to connect to nodes via single endpoint with SSL/TLS.
-
-```ruby
-Redis.new(cluster: %w[rediss://foo-endpoint.example.com:6379], fixed_hostname: 'foo-endpoint.example.com')
-```
-
-In case of the above architecture, if you don't pass the `fixed_hostname` option to the client and servers return IP addresses of nodes, the client may fail to verify certificates.
-
-## Storing objects
-
-Redis "string" types can be used to store serialized Ruby objects, for
-example with JSON:
-
-```ruby
-require "json"
-
-redis.set "foo", [1, 2, 3].to_json
-# => OK
-
-JSON.parse(redis.get("foo"))
-# => [1, 2, 3]
-```
+[Clustering](https://redis.io/topics/cluster-spec). is supported via the [`redis-clustering` gem](cluster/).
 
 ## Pipelining
 
@@ -206,6 +156,17 @@ 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 willb e 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
@@ -225,21 +186,22 @@ end
 ### Futures
 
 Replies to commands in a pipeline can be accessed via the *futures* they
-emit (since redis-rb 3.0). All calls on the pipeline object 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
+set = incr = nil
 redis.pipelined do |pipeline|
-  @set = pipeline.set "foo", "bar"
-  @incr = pipeline.incr "baz"
+  set = pipeline.set "foo", "bar"
+  incr = pipeline.incr "baz"
 end
 
-@set.value
+set.value
 # => "OK"
 
-@incr.value
+incr.value
 # => 1
 ```
 
@@ -251,7 +213,7 @@ it can't connect to the server a `Redis::CannotConnectError` error will be raise
 ```ruby
 begin
   redis.ping
-rescue StandardError => e
+rescue Redis::BaseError => e
   e.inspect
 # => #<Redis::CannotConnectError: Timed out connecting to Redis on 10.0.1.1:6380>
 
@@ -298,55 +260,37 @@ If no message is received after 5 seconds, the client will unsubscribe.
 
 ## Reconnections
 
-The client allows you to configure how many `reconnect_attempts` it should
-complete before declaring a connection as failed. Furthermore, you may want
-to control the maximum duration between reconnection attempts with
-`reconnect_delay` and `reconnect_delay_max`.
+**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 => 10,
-  :reconnect_delay => 1.5,
-  :reconnect_delay_max => 10.0,
-)
+Redis.new(reconnect_attempts: 0)
+Redis.new(reconnect_attempts: 3)
 ```
 
-The delay values are specified in seconds. With the above configuration, the
-client would attempt 10 reconnections, exponentially increasing the duration
-between each attempt but it never waits longer than `reconnect_delay_max`.
-
-This is the retry algorithm:
+If you wish to wait between reconnection attempts, you can instead pass a list
+of durations:
 
 ```ruby
-attempt_wait_time = [(reconnect_delay * 2**(attempt-1)), reconnect_delay_max].min
+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
+])
 ```
 
-**By default**, this gem will only **retry a connection once** and then fail, but with the
-above configuration the reconnection attempt would look like this:
-
-#|Attempt wait time|Total wait time
-:-:|:-:|:-:
-1|1.5s|1.5s
-2|3.0s|4.5s
-3|6.0s|10.5s
-4|10.0s|20.5s
-5|10.0s|30.5s
-6|10.0s|40.5s
-7|10.0s|50.5s
-8|10.0s|60.5s
-9|10.0s|70.5s
-10|10.0s|80.5s
-
-So if the reconnection attempt #10 succeeds 70 seconds have elapsed trying
-to reconnect, this is likely fine in long-running background processes, but if
-you use Redis to drive your website you might want to have a lower
-`reconnect_delay_max` or have less `reconnect_attempts`.
+If you wish to disable reconnection only for some commands, you can use
+`disable_reconnection`:
 
-## SSL/TLS Support
+```ruby
+redis.get("some-key") # this may be retried
+redis.disable_reconnection do
+  redis.incr("some-counter") # this won't be retried.
+end
+```
 
-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].
+## 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).
@@ -381,13 +325,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
 
@@ -401,17 +339,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
@@ -421,41 +351,27 @@ 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
-
-In your Gemfile, include em-synchrony and hiredis:
-
-```ruby
-gem "redis", "~> 3.0.1"
-gem "hiredis", "~> 0.4.5"
-gem "em-synchrony"
-```
+This makes the hiredis driver the default.
 
-When instantiating the client object, specify synchrony:
+If you want to be certain hiredis is being used, when instantiating
+the client object, specify hiredis:
 
 ```ruby
-redis = Redis.new(:driver => :synchrony)
+redis = Redis.new(driver: :hiredis)
 ```
 
 ## Testing