aiomysql — API Reference

Connection

The library provides a way to connect to MySQL database with simple factory function aiomysql.connnect(). Use this function if you want just one connection to the database, consider connection pool for multiple connections.

Example:

import asyncio
import aiomysql

loop = asyncio.get_event_loop()

async def test_example():
    conn = await aiomysql.connect(host='127.0.0.1', port=3306,
                                  user='root', password='', db='mysql',
                                  loop=loop)

    cur = await conn.cursor()
    await cur.execute("SELECT Host,User FROM user")
    print(cur.description)
    r = await cur.fetchall()
    print(r)
    await cur.close()
    conn.close()

loop.run_until_complete(test_example())
connect(host="localhost", user=None, password="",
db=None, port=3306, unix_socket=None,
charset='', sql_mode=None,
read_default_file=None, conv=decoders, use_unicode=None,
client_flag=0, cursorclass=Cursor, init_command=None,
connect_timeout=None, read_default_group=None,
autocommit=False, echo=False
ssl=None, auth_plugin='', program_name='',
server_public_key=None, loop=None)

A coroutine that connects to MySQL.

The function accepts all parameters that pymysql.connect() does plus optional keyword-only loop and timeout parameters.

param str host

host where the database server is located, default: localhost.

param str user

username to log in as.

param str password

password to use.

param str db

database to use, None to not use a particular one.

param int port

MySQL port to use, default is usually OK.

param str unix_socket

optionally, you can use a unix socket rather than TCP/IP.

param str charset

charset you want to use, for example ‘utf8’.

param sql_mode

default sql-mode to use, like ‘NO_BACKSLASH_ESCAPES’

param read_default_file

specifies my.cnf file to read these parameters from under the [client] section.

param conv

decoders dictionary to use instead of the default one. This is used to provide custom marshalling of types. See pymysql.converters.

param use_unicode

whether or not to default to unicode strings.

param client_flag

custom flags to send to MySQL. Find potential values in pymysql.constants.CLIENT.

param cursorclass

custom cursor class to use.

param str init_command

initial SQL statement to run when connection is established.

param connect_timeout

Timeout in seconds before throwing an exception when connecting.

param str read_default_group

Group to read from in the configuration file.

param autocommit

Autocommit mode. None means use server default. (default: False)

param ssl

Optional SSL Context to force SSL

param auth_plugin

String to manually specify the authentication plugin to use, i.e you will want to use mysql_clear_password when using IAM authentication with Amazon RDS. (default: Server Default)

param program_name

Program name string to provide when handshaking with MySQL. (omitted by default)

Changed in version 1.0: sys.argv[0] is no longer passed by default

param server_public_key

SHA256 authenticaiton plugin public key value.

param loop

asyncio event loop instance or None for default one.

returns

Connection instance.

Representation of a socket with a mysql server. The proper way to get an instance of this class is to call aiomysql.connnect().

Its insterface is almost the same as pymysql.connection except all methods are coroutines.

The most important methods are:

aiomysql.cursor(cursor=None)

A coroutine that creates a new cursor object using the connection.

By default, Cursor is returned. It is possible to also give a custom cursor through the cursor parameter, but it needs to be a subclass of Cursor

Parameters

cursor – subclass of Cursor or None for default cursor.

Returns

Cursor instance.

aiomysql.close()

Immediately close the connection.

Close the connection now (rather than whenever del is executed). The connection will be unusable from this point forward.

aiomysql.ensure_closed()

A coroutine ends quit command and then closes socket connection.

aiomysql.autocommit(value)

A coroutine to enable/disable autocommit mode for current MySQL session. :param bool value: toggle atutocommit mode.

aiomysql.get_autocommit()

Returns autocommit status for current MySQL sesstion. :returns bool: current autocommit status.

aiomysql.begin()

A coroutine to begin transaction.

aiomysql.commit()

Commit changes to stable storage coroutine.

aiomysql.rollback()

Roll back the current transaction coroutine.

aiomysql.select_db(db)

A coroutine to set current db.

Parameters

db (str) – database name

aiomysql.closed

The readonly property that returns True if connections is closed.

aiomysql.host

MySQL server IP address or name.

aiomysql.port

MySQL server TCP/IP port.

aiomysql.unix_socket

ySQL Unix socket file location.

aiomysql.db

Current database name.

aiomysql.user

User used while connecting to MySQL

aiomysql.echo

Return echo mode status.

aiomysql.encoding

Encoding employed for this connection.

aiomysql.charset

Returns the character set for current connection.