{"id":999,"library":"mysqlclient","title":"mysqlclient","description":"mysqlclient is a Python interface to MySQL that acts as a fork of MySQLdb1, providing Python 3 support and numerous bug fixes. It is a C extension that wraps the official MySQL C API (libmysqlclient), offering superior performance compared to pure-Python drivers. The library currently operates at version 2.2.8 and maintains a healthy release cadence, with at least one new version released in the past three months.","status":"active","version":"2.2.8","language":"python","source_language":"en","source_url":"https://github.com/PyMySQL/mysqlclient","tags":["database","mysql","sql","db-api"],"install":[{"cmd":"pip install mysqlclient","lang":"bash","label":"Basic Installation"},{"cmd":"sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config\npip install mysqlclient","lang":"bash","label":"Debian/Ubuntu (with system dependencies)"},{"cmd":"sudo yum install python3-devel mysql-devel pkgconfig\npip install mysqlclient","lang":"bash","label":"Red Hat/CentOS (with system dependencies)"},{"cmd":"brew install mysql pkg-config\npip install mysqlclient","lang":"bash","label":"macOS (Homebrew, with system dependencies)"}],"dependencies":[{"reason":"mysqlclient is a C extension and requires Python development headers for compilation. Examples: python3-dev (Debian/Ubuntu), python3-devel (Red Hat/CentOS).","package":"Python 3 Development Headers","optional":false},{"reason":"mysqlclient links against the MySQL C API (libmysqlclient). Examples: default-libmysqlclient-dev (Debian/Ubuntu), mysql-devel (Red Hat/CentOS), mysql-connector-c (macOS).","package":"MySQL Client Development Headers and Libraries","optional":false},{"reason":"The library compiles C code during installation. Examples: build-essential (Debian/Ubuntu), Development Tools (Red Hat/CentOS), Xcode Command Line Tools (macOS), Build Tools for Visual Studio (Windows).","package":"C/C++ Compiler","optional":false},{"reason":"On POSIX systems, mysqlclient uses pkg-config to find compiler/linker flags. It is required for successful compilation if pre-built wheels are not available.","package":"pkg-config","optional":false}],"imports":[{"note":"MySQLdb is the higher-level, DB API-compliant module. _mysql is a lower-level, non-portable module that directly wraps the MySQL C API and should generally be avoided for application development.","wrong":"import _mysql","symbol":"MySQLdb","correct":"import MySQLdb"},{"symbol":"connect","correct":"from MySQLdb import connect"}],"quickstart":{"code":"import MySQLdb\nimport os\n\nDB_HOST = os.environ.get('MYSQL_HOST', '127.0.0.1')\nDB_USER = os.environ.get('MYSQL_USER', 'root')\nDB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'your_password') # Replace with a secure method for production\nDB_NAME = os.environ.get('MYSQL_DATABASE', 'testdb')\n\ntry:\n    # Establish a connection\n    conn = MySQLdb.connect(\n        host=DB_HOST,\n        user=DB_USER,\n        password=DB_PASSWORD,\n        database=DB_NAME\n    )\n    cursor = conn.cursor()\n\n    # Execute a query\n    cursor.execute(\"SELECT VERSION();\")\n    version = cursor.fetchone()\n    print(f\"Database version: {version[0]}\")\n\n    # Example: Create a table (if it doesn't exist)\n    cursor.execute(\"CREATE TABLE IF NOT EXISTS my_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))\")\n    print(\"Table 'my_table' ensured.\")\n\n    # Example: Insert data\n    cursor.execute(\"INSERT INTO my_table (name) VALUES (%s)\", (\"Test Name\",))\n    conn.commit()\n    print(\"Data inserted.\")\n\n    # Example: Read data\n    cursor.execute(\"SELECT id, name FROM my_table\")\n    rows = cursor.fetchall()\n    for row in rows:\n        print(f\"ID: {row[0]}, Name: {row[1]}\")\n\nfinally:\n    # Close the cursor and connection\n    if 'cursor' in locals() and cursor:\n        cursor.close()\n    if 'conn' in locals() and conn:\n        conn.close()\n    print(\"Database connection closed.\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a MySQL database, execute a simple query, create a table, insert data, and retrieve data using `mysqlclient`. Connection parameters are loaded from environment variables for flexibility. Remember to replace placeholder credentials with actual, securely managed values in a production environment."},"warnings":[{"fix":"Before installing `mysqlclient`, install the necessary system packages. For Debian/Ubuntu: `sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config`. For Red Hat/CentOS: `sudo yum install python3-devel mysql-devel pkgconfig`. For macOS: `brew install mysql pkg-config`. For Windows, ensure 'Build Tools for Visual Studio' and 'MariaDB Connector/C' are installed.","message":"Installation via `pip install mysqlclient` often fails without pre-installed system-level MySQL client development headers, a C/C++ compiler, and `pkg-config` (on POSIX systems). This is because `mysqlclient` is a C extension that needs to compile against native libraries.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure `pkg-config` is installed on your system. For Debian/Ubuntu: `sudo apt-get install pkg-config`. For Red Hat/CentOS: `sudo yum install pkgconfig`.","message":"In version 2.2.0, `mysqlclient` switched from using `mysql_config` to `pkg-config` for discovering compiler and linker flags during installation. If `pkg-config` is not installed or configured correctly, compilation will fail.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Update your `executemany` calls. For example, change `executemany(\"INSERT INTO t (data) VALUES (%s)\", [1, 2, 3])` to `executemany(\"INSERT INTO t (data) VALUES (%s)\", [(1,), (2,), (3,)])`.","message":"The `Cursor.executemany()` method's argument format changed in version 2.2.0. It now expects a sequence of tuples, even for single-value inserts, instead of a sequence of scalar values.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Use `password` and `database` keyword arguments instead.","message":"The `passwd` and `db` keyword arguments in the `MySQLdb.connect()` function are deprecated. They will be removed in future versions.","severity":"deprecated","affected_versions":">=2.1.0"},{"fix":"Ensure that each `Connection` object is used by only one thread at a time. If multi-threading is required, establish a separate `Connection` for each thread or use a connection pooling mechanism that manages thread-safe access.","message":"As of v2.2.8, `mysqlclient` offers experimental support for free-threaded Python (importing `MySQLdb` doesn't enable the GIL). However, the library explicitly states that it *does not* support simultaneous operations on a single `Connection` object from multiple threads concurrently. Doing so will result in undefined behavior.","severity":"gotcha","affected_versions":">=2.2.8"},{"fix":"Avoid using `Connection.shutdown()` and `Connection.kill()`. If server administration is required, use dedicated MySQL administration tools or SQL commands executed via a standard cursor.","message":"The `Connection.shutdown()` and `Connection.kill()` methods are deprecated, as the underlying MySQL C API functions (`mysql_shutdown()` and `mysql_kill()`) were removed in MySQL 8.3. These methods will emit a `DeprecationWarning` in future versions.","severity":"deprecated","affected_versions":">=2.2.2 (warning will appear in future versions)"},{"fix":"If encountering compilation errors on macOS, a common workaround is to modify the `mysql_config` script (usually found in `/usr/local/bin` or a similar path). Specifically, change the `libs` definition from `libs=\"-L$pkglibdir\" libs=\"$libs -l \"` to `libs=\"-L$pkglibdir\" libs=\"$libs -lmysqlclient -lssl -lcrypto\"`.","message":"On macOS, certain versions of `mysql-connector-c` installed via Homebrew or official packages may have incorrect default configuration options, causing `mysqlclient` compilation errors. This often manifests as linker errors related to `ssl` or `crypto` libraries.","severity":"gotcha","affected_versions":"All versions on macOS with problematic `mysql-connector-c` installations"}],"env_vars":null,"search_vec":"'2.2.8':52 '3':18 'act':10 'api':35,76 'bug':22 'c':27,34 'cadenc':58 'compar':40 'current':48 'databas':71 'db':75 'db-api':74 'driver':45 'extens':28 'fix':23 'fork':13 'healthi':56 'interfac':6 'least':61 'libmysqlcli':36 'librari':47 'maintain':54 'month':70 'mysql':8,33,72 'mysqlclient':1,2 'mysqldb1':15 'new':63 'numer':21 'offer':37 'offici':32 'one':62 'oper':49 'past':68 'perform':39 'provid':16 'pure':43 'pure-python':42 'python':5,17,44 'releas':57,65 'sql':73 'superior':38 'support':19 'three':69 'version':51,64 'wrap':30","created_at":"2026-03-29T08:38:11.684547+00:00","updated_at":"2026-04-16T17:18:25.179766+00:00","problems":{"verify_error":"× Failed to build `mysqlclient==2.2.8`\n  ├─▶ The build backend returned an error\n  ╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)\n\n      [stdout]\n      Trying pkg-config --exists mysqlclient\n      Command 'pkg-config --exists mysqlclient' returned non-zero exit status\n      "},"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.8","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/PyMySQL/mysqlclient","docs":"https://mysqlclient.readthedocs.io/","changelog":null,"pypi":"https://pypi.org/project/mysqlclient/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":"stale"}}