Debian Codegraph @

docs/connection.rst

raw
1 .. _api:
2
3 :mod:`aiomysql` --- API Reference
4 =================================
5
6 .. module:: aiomysql
7 :synopsis: A library for accessing a MySQL database from the asyncio
8 .. currentmodule:: aiomysql
9
10 .. _aiomysql-connection:
11
12 Connection
13 ==========
14
15 The library provides a way to connect to MySQL database with simple factory
16 function :func:`aiomysql.connnect`. Use this function if you want just one
17 connection to the database, consider connection pool for multiple connections.
18
19 Example::
20
21 import asyncio
22 import aiomysql
23
24 loop = asyncio.get_event_loop()
25
26 async def test_example():
27 conn = await aiomysql.connect(host='127.0.0.1', port=3306,
28 user='root', password='', db='mysql',
29 loop=loop)
30
31 cur = await conn.cursor()
32 await cur.execute("SELECT Host,User FROM user")
33 print(cur.description)
34 r = await cur.fetchall()
35 print(r)
36 await cur.close()
37 conn.close()
38
39 loop.run_until_complete(test_example())
40
41
42 .. function:: connect(host="localhost", user=None, password="",
43 db=None, port=3306, unix_socket=None,
44 charset='', sql_mode=None,
45 read_default_file=None, conv=decoders, use_unicode=None,
46 client_flag=0, cursorclass=Cursor, init_command=None,
47 connect_timeout=None, read_default_group=None,
48 autocommit=False, echo=False
49 local_infile=False, loop=None, ssl=None, auth_plugin='',
50 program_name='', server_public_key=None)
51
52 A :ref:`coroutine <coroutine>` that connects to MySQL.
53
54 The function accepts all parameters that :func:`pymysql.connect`
55 does plus optional keyword-only *loop* and *timeout* parameters.
56
57 :param str host: host where the database server is located,
58 default: `localhost`.
59 :param str user: username to log in as.
60 :param str password: password to use.
61 :param str db: database to use, None to not use a particular one.
62 :param int port: MySQL port to use, default is usually OK.
63 :param str unix_socket: optionally, you can use a unix socket rather
64 than TCP/IP.
65 :param str charset: charset you want to use, for example 'utf8'.
66 :param sql_mode: default sql-mode_ to use, like 'NO_BACKSLASH_ESCAPES'
67 :param read_default_file: specifies my.cnf file to read these
68 parameters from under the [client] section.
69 :param conv: decoders dictionary to use instead of the default one.
70 This is used to provide custom marshalling of types.
71 See `pymysql.converters`.
72 :param use_unicode: whether or not to default to unicode strings.
73 :param client_flag: custom flags to send to MySQL. Find
74 potential values in `pymysql.constants.CLIENT`. Refer to the
75 `local_infile` parameter for enabling loading of local data.
76 :param cursorclass: custom cursor class to use.
77 :param str init_command: initial SQL statement to run when connection is
78 established.
79 :param connect_timeout: Timeout in seconds before throwing an exception
80 when connecting.
81 :param str read_default_group: Group to read from in the configuration
82 file.
83 :param autocommit: Autocommit mode. None means use server default.
84 (default: ``False``)
85 :param local_infile: Boolean to enable the use of `LOAD DATA LOCAL`
86 command. This also enables the corresponding `client_flag`. aiomysql
87 does not perform any validation of files requested by the server. Do
88 not use this with untrusted servers. (default: ``False``)
89 :param ssl: Optional SSL Context to force SSL
90 :param auth_plugin: String to manually specify the authentication
91 plugin to use, i.e you will want to use mysql_clear_password
92 when using IAM authentication with Amazon RDS.
93 (default: Server Default)
94 :param program_name: Program name string to provide when
95 handshaking with MySQL. (omitted by default)
96
97 .. versionchanged:: 1.0
98 ``sys.argv[0]`` is no longer passed by default
99 :param server_public_key: SHA256 authenticaiton plugin public key value.
100 :param loop: asyncio event loop instance or ``None`` for default one.
101 :returns: :class:`Connection` instance.
102
103
104 Representation of a socket with a mysql server. The proper way to get an
105 instance of this class is to call :func:`aiomysql.connnect`.
106
107 Its insterface is almost the same as `pymysql.connection` except all methods
108 are :ref:`coroutines <coroutine>`.
109
110
111 The most important methods are:
112
113 .. method:: cursor(cursor=None)
114
115 A :ref:`coroutine <coroutine>` that creates a new cursor object
116 using the connection.
117
118 By default, :class:`Cursor` is returned. It is possible to also give a
119 custom cursor through the `cursor` parameter, but it needs to
120 be a subclass of :class:`Cursor`
121
122 :param cursor: subclass of :class:`Cursor` or ``None`` for default
123 cursor.
124 :returns: :class:`Cursor` instance.
125
126 .. method:: close()
127
128 Immediately close the connection.
129
130 Close the connection now (rather than whenever `del` is executed).
131 The connection will be unusable from this point forward.
132
133 .. method:: ensure_closed()
134
135 A :ref:`coroutine <coroutine>` ends quit command and then closes
136 socket connection.
137
138 .. method:: autocommit(value)
139
140 A :ref:`coroutine <coroutine>` to enable/disable autocommit mode for
141 current MySQL session.
142 :param bool value: toggle atutocommit mode.
143
144 .. method:: get_autocommit()
145
146 Returns autocommit status for current MySQL sesstion.
147 :returns bool: current autocommit status.
148
149 .. method:: begin()
150
151 A :ref:`coroutine <coroutine>` to begin transaction.
152
153 .. method:: commit()
154
155 Commit changes to stable storage :ref:`coroutine <coroutine>`.
156
157 .. method:: rollback()
158
159 Roll back the current transaction :ref:`coroutine <coroutine>`.
160
161 .. method:: select_db(db)
162
163 A :ref:`coroutine <coroutine>` to set current db.
164
165 :param str db: database name
166
167 .. attribute:: closed
168
169 The readonly property that returns ``True`` if connections is closed.
170
171 .. attribute:: host
172
173 MySQL server IP address or name.
174
175 .. attribute:: port
176
177 MySQL server TCP/IP port.
178
179
180 .. attribute:: unix_socket
181
182 ySQL Unix socket file location.
183
184 .. attribute:: db
185
186 Current database name.
187
188 .. attribute:: user
189
190 User used while connecting to MySQL
191
192 .. attribute:: echo
193
194 Return echo mode status.
195
196 .. attribute:: encoding
197
198 Encoding employed for this connection.
199
200
201 .. attribute:: charset
202
203 Returns the character set for current connection.
204
205
206 .. _sql-mode: http://dev.mysql.com/doc/refman/5.0/en/sql-mode.html