Install & Compatibility
Where this runs
tested against v0.2.2 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.257s · 18.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.228s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_pool
✓ from aiomysql import create_pool
✗ from hopsworks_aiomysql import create_pool
Despite installing `hopsworks-aiomysql`, the actual Python module to import for the API is `aiomysql`.
connect
✓ from aiomysql import connect
✗ from hopsworks_aiomysql import connect
Despite installing `hopsworks-aiomysql`, the actual Python module to import for the API is `aiomysql`.
Establishes a connection pool to a MySQL database using environment variables for credentials, executes a simple query, and properly closes the pool. This example showcases the `async with` context managers for connections and cursors.
import asyncio
import os
from aiomysql import create_pool
async def main():
# Database connection details, preferably from environment variables
pool = await create_pool(
host=os.environ.get('MYSQL_HOST', '127.0.0.1'),
port=int(os.environ.get('MYSQL_PORT', '3306')),
user=os.environ.get('MYSQL_USER', 'root'),
password=os.environ.get('MYSQL_PASSWORD', 'password'),
db=os.environ.get('MYSQL_DB', 'test_db'),
autocommit=True,
minsize=1,
maxsize=5
)
print("Connection pool created.")
async with pool.acquire() as conn:
# 'conn' is an aiomysql.connection.Connection object
async with conn.cursor() as cur:
# 'cur' is an aiomysql.cursors.Cursor object
await cur.execute("SELECT 1+1;")
(result,) = await cur.fetchone()
print(f"Query result: {result}")
# Ensure the pool is closed gracefully
pool.close()
await pool.wait_closed()
print("Connection pool closed.")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
gotchaThe installed package is `hopsworks-aiomysql`, but the Python module to import and use is `aiomysql`. Attempts to `from hopsworks_aiomysql import ...` will result in a `ModuleNotFoundError`.fixAlways use `from aiomysql import ...` for imports after installing `hopsworks-aiomysql`.
affects: All `hopsworks-aiomysql` versions
gotchaThe `hopsworks-aiomysql` package bundles its own `aiomysql` source internally but also declares `aiomysql` as an `install_requires` dependency. This unusual setup can lead to confusion or potential version conflicts if another version of `aiomysql` is explicitly installed or if pip's dependency resolution acts unexpectedly.fixAvoid installing `aiomysql` separately. If specific `aiomysql` version requirements arise, carefully review `hopsworks-aiomysql`'s bundled version and its declared dependency.
affects: All `hopsworks-aiomysql` versions
breakingUpstream `aiomysql` (and thus `hopsworks-aiomysql` 0.2.x onwards) changed how connections and cursors are managed. Direct `await pool.acquire()` followed by `conn.close()` is deprecated in favor of `async with pool.acquire() as conn:` for proper resource handling and cleanup.fixRefactor connection and cursor acquisition to use `async with pool.acquire() as conn:` and `async with conn.cursor() as cur:`.
affects: Upgrading from older `aiomysql` (pre-0.2.0) API to `hopsworks-aiomysql` 0.2.x.
gotchaForgetting to `await` asynchronous calls to `aiomysql` methods (e.g., `cur.execute(...)` instead of `await cur.execute(...)`) will lead to `RuntimeWarning: coroutine was never awaited` and the operation not completing, potentially causing hangs or unexpected behavior.fixAlways prefix asynchronous calls with `await`, such as `await cur.execute(...)`, `await pool.acquire()`, `await pool.wait_closed()`, etc.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hopsworks_aiomysql'
Incorrect import statement. The installed package name differs from the actual Python module name to be imported.
fixChange `from hopsworks_aiomysql import ...` to `from aiomysql import ...`.
TypeError: object aiomysql.connection.Connection can't be used in 'await' expression
Attempting to `await` a connection object directly instead of using `async with` for context management, or forgetting `await` for methods that return awaitables.
fixEnsure `pool.acquire()` and `conn.cursor()` are used with `async with` (e.g., `async with pool.acquire() as conn:`) and other async methods are explicitly awaited (e.g., `await cur.execute(...)`).
RuntimeWarning: coroutine 'create_pool' was never awaited
An asynchronous function or coroutine was called but the `await` keyword was omitted.
fixAdd `await` before the coroutine call, e.g., `pool = await create_pool(...)`.
OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1' ([Errno 111] Connection refused)")
The MySQL server is not running, is inaccessible from the client machine, or the provided host/port/credentials are incorrect.
fixVerify that your MySQL server is running and accessible from the machine where your Python script is executing. Check firewall rules, network connectivity, and ensure the `host`, `port`, `user`, `password`, and `db` parameters are correct.
Upgrade
Version history
0.2.2latest on PyPI · released Jul 29, 2025
Audit
Dependencies
aiomysqlrequiredCore underlying library; although `hopsworks-aiomysql` bundles its own `aiomysql` source, it also lists it as a dependency, which can lead to confusion.
Resources
No resource links recorded.