{"id":1312,"library":"aiomysql","title":"aiomysql","description":"aiomysql is a MySQL driver for asyncio, enabling asynchronous interaction with MySQL databases using Python's `async`/`await` syntax. It provides a familiar DB-API 2.0-like interface adapted for asyncio. The current version is 0.3.2. Releases are infrequent, typically driven by critical bug fixes, `PyMySQL` updates, or community contributions.","status":"active","version":"0.3.2","language":"python","source_language":"en","source_url":"https://github.com/aio-libs/aiomysql","tags":["database","mysql","async","asyncio","db-api"],"install":[{"cmd":"pip install aiomysql","lang":"bash","label":"Install aiomysql"}],"dependencies":[],"imports":[{"symbol":"connect","correct":"import aiomysql\n\nconn = await aiomysql.connect(...)"},{"note":"While `from aiomysql import DictCursor` often works due to convenience imports, `from aiomysql.cursors import DictCursor` is the explicit and recommended path for cursor types.","wrong":"from aiomysql import DictCursor","symbol":"DictCursor","correct":"from aiomysql.cursors import DictCursor"},{"symbol":"create_pool","correct":"import aiomysql\n\npool = await aiomysql.create_pool(...)"}],"quickstart":{"code":"import asyncio\nimport os\nimport aiomysql\n\nasync def main():\n    # Get credentials from environment variables for security\n    db_host = os.environ.get('MYSQL_HOST', '127.0.0.1')\n    db_user = os.environ.get('MYSQL_USER', 'root')\n    db_password = os.environ.get('MYSQL_PASSWORD', 'password')\n    db_name = os.environ.get('MYSQL_DB', 'test_db')\n\n    try:\n        # Establish an asynchronous connection\n        async with await aiomysql.connect(\n            host=db_host,\n            user=db_user,\n            password=db_password,\n            db=db_name,\n            autocommit=True # Or manage transactions manually\n        ) as conn:\n            print(f\"Connected to MySQL on {db_host}\")\n\n            # Create a cursor object\n            async with conn.cursor() as cursor:\n                # Execute a query\n                await cursor.execute(\"SELECT VERSION();\")\n                # Fetch one result\n                version = await cursor.fetchone()\n                print(f\"MySQL Version: {version[0]}\")\n\n                # Execute another query (e.g., create a table)\n                await cursor.execute(\n                    \"CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255));\"\n                )\n                print(\"Table 'users' ensured to exist.\")\n\n                # Insert data\n                await cursor.execute(\"INSERT INTO users (name) VALUES (%s);\", (\"Alice\",))\n                await cursor.execute(\"INSERT INTO users (name) VALUES (%s);\", (\"Bob\",))\n                print(\"Inserted Alice and Bob.\")\n\n                # Select data\n                await cursor.execute(\"SELECT id, name FROM users;\")\n                users = await cursor.fetchall()\n                print(\"Users:\")\n                for user_id, name in users:\n                    print(f\"  ID: {user_id}, Name: {name}\")\n\n            # The connection is automatically closed when exiting the 'async with' block\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to connect to a MySQL database, create a table, insert data, and fetch results using `aiomysql`. It uses `async with` statements for robust connection and cursor management, ensuring resources are properly closed. Database credentials are retrieved from environment variables for security."},"warnings":[{"fix":"Ensure you `await` the `aiomysql.connect()` call directly, e.g., `conn = await aiomysql.connect(...)`. For older versions, you might need `conn = await asyncio.ensure_future(aiomysql.connect(...))` or similar.","message":"The `aiomysql.connect` function became an `async def` function in version 0.2.0. Previously, it returned a `Future`.","severity":"breaking","affected_versions":"<0.2.0"},{"fix":"Always prepend `await` to calls like `aiomysql.connect()`, `cursor.execute()`, `cursor.fetchone()`, `pool.acquire()`, and `pool.release()`.","message":"Forgetting to `await` asynchronous operations will lead to `RuntimeWarning: coroutine '...' was never awaited` or unexpected behavior.","severity":"gotcha","affected_versions":"All"},{"fix":"For applications with many concurrent database operations, use `await aiomysql.create_pool(...)` to manage a pool of connections. Acquire a connection from the pool with `await pool.acquire()` and release it with `pool.release(conn)` (or use `async with pool.acquire() as conn:`).","message":"Not using connection pooling for high-concurrency applications can lead to performance bottlenecks and resource exhaustion.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `async with await aiomysql.connect(...) as conn:` and `async with conn.cursor() as cursor:` to ensure connections and cursors are properly closed, even if errors occur.","message":"Improperly closing connections and cursors can lead to resource leaks.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your MySQL server is running and accessible from where your application is running. Verify the host, port, username, and password in your `aiomysql.connect()` parameters. Check firewall rules and network connectivity between your application and the database server.","message":"Failed to connect to the MySQL server. This can be caused by the server not running, incorrect host/port, firewall issues, or network configuration.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure the MySQL server is running, configured to accept connections from the application's host and port, and that no network or firewall rules are blocking the connection.","message":"The application failed to connect to the MySQL server. This error typically indicates that the database server is not running, is not accessible from the specified host and port, or network/firewall rules are preventing the connection.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-30T13:50:14.042Z","next_check":"2026-07-08T00:00:00.000Z","problems":[{"fix":"Ensure the MySQL server is running and accessible at '127.0.0.1' on port 3306, and verify that the connection parameters are correct.","cause":"This error occurs when the MySQL server is unreachable at the specified host and port.","error":"pymysql.err.OperationalError: (2003, \"Can't connect to MySQL server on '127.0.0.1'\")"},{"fix":"Ensure that the event loop is open and running before performing asynchronous operations.","cause":"This error occurs when an operation is attempted on a closed asyncio event loop.","error":"RuntimeError: Event loop is closed"},{"fix":"Check for network issues or bugs in the client-server communication that may cause packet loss or duplication.","cause":"This error indicates a mismatch in the packet sequence numbers during communication with the MySQL server.","error":"pymysql.err.InternalError: Packet sequence number wrong - got 1 expected 2"},{"fix":"Ensure that all transactions are properly committed or rolled back before releasing the connection.","cause":"This error occurs when attempting to release a connection that has an unfinished transaction.","error":"aiomysql raise InvalidRequestError: Cannot release a connection with not finished transaction"},{"fix":"Verify the SSL configuration and compatibility between aiomysql and the MySQL server.","cause":"This issue arises when aiomysql fails to establish an SSL connection, whereas pymysql succeeds.","error":"aiomysql does not work with ssl, but pymysql does work"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/aio-libs/aiomysql","docs":"https://aiomysql.readthedocs.io/","changelog":"https://github.com/aio-libs/aiomysql/blob/main/CHANGES.txt","pypi":"https://pypi.org/project/aiomysql/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","http-networking","web-framework"],"base_url":null,"auth_type":null,"install_checks":{"last_tested":"2026-05-30","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"0.3.2","pypi_latest":"0.3.2","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.12,"mem_mb":5.1,"disk_size":"18.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5.1,"disk_size":"18.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.09,"mem_mb":5.1,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":5.1,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.22,"mem_mb":6.3,"disk_size":"20.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":6.3,"disk_size":"20.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.19,"mem_mb":6.3,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":6.3,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.41,"mem_mb":9.2,"disk_size":"12.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":9.2,"disk_size":"12.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.39,"mem_mb":9.2,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":9.2,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.42,"mem_mb":9.7,"disk_size":"12.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":9.7,"disk_size":"12.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.37,"mem_mb":9.7,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":9.7,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.13,"mem_mb":5,"disk_size":"18.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5,"disk_size":"18.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.9,"import_time_s":0.1,"mem_mb":5,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiomysql","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":5,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]},"_links":{"self":"https://checklist.day/api/registry/aiomysql","v1":"https://checklist.day/v1/registry/aiomysql","v1_install":"https://checklist.day/v1/registry/aiomysql/install","v1_imports":"https://checklist.day/v1/registry/aiomysql/imports","v1_compatibility":"https://checklist.day/v1/registry/aiomysql/compatibility","v1_quickstart":"https://checklist.day/v1/registry/aiomysql/quickstart","docs":"https://checklist.day/docs"}}