Hopsworks Async MySQL Driver (aiomysql)

0.2.2 · active · verified Thu Apr 16

The `hopsworks-aiomysql` library provides an asynchronous MySQL client for Python, distributed by Logical Clocks, primarily for use within the Hopsworks ecosystem. It is effectively a distribution of the popular `aiomysql` library (currently version 0.2.2) and follows its API. It's actively maintained but release cadence is tied to Hopsworks platform updates rather than independent `aiomysql` releases.

Common errors

```
ModuleNotFoundError: No module named 'hopsworks_aiomysql'
```
cause Incorrect import statement. The installed package name differs from the actual Python module name to be imported.

fix Change `from hopsworks_aiomysql import ...` to `from aiomysql import ...`.
```
TypeError: object aiomysql.connection.Connection can't be used in 'await' expression
```
cause Attempting to `await` a connection object directly instead of using `async with` for context management, or forgetting `await` for methods that return awaitables.

fix Ensure `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
```
cause An asynchronous function or coroutine was called but the `await` keyword was omitted.

fix Add `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)")
```
cause The MySQL server is not running, is inaccessible from the client machine, or the provided host/port/credentials are incorrect.

fix Verify 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.

Warnings

gotcha The 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`.
Fix: Always use `from aiomysql import ...` for imports after installing `hopsworks-aiomysql`.
gotcha The `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.
Fix: Avoid installing `aiomysql` separately. If specific `aiomysql` version requirements arise, carefully review `hopsworks-aiomysql`'s bundled version and its declared dependency.
breaking Upstream `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.
Fix: Refactor connection and cursor acquisition to use `async with pool.acquire() as conn:` and `async with conn.cursor() as cur:`.
gotcha Forgetting 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.
Fix: Always prefix asynchronous calls with `await`, such as `await cur.execute(...)`, `await pool.acquire()`, `await pool.wait_closed()`, etc.

Install

pip install hopsworks-aiomysql Install `hopsworks-aiomysql`

Imports

create_pool
wrong:
```
from hopsworks_aiomysql import create_pool
```
correct:
```
from aiomysql import create_pool
```
Despite installing `hopsworks-aiomysql`, the actual Python module to import for the API is `aiomysql`.
connect
wrong:
```
from hopsworks_aiomysql import connect
```
correct:
```
from aiomysql import connect
```
Despite installing `hopsworks-aiomysql`, the actual Python module to import for the API is `aiomysql`.

Quickstart

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())

view raw JSON →