asyncmy

library0.2.14pypypi✓ verified 22d ago

asyncmy is a high-performance asynchronous MySQL/MariaDB driver for Python, leveraging `asyncio`. It reuses much of the `PyMySQL` and `aiomysql` codebase but significantly boosts performance by rewriting its core protocol in Cython. The library offers an API compatible with `aiomysql` and supports advanced features like the MySQL replication protocol. It is actively maintained, with releases typically occurring as new features or performance improvements are integrated.

database http-networking

pip install asyncmy

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · ASYNCMY

asyncmy

databasepythonv0.2.14

Install

1.9s avg

Import

307ms

Disk

42MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.14 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.314s · 40.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.9s · import 0.300s · 46MB

42MB installed

● package 42MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

connect

✓ from asyncmy import connect

create_pool

✓ from asyncmy import create_pool

For managing multiple database connections efficiently.

DictCursor

✓ from asyncmy.cursors import DictCursor

A cursor that returns rows as dictionaries.

BinLogStream

✓ from asyncmy.replication import BinLogStream

For working with MySQL's replication protocol.

This example demonstrates connecting to a MySQL database, executing DDL and DML operations, and fetching results using a DictCursor. It uses environment variables for connection parameters and ensures proper resource cleanup using `async with` and a `finally` block.

import asyncio import os from asyncmy import connect from asyncmy.cursors import DictCursor async def main(): conn = await connect( host=os.environ.get('MYSQL_HOST', '127.0.0.1'), user=os.environ.get('MYSQL_USER', 'root'), password=os.environ.get('MYSQL_PASSWORD', ''), db=os.environ.get('MYSQL_DB', 'test_db'), port=int(os.environ.get('MYSQL_PORT', 3306)) ) try: async with conn.cursor(cursor=DictCursor) as cursor: await cursor.execute("CREATE DATABASE IF NOT EXISTS test_db") await cursor.execute("USE test_db") await cursor.execute( """ CREATE TABLE IF NOT EXISTS users ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255), email VARCHAR(255) ) """ ) await cursor.execute( "INSERT INTO users (name, email) VALUES (%s, %s)", ("Alice", "alice@example.com") ) await cursor.execute("SELECT id, name, email FROM users WHERE name = %s", ("Alice",)) result = await cursor.fetchone() print(f"Fetched user: {result}") finally: await conn.close() if __name__ == '__main__': asyncio.run(main())

Debug

Known issues

gotchaOn Windows, `asyncmy` uses Cython extensions which require Microsoft C++ Build Tools to be installed for successful installation via pip. Without these tools, installation may fail or result in a non-optimized pure-Python fallback.

fix

Download and install Microsoft C++ Build Tools from the Visual Studio website before running `pip install asyncmy`.

affects: All versions

gotchaAlways ensure connections and cursors are properly closed to prevent resource leaks. While `async with` statements handle this for contexts, direct `connect()` calls require an explicit `await conn.close()`.

fix

Use `async with conn.cursor(...)` and `async with asyncmy.create_pool(...)` where possible. For direct `connect()`, always pair with `await conn.close()` in a `finally` block.

affects: All versions

gotchaCommon `asyncio` pitfalls like 'fire and forget' tasks (not awaiting coroutines) or blocking the event loop with synchronous operations can lead to unexpected behavior, lost exceptions, or reduced performance. `asyncmy` operations are all awaitable and should be used within an `asyncio` event loop.

fix

Ensure all `async` functions are `await`ed. Use `asyncio.create_task()` for background tasks and `asyncio.gather()` for concurrent execution. Avoid blocking I/O or CPU-bound synchronous calls directly in the event loop.

affects: All versions

breakingThe `loop` argument for `asyncmy.connect()` and `asyncmy.create_pool()` was removed in version 0.2.1, as passing an explicit event loop is generally no longer necessary or recommended in modern `asyncio`.

fix

Remove the `loop=asyncio.get_event_loop()` argument from `connect()` and `create_pool()` calls. `asyncmy` will automatically use the current running event loop.

affects: >=0.2.1

Errors

Common errors & fixes

sqlalchemy.exc.InvalidRequestError: The asyncio extension requires an async driver to be used. The loaded 'mysqldb' is not async.

This error occurs when attempting to use SQLAlchemy's asyncio extension with a synchronous MySQL driver like 'mysqldb'.

fix

Ensure you're using an asynchronous driver by modifying your database URL to include 'asyncmy', e.g., 'mysql+asyncmy://user:password@localhost/dbname'. Additionally, install the required packages: 'pip install asyncmy sqlalchemy[asyncio]'.

asyncmy.errors.ProgrammingError: (1064, "You have an error in your SQL syntax...")

This error arises when using JSON data types with an unsupported MySQL or MariaDB version.

fix

Upgrade your database to MySQL 5.7.8+ or MariaDB 10.2.7+ to ensure JSON data type support.

asyncmy.errors.PoolError: Pool is full

This error indicates that all connections in the connection pool are in use, and no additional connections can be allocated.

fix

Increase the 'maxsize' parameter of your connection pool configuration to allow more connections, and ensure that connections are properly released after use by utilizing context managers.

RuntimeWarning: coroutine 'function_name' was never awaited

An `async` function (coroutine) was called but not `await`ed, meaning its execution was scheduled but never explicitly run or waited for by the `asyncio` event loop.

fix

Ensure that all calls to `async` functions are preceded by `await` within another `async` function, or run directly using `asyncio.run(main_coroutine())` for the top-level entry point.

asyncmy.errors.OperationalError: (2013, 'Lost connection to MySQL server during query')

The connection to the MySQL server was unexpectedly closed, often due to network issues, server restarts, or an idle connection timing out on the server or an intermediate proxy (like Docker Swarm's default 15-minute TCP idle timeout).

fix

Implement a connection pool with `pool_recycle` set to a value less than the MySQL or proxy's idle timeout. For SQLAlchemy, configure `create_async_engine(..., pool_recycle=seconds)`.

Upgrade

Version history

0.2.14latest on PyPI · released Aug 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/long2ice/asyncmy ↗

packagehttps://pypi.org/project/asyncmy/ ↗

docshttps://github.com/long2ice/asyncmy ↗