{"id":14622,"library":"hopsworks-aiomysql","title":"Hopsworks Async MySQL Driver (aiomysql)","description":"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.","status":"active","version":"0.2.2","language":"en","source_language":"en","source_url":"https://github.com/logicalclocks/aiomysql","tags":["async","mysql","database","aiomysql","hopsworks"],"install":[{"cmd":"pip install hopsworks-aiomysql","lang":"bash","label":"Install `hopsworks-aiomysql`"}],"dependencies":[{"reason":"Core underlying library; although `hopsworks-aiomysql` bundles its own `aiomysql` source, it also lists it as a dependency, which can lead to confusion.","package":"aiomysql","optional":false}],"imports":[{"note":"Despite installing `hopsworks-aiomysql`, the actual Python module to import for the API is `aiomysql`.","wrong":"from hopsworks_aiomysql import create_pool","symbol":"create_pool","correct":"from aiomysql import create_pool"},{"note":"Despite installing `hopsworks-aiomysql`, the actual Python module to import for the API is `aiomysql`.","wrong":"from hopsworks_aiomysql import connect","symbol":"connect","correct":"from aiomysql import connect"}],"quickstart":{"code":"import asyncio\nimport os\nfrom aiomysql import create_pool\n\nasync def main():\n    # Database connection details, preferably from environment variables\n    pool = await create_pool(\n        host=os.environ.get('MYSQL_HOST', '127.0.0.1'),\n        port=int(os.environ.get('MYSQL_PORT', '3306')),\n        user=os.environ.get('MYSQL_USER', 'root'),\n        password=os.environ.get('MYSQL_PASSWORD', 'password'),\n        db=os.environ.get('MYSQL_DB', 'test_db'),\n        autocommit=True,\n        minsize=1,\n        maxsize=5\n    )\n    print(\"Connection pool created.\")\n\n    async with pool.acquire() as conn:\n        # 'conn' is an aiomysql.connection.Connection object\n        async with conn.cursor() as cur:\n            # 'cur' is an aiomysql.cursors.Cursor object\n            await cur.execute(\"SELECT 1+1;\")\n            (result,) = await cur.fetchone()\n            print(f\"Query result: {result}\")\n    \n    # Ensure the pool is closed gracefully\n    pool.close()\n    await pool.wait_closed()\n    print(\"Connection pool closed.\")\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Always use `from aiomysql import ...` for imports after installing `hopsworks-aiomysql`.","message":"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`.","severity":"gotcha","affected_versions":"All `hopsworks-aiomysql` versions"},{"fix":"Avoid installing `aiomysql` separately. If specific `aiomysql` version requirements arise, carefully review `hopsworks-aiomysql`'s bundled version and its declared dependency.","message":"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.","severity":"gotcha","affected_versions":"All `hopsworks-aiomysql` versions"},{"fix":"Refactor connection and cursor acquisition to use `async with pool.acquire() as conn:` and `async with conn.cursor() as cur:`.","message":"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.","severity":"breaking","affected_versions":"Upgrading from older `aiomysql` (pre-0.2.0) API to `hopsworks-aiomysql` 0.2.x."},{"fix":"Always prefix asynchronous calls with `await`, such as `await cur.execute(...)`, `await pool.acquire()`, `await pool.wait_closed()`, etc.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change `from hopsworks_aiomysql import ...` to `from aiomysql import ...`.","cause":"Incorrect import statement. The installed package name differs from the actual Python module name to be imported.","error":"ModuleNotFoundError: No module named 'hopsworks_aiomysql'"},{"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(...)`).","cause":"Attempting to `await` a connection object directly instead of using `async with` for context management, or forgetting `await` for methods that return awaitables.","error":"TypeError: object aiomysql.connection.Connection can't be used in 'await' expression"},{"fix":"Add `await` before the coroutine call, e.g., `pool = await create_pool(...)`.","cause":"An asynchronous function or coroutine was called but the `await` keyword was omitted.","error":"RuntimeWarning: coroutine 'create_pool' was never awaited"},{"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.","cause":"The MySQL server is not running, is inaccessible from the client machine, or the provided host/port/credentials are incorrect.","error":"OperationalError: (2003, \"Can't connect to MySQL server on '127.0.0.1' ([Errno 111] Connection refused)\")"}],"ecosystem":"pypi"}