redis-py-cluster 1.1.0

# redis-py-cluster

This client provides a working client for redis cluster that was added in redis 3.0.

This project is a port of `redis-rb-cluster` by antirez, with alot of added functionality. The original source can be found at https://github.com/antirez/redis-rb-cluster

[](https://travis-ci.org/Grokzen/redis-py-cluster) [](https://coveralls.io/r/Grokzen/redis-py-cluster) [](http://badge.fury.io/py/redis-py-cluster) [](https://landscape.io/github/Grokzen/redis-py-cluster/unstable)



# Project status

The project is not dead but, not much new development is done right now. I do answer issue reports and pull requests as soon as possible. If you have a problem with the code, you can ping me inside the gitter channel that you can find here [](https://gitter.im/Grokzen/redis-py-cluster?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) and i will help you out with problems or usage of this lib.

As of release `0.3.0` this project will be considered stable and usable in production. If you are going to use redis cluster in your project, you should read up on all documentation that you can find in the bottom of this Readme file. It will contain usage examples and descriptions of what is and what is not implemented. It will also describe how and why things work the way they do in this client.

On the topic about porting/moving this code into `redis-py` there is currently work over here https://github.com/andymccurdy/redis-py/pull/604 that will bring cluster support based on this code. But my suggestion is that until that work is completed that you should use this lib.



## Installation

Latest stable release from pypi

```
$ pip install redis-py-cluster
```

or from source

```
$ python setup.py install
```



## Usage example

Small sample script that shows how to get started with RedisCluster. It can also be found in [examples/basic.py](examples/basic.py)

```python
>>> from rediscluster import StrictRedisCluster

>>> startup_nodes = [{"host": "127.0.0.1", "port": "7000"}]

>>> # Note: decode_responses must be set to True when used with python3
>>> rc = StrictRedisCluster(startup_nodes=startup_nodes, decode_responses=True)

>>> rc.set("foo", "bar")
True
>>> print(rc.get("foo"))
'bar'
```



## Upgrading instructions

Please read the [following](docs/Upgrading.md) documentation that will go through all changes that is required when upgrading `redis-py-cluster` between versions.



## Dependencies & supported python versions

- Python: redis >= `2.10.2` is required
- Redis server >= `3.0.0` is required
- Optional Python: hiredis >= `0.1.3`

Hiredis is tested on all supported python versions.

List of all supported python versions.

- 2.7
- 3.2
- 3.3
- 3.4.1+
- 3.5

Experimental:

- Python 3.6.0a0 - Currently broken due to `coverage` is not yet compatible with python 3.6


### Python 3.4.0

A segfault was found when running `redis-py` in python `3.4.0` that was introduced into the codebase in python `3.4.0`. Because of this both `redis-py` and `redis-py-cluster` will not work when running with `3.4.0`. This lib has decided to block the lib from execution on `3.4.0` and you will get a exception when trying to import the code. The only solution is to use python `3.4.1` or some other higher minor version in the `3.4` series.



## Testing

All tests are currently built around a 6 redis server cluster setup (3 masters + 3 slaves). One server must be using port 7000 for redis cluster discovery.

The easiest way to setup a cluster is to use either a Docker or Vagrant. They are both described in [Setup a redis cluster. Manually, Docker & Vagrant](docs/Cluster_Setup.md).

To run all tests in all supported environments with `tox` read this [Tox multienv testing](docs/Tox.md)



## More documentation

More detailed documentation can be found in `docs` folder.

- [Benchmarks](docs/Benchmarks.md)
- [Pubsub](docs/Pubsub.md)
- [Setup a redis cluster. Manually, Docker & Vagrant](docs/Cluster_Setup.md)
- [Command differences](docs/Commands.md)
- [Limitations and differences](docs/Limits_and_differences.md)
- [Redisco support (Django ORM)](docs/Redisco.md)
- [Pipelines](docs/Pipelines.md)
- [Threaded Pipeline support](docs/Threads.md)
- [Cluster Management class](docs/ClusterMgt.md)
- [READONLY mode](docs/Readonly_mode.md)
- [Authors](docs/Authors)



## Disclaimer

Both Redis cluster and redis-py-cluster is considered stable and production ready.

But this depends on what you are going to use clustering for. In the simple use cases with SET/GET and other single key functions there is not issues. If you require multi key functinoality or pipelines then you must be very careful when developing because they work slightly different from the normal redis server.

If you require advance features like pubsub or scripting, this lib and redis do not handle that kind of use-cases very well. You either need to develop a custom solution yourself or use a non clustered redis server for that.

Finally, this lib itself is very stable and i know of atleast 2 companies that use this in production with high loads and big cluster sizes.



## License & Authors

MIT (See docs/License.txt file)

The license should be the same as redis-py (https://github.com/andymccurdy/redis-py)


* 1.1.0
* Refactored exception handling and exception classes.
* Added READONLY mode support, scales reads using slave nodes.
* Fix __repr__ for ClusterConnectionPool and ClusterReadOnlyConnectionPool
* Add max_connections_per_node parameter to ClusterConnectionPool so that max_connections parameter is calculated per-node rather than across the whole cluster.
* Improve thread safty of get_connection_by_slot and get_connection_by_node methods (iandyh)
* Improved error handling when sending commands to all nodes, e.g. info. Now the connection takes retry_on_timeout as an option and retry once when there is a timeout. (iandyh)
* Added support for SCRIPT LOAD, SCRIPT FLUSH, SCRIPT EXISTS and EVALSHA commands. (alisaifee)
* Improve thread safety to avoid exceptions when running one client object inside multiple threads and doing resharding of the
cluster at the same time.
* Fix ASKING error handling so now it really sends ASKING to next node during a reshard operation. This improvement was also made to pipelined commands.
* Improved thread safety in pipelined commands, along better explanation of the logic inside pipelining with code comments.

* 1.0.0
* No change to anything just a bump to 1.0.0 because the lib is now considered stable/production ready.

* 0.3.0
* simple benchmark now uses docopt for cli parsing
* New make target to run some benchmarks 'make benchmark'
* simple benchmark now support pipelines tests
* Renamed RedisCluster --> StrictRedisCluster
* Implement backwards compatible redis.Redis class in cluster mode. It was named RedisCluster and everyone updating from 0.2.0 to 0.3.0 should consult docs/Upgrading.md for instructions how to change your code.
* Added comprehensive documentation regarding pipelines
* Meta retrieval commands(slots, nodes, info) for Redis Cluster. (iandyh)

* 0.2.0
* Moved pipeline code into new file.
* Code now uses a proper cluster connection pool class that handles
all nodes and connections similar to how redis-py do.
* Better support for pubsub. All clients will now talk to the same server because
pubsub commands do not work reliably if it talks to a random server in the cluster.
* Better result callbacks and node routing support. No more ugly decorators.
* Fix keyslot command when using non ascii characters.
* Add bitpos support, redis-py 2.10.2 or higher required.
* Fixed a bug where vagrant users could not build the package via shared folder.
* Better support for CLUSTERDOWN error. (Neuront)
* Parallel pipeline execution using threads. (72squared)
* Added vagrant support for testing and development. (72squared)
* Improve stability of client during resharding operations (72squared)

* 0.1.0
* Initial release
* First release uploaded to pypi