Debian Codegraph @

docs/pool.rst

raw
1 .. _aiomysql-pool:
2
3 Pool
4 ====
5
6 The library provides *connection pool* as well as plain
7 :class:`Connection` objects.
8
9
10 The basic usage is::
11
12 import asyncio
13 import aiomysql
14
15 loop = asyncio.get_event_loop()
16
17 async def go():
18 pool = await aiomysql.create_pool(host='127.0.0.1', port=3306,
19 user='root', password='',
20 db='mysql', loop=loop, autocommit=False)
21
22 async with pool.acquire() as conn:
23 async with conn.cursor() as cur:
24 await cur.execute("SELECT 10")
25 # print(cur.description)
26 (r,) = await cur.fetchone()
27 assert r == 10
28 pool.close()
29 await pool.wait_closed()
30
31 loop.run_until_complete(go())
32
33
34 .. function:: create_pool(minsize=1, maxsize=10, loop=None, **kwargs)
35
36 A :ref:`coroutine <coroutine>` that creates a pool of connections to
37 :term:`MySQL` database.
38
39 :param int minsize: minimum sizes of the *pool*.
40 :param int maxsize: maximum sizes of the *pool*.
41 :param loop: is an optional *event loop* instance,
42 :func:`asyncio.get_event_loop` is used if *loop* is not specified.
43 :param bool echo: -- executed log SQL queryes (``False`` by default).
44 :param kwargs: The function accepts all parameters that
45 :func:`aiomysql.connect` does plus optional keyword-only parameters
46 *loop*, *minsize*, *maxsize*.
47 :param float pool_recycle: number of seconds after which connection is
48 recycled, helps to deal with stale connections in pool, default
49 value is -1, means recycling logic is disabled.
50 :returns: :class:`Pool` instance.
51
52
53 .. class:: Pool
54
55 A connection pool.
56
57 After creation pool has *minsize* free connections and can grow up
58 to *maxsize* ones.
59
60 If *minsize* is ``0`` the pool doesn't creates any connection on startup.
61
62 If *maxsize* is ``0`` than size of pool is unlimited (but it
63 recycles used connections of course).
64
65 The most important way to use it is getting connection in *with statement*::
66
67 async with pool.acquire() as conn:
68 async with conn.cursor() as cur:
69 pass
70
71
72 See also :meth:`Pool.acquire` and :meth:`Pool.release` for acquiring
73 :class:`Connection` without *with statement*.
74
75 .. attribute:: echo
76
77 Return *echo mode* status. Log all executed queries to logger
78 named ``aiomysql`` if ``True``
79
80 .. attribute:: minsize
81
82 A minimal size of the pool (*read-only*), ``1`` by default.
83
84 .. attribute:: maxsize
85
86 A maximal size of the pool (*read-only*), ``10`` by default.
87
88 .. attribute:: size
89
90 A current size of the pool (*readonly*). Includes used and free
91 connections.
92
93 .. attribute:: freesize
94
95 A count of free connections in the pool (*readonly*).
96
97 .. method:: clear()
98
99 A :ref:`coroutine <coroutine>` that closes all *free* connections
100 in the pool. At next connection acquiring at least :attr:`minsize` of
101 them will be recreated.
102
103 .. method:: close()
104
105 Close pool.
106
107 Mark all pool connections to be closed on getting back to pool.
108 Closed pool doesn't allow to acquire new connections.
109
110 If you want to wait for actual closing of acquired connection please
111 call :meth:`wait_closed` after :meth:`close`.
112
113 .. warning:: The method is not a :ref:`coroutine <coroutine>`.
114
115 .. method:: terminate()
116
117 Terminate pool.
118
119 Close pool with instantly closing all acquired connections also.
120
121 :meth:`wait_closed` should be called after :meth:`terminate` for
122 waiting for actual finishing.
123
124 .. warning:: The method is not a :ref:`coroutine <coroutine>`.
125
126 .. method:: wait_closed()
127
128 A :ref:`coroutine <coroutine>` that waits for releasing and
129 closing all acquired connections.
130
131 Should be called after :meth:`close` for waiting for actual pool
132 closing.
133
134 .. method:: acquire()
135
136 A :ref:`coroutine <coroutine>` that acquires a connection from
137 *free pool*. Creates new connection if needed and :attr:`size`
138 of pool is less than :attr:`maxsize`.
139
140 Returns a :class:`Connection` instance.
141
142 .. method:: release(conn)
143
144 Reverts connection *conn* to *free pool* for future recycling.
145
146 .. warning:: The method is not a :ref:`coroutine <coroutine>`.