1.. highlight:: python3
2.. module:: aioredis.commands
3
4Getting started
5===============
6
7Installation
8------------
9
10.. code-block:: bash
11
12   $ pip install aioredis
13
14This will install aioredis along with its dependencies:
15
16* hiredis protocol parser;
17
18* async-timeout --- used in Sentinel client.
19
20Without dependencies
21~~~~~~~~~~~~~~~~~~~~
22
23In some cases [1]_ you might need to install :mod:`aioredis` without ``hiredis``,
24it is achievable with the following command:
25
26.. code-block:: bash
27
28   $ pip install --no-deps aioredis async-timeout
29
30Installing latest version from Git
31~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32
33.. code-block:: bash
34
35   $ pip install git+https://github.com/aio-libs/aioredis@master#egg=aioredis
36
37Connecting
38----------
39
40:download:`get source code<../examples/getting_started/00_connect.py>`
41
42.. literalinclude:: ../examples/getting_started/00_connect.py
43   :language: python3
44
45:func:`aioredis.create_redis_pool` creates a Redis client backed by a pool of
46connections. The only required argument is the address of Redis server.
47Redis server address can be either host and port tuple
48(ex: ``('localhost', 6379)``), or a string which will be parsed into
49TCP or UNIX socket address (ex: ``'unix://var/run/redis.sock'``,
50``'//var/run/redis.sock'``, ``redis://redis-host-or-ip:6379/1``).
51
52Closing the client. Calling ``redis.close()`` and then ``redis.wait_closed()``
53is strongly encouraged as this will methods will shutdown all open connections
54and cleanup resources.
55
56See the :doc:`commands reference </mixins>` for the full list of supported commands.
57
58Connecting to specific DB
59~~~~~~~~~~~~~~~~~~~~~~~~~
60
61There are several ways you can specify database index to select on connection:
62
63#. explicitly pass db index as ``db`` argument:
64
65   .. code-block:: python
66
67      redis = await aioredis.create_redis_pool(
68       'redis://localhost', db=1)
69
70#. pass db index in URI as path component:
71
72   .. code-block:: python
73
74      redis = await aioredis.create_redis_pool(
75          'redis://localhost/2')
76
77   .. note::
78
79      DB index specified in URI will take precedence over
80      ``db`` keyword argument.
81
82#. call :meth:`~aioredis.Redis.select` method:
83
84   .. code-block:: python
85
86      redis = await aioredis.create_redis_pool(
87          'redis://localhost/')
88      await redis.select(3)
89
90
91Connecting to password-protected Redis instance
92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
94The password can be specified either in keyword argument or in address URI:
95
96.. code-block:: python
97
98   redis = await aioredis.create_redis_pool(
99       'redis://localhost', password='sEcRet')
100
101   redis = await aioredis.create_redis_pool(
102       'redis://:sEcRet@localhost/')
103
104   redis = await aioredis.create_redis_pool(
105       'redis://localhost/?password=sEcRet')
106
107.. note::
108   Password specified in URI will take precedence over password keyword.
109
110   Also specifying both password as authentication component and
111   query parameter in URI is forbidden.
112
113   .. code-block:: python
114
115      # This will cause assertion error
116      await aioredis.create_redis_pool(
117          'redis://:sEcRet@localhost/?password=SeCreT')
118
119Result messages decoding
120------------------------
121
122By default :mod:`aioredis` will return :class:`bytes` for most Redis
123commands that return string replies. Redis error replies are known to be
124valid UTF-8 strings so error messages are decoded automatically.
125
126If you know that data in Redis is valid string you can tell :mod:`aioredis`
127to decode result by passing keyword-only argument ``encoding``
128in a command call:
129
130:download:`get source code<../examples/getting_started/01_decoding.py>`
131
132.. literalinclude:: ../examples/getting_started/01_decoding.py
133   :language: python3
134
135
136:mod:`aioredis` can decode messages for all Redis data types like
137lists, hashes, sorted sets, etc:
138
139:download:`get source code<../examples/getting_started/02_decoding.py>`
140
141.. literalinclude:: ../examples/getting_started/02_decoding.py
142   :language: python3
143
144
145Multi/Exec transactions
146-----------------------
147
148:download:`get source code<../examples/getting_started/03_multiexec.py>`
149
150.. literalinclude:: ../examples/getting_started/03_multiexec.py
151   :language: python3
152
153:meth:`~TransactionsCommandsMixin.multi_exec` method creates and returns new
154:class:`~aioredis.commands.MultiExec` object which is used for buffering commands and
155then executing them inside MULTI/EXEC block.
156
157.. warning::
158
159   It is very important not to ``await`` buffered command
160   (ie ``tr.set('foo', '123')``) as it will block forever.
161
162   The following code will block forever::
163
164      tr = redis.multi_exec()
165      await tr.incr('foo')   # that's all. we've stuck!
166
167
168Pub/Sub mode
169------------
170
171:mod:`aioredis` provides support for Redis Publish/Subscribe messaging.
172
173To start listening for messages you must call either
174:meth:`~PubSubCommandsMixin.subscribe` or
175:meth:`~PubSubCommandsMixin.psubscribe` method.
176Both methods return list of :class:`~aioredis.Channel` objects representing
177subscribed channels.
178
179Right after that the channel will receive and store messages
180(the ``Channel`` object is basically a wrapper around :class:`asyncio.Queue`).
181To read messages from channel you need to use :meth:`~aioredis.Channel.get`
182or :meth:`~aioredis.Channel.get_json` coroutines.
183
184Example subscribing and reading channels:
185
186:download:`get source code<../examples/getting_started/04_pubsub.py>`
187
188.. literalinclude:: ../examples/getting_started/04_pubsub.py
189   :language: python3
190
191Subscribing and reading patterns:
192
193:download:`get source code<../examples/getting_started/05_pubsub.py>`
194
195.. literalinclude:: ../examples/getting_started/05_pubsub.py
196   :language: python3
197
198Sentinel client
199---------------
200
201:download:`get source code<../examples/getting_started/06_sentinel.py>`
202
203.. literalinclude:: ../examples/getting_started/06_sentinel.py
204   :language: python3
205
206Sentinel client requires a list of Redis Sentinel addresses to connect to
207and start discovering services.
208
209Calling :meth:`~aioredis.sentinel.SentinelPool.master_for` or
210:meth:`~aioredis.sentinel.SentinelPool.slave_for` methods will return
211Redis clients connected to specified services monitored by Sentinel.
212
213Sentinel client will detect failover and reconnect Redis clients automatically.
214
215See detailed reference :doc:`here <sentinel>`
216
217----
218
219.. [1]
220   Celery hiredis issues
221   (`#197 <https://github.com/aio-libs/aioredis/issues/197>`_,
222   `#317 <https://github.com/aio-libs/aioredis/pull/317>`_)
223