This document describes what must be done when upgrading between different versions to ensure that code still works.
If you created the StrictRedisCluster (or RedisCluster) instance via the from_url method and were passing readonly_mode to it, the connection pool created will now properly allow selecting read-only slaves from the pool. Previously it always used master nodes only, even in the case of readonly_mode=True. Make sure your code don't attempt any write commands over connections with readonly_mode=True.
If your redis instance is configured to not have the CONFIG ... commands enabled due to security reasons you need to pass this into the client object skip_full_coverage_check=True. Benefits is that the client class no longer requires the CONFIG ... commands to be enabled on the server. Downsides is that you can't use the option in your redis server and still use the same feature in this client.
Method scan_iter was rebuilt becuase it was broken and did not perform as expected. If you are using this method you should be carefull with this new implementation and test it through before using it. The expanded testing for that method indicates it should work without problems. If you find any issues with the new method please open a issue on github.
A major refactoring was performed in the pipeline system that improved error handling and reliability of execution. It also simplified the code alot to make it easier to understand and continue to develop in the future. Becuase of this major refactoring you should really test throuhg your pipeline code to ensure that none of your code is broken because of this refactoring.
Class RedisClusterMgt has been removed. You should use the CLUSTER ... methods that exists in the StrictRedisCluster client class.
Method cluster_delslots changed argument specification from self, node_id, *slots to self, *slots and changed the behaviour of the method to now automatically determine the slot_id based on the current cluster structure and where each slot that you want to delete is loated.
Method pfcount no longer has custom logic and exceptions to prevent CROSSSLOT errors. If method is used with different slots then a regular CROSSSLOT error (rediscluster.exceptions.ClusterCrossSlotError) will be returned.
Discontinue passing pipeline_use_threads flag to rediscluster.StrictRedisCluster or rediscluster.RedisCluster.
Also discontinue passing use_threads flag to the pipeline() method.
In 1.1.0 and prior, you could use pipeline_use_threads flag to tell the client to perform queries to the different nodes in parallel via threads. We exposed this as a flag because using threads might have been risky and we wanted people to be able to disable it if needed.
With this release we figured out how to get parallelization of the commands without the need for threads. We write to all the nodes before reading from them, essentially multiplexing the connections (but without the need for complicated socket multiplexing). We found this approach to be faster and more scalable as more nodes are added to the cluster.
That means we don't need the pipeline_use_threads flag anymore, or the use_threads flag that could be passed into the instantiation of the pipeline object itself.
The logic is greatly simplified and the default behavior will now come with a performance boost and no need to use threads.
Publish and subscribe no longer connects to a single instance. It now hashes the channel name and uses that to determine what node to connect to. More work will be done in the future when redis-server improves the pubsub implementation. Please read up on the documentation about pubsub in the docs/pubsub.md file about the problems and limitations on using a pubsub in a cluster.
Commands Publish and Subscribe now uses the same connections as any other commands. If you are using any pubsub commands you need to test it through thoroughly to ensure that your implementation still works.
To use less strict cluster slots discovery you can add the following config to your redis-server config file "cluster-require-full-coverage=no" and this client will honour that setting and not fail if not all slots is covered.
A bug was fixed in 'sdiffstore', if you are using this, verify that your code still works as expected.
Class RedisClusterMgt is now deprecated and will be removed in next release in favor of all cluster commands implemented in the client in this release.
The following exceptions have been changed/added and code that use this client might have to be updated to handle the new classes.
raise RedisClusterException("Too many Cluster redirections") have been changed to raise ClusterError('TTL exhausted.')
ClusterDownException have been replaced with ClusterDownError
Added new AskError exception class.
Added new TryAgainError exception class.
Added new MovedError exception class.
Added new ClusterCrossSlotError exception class.
Added optional max_connections_per_node parameter to ClusterConnectionPool which changes behavior of max_connections so that it applies per-node rather than across the whole cluster. The new feature is opt-in, and the existing default behavior is unchanged. Users are recommended to opt-in as the feature fixes two important problems. First is that some nodes could be starved for connections after max_connections is used up by connecting to other nodes. Second is that the asymmetric number of connections across nodes makes it challenging to configure file descriptor and redis max client settings.
Reinitialize on MOVED errors will not run on every error but instead on every 25 error to avoid excessive cluster reinitialize when used in multiple threads and resharding at the same time. If you want to go back to the old behaviour with reinitialize on every error you should pass in reinitialize_steps=1 to the client constructor. If you want to increase or decrease the intervall of this new behaviour you should set reinitialize_steps in the client constructor to a value that you want.
Pipelines in general have recieved alot of attention so if you are using pipelines in your code, ensure that you test the new code out alot before using it to make sure it still works as you expect.
The entire client code should now be safer to use in a threaded environment. Some race conditions was found and have now been fixed and it should prevent the code from behaving wierd during reshard operations.
In 0.3.0 release the name of the client class was changed from RedisCluster to StrictRedisCluster and a new implementation of RedisCluster was added that is based on redis.Redis class. This was done to enable implementation a cluster enabled version of redis.Redis class.
Because of this all imports and usage of RedisCluster must be changed to StrictRedisCluster so that existing code will remain working. If this is not done some issues could arise in existing code.
No major changes was done.