{"id":537,"library":"mysql-connector-python","title":"MySQL Connector/Python","description":"MySQL Connector/Python is a self-contained Python driver for communicating with MySQL servers, using an API that is compliant with the Python Database API Specification v2.0 (PEP 249). It also includes an implementation of the X DevAPI for working with the MySQL Document Store. The library is actively maintained, with its latest version (9.6.0) released in January 2026.","status":"active","version":"9.6.0","language":"python","source_language":"en","source_url":"https://github.com/mysql/mysql-connector-python","tags":["database","mysql","sql","driver","orm"],"install":[{"cmd":"pip install mysql-connector-python","lang":"bash","label":"Classic API (recommended)"},{"cmd":"pip install mysqlx-connector-python","lang":"bash","label":"X DevAPI (separate package)"}],"dependencies":[{"reason":"Optional, for DNS SRV record support.","package":"dnspython","optional":true},{"reason":"Optional, for GSSAPI authentication.","package":"gssapi","optional":true}],"imports":[{"note":"While 'import mysql.connector as mysql' works, directly calling mysql.connector.connect() is clearer as 'mysql' is a module, not the function.","wrong":"import mysql.connector as mysql\nmysql.connect()","symbol":"connect","correct":"import mysql.connector\ncnx = mysql.connector.connect(...)"}],"quickstart":{"code":"import os\nimport mysql.connector\nfrom mysql.connector import Error\n\nhost = os.environ.get('MYSQL_HOST', 'localhost')\nuser = os.environ.get('MYSQL_USER', 'root')\npassword = os.environ.get('MYSQL_PASSWORD', 'your_password')\ndatabase = os.environ.get('MYSQL_DATABASE', 'test_db')\n\nconn = None\ntry:\n    conn = mysql.connector.connect(\n        host=host,\n        user=user,\n        password=password,\n        database=database\n    )\n\n    if conn.is_connected():\n        print(f\"Connected to MySQL database: {database}\")\n        cursor = conn.cursor()\n\n        # Create a table (DDL - auto-commits)\n        cursor.execute(\"CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255))\")\n        print(\"Table 'users' ensured to exist.\")\n\n        # Insert data (DML - requires commit)\n        sql_insert = \"INSERT INTO users (name, email) VALUES (%s, %s)\"\n        data_to_insert = (\"Alice\", \"alice@example.com\")\n        cursor.execute(sql_insert, data_to_insert)\n        conn.commit() # Important: Commit changes for DML operations\n        print(f\"Inserted: {cursor.rowcount} row(s)\")\n\n        # Select data\n        cursor.execute(\"SELECT id, name, email FROM users\")\n        records = cursor.fetchall()\n        print(\"\\nData from 'users' table:\")\n        for row in records:\n            print(row)\n\n    else:\n        print(\"Failed to connect to MySQL database.\")\n\nexcept Error as e:\n    print(f\"Error connecting to MySQL: {e}\")\nfinally:\n    if conn and conn.is_connected():\n        conn.close()\n        print(\"MySQL connection closed.\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a MySQL database, create a table (DDL), insert data (DML), and query data using `mysql.connector`. It highlights the importance of `conn.commit()` for data manipulation statements. Database credentials are retrieved from environment variables for security."},"warnings":[{"fix":"Always call `connection.commit()` after `cursor.execute()` for DML statements within a transaction block, or if `autocommit` is not enabled.","message":"Data Manipulation Language (DML) operations (e.g., INSERT, UPDATE, DELETE) are not automatically committed to the database. You must explicitly call `connection.commit()` after executing DML statements for changes to persist. Data Definition Language (DDL) operations (e.g., CREATE TABLE, ALTER TABLE) are auto-committed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `use_pure=True` to your `mysql.connector.connect()` parameters, e.g., `mysql.connector.connect(..., use_pure=True)`.","message":"By default, MySQL Connector/Python attempts to use a C extension for improved performance. If the `libmysqlclient` library is missing or incompatible on your system (e.g., specific Python versions or platforms), this can lead to connection errors or failures. Setting `use_pure=True` in the `connect()` call forces the use of the pure Python implementation.","severity":"gotcha","affected_versions":"Versions 2.1.1 and higher, particularly affecting environments where the C extension is problematic."},{"fix":"For X DevAPI functionality, install `mysqlx-connector-python` via `pip install mysqlx-connector-python` and import from `mysqlx` instead of `mysql.connector`.","message":"X DevAPI support, which was previously part of the `mysql-connector-python` package, was separated into its own distinct package (`mysqlx-connector-python`) starting from version 8.3.0.","severity":"breaking","affected_versions":"8.3.0 and later"},{"fix":"Ensure your MySQL server version is 4.1 or higher. It is recommended to use MySQL Server version 8.0 or higher with the latest Connector/Python versions.","message":"MySQL Connector/Python does not support old MySQL Server authentication methods. This means it will not work with MySQL server versions prior to 4.1.","severity":"gotcha","affected_versions":"All versions of mysql-connector-python"},{"fix":"Verify all connection parameters are correct, check network connectivity, ensure the MySQL server is running and accessible from the client, and review MySQL server logs for connection attempts/failures. Implement robust exception handling and connection pooling for production applications.","message":"Frequent `mysql.connector.errors.OperationalError` often indicates underlying issues such as incorrect database credentials (host, user, password, database), network problems (firewall, unreachable host), or the MySQL server being down or inaccessible.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:46:43.937Z","next_check":"2026-07-10T00:00:00.000Z","problems":[{"fix":"Run `pip install mysql-connector-python` (or `pip3 install mysql-connector-python`) to install the package. If using a virtual environment, activate it first. Also, ensure no Python script in your project is named `mysql.py` or `mysql.connector.py`.","cause":"The 'mysql-connector-python' package is not installed, the Python environment is incorrect (e.g., virtual environment not activated), or there is a naming conflict with a local file named 'mysql.py'.","error":"ModuleNotFoundError: No module named 'mysql'"},{"fix":"Upgrade `mysql-connector-python` to a newer version (8.0.11 or higher generally supports it). Alternatively, configure the MySQL user to use the `mysql_native_password` plugin: `ALTER USER 'your_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';` then `FLUSH PRIVILEGES;`.","cause":"MySQL 8.0 and later versions use 'caching_sha2_password' as the default authentication plugin, which older versions of `mysql-connector-python` or some configurations do not support, leading to a mismatch.","error":"mysql.connector.errors.NotSupportedError: Authentication plugin 'caching_sha2_password' is not supported"},{"fix":"Verify the `host`, `port`, `user`, and `password` in your `mysql.connector.connect()` call. Ensure the MySQL server is running and accessible from where your Python script is executed. Check firewall settings if connecting remotely.","cause":"The Python application cannot establish a connection to the MySQL server. This often indicates incorrect connection parameters (host, port, user, password), the MySQL server is not running, or network/firewall issues prevent access.","error":"mysql.connector.errors.OperationalError: 2003 (HY000): Can't connect to MySQL server on 'localhost' (10061)"},{"fix":"Always wrap the `mysql.connector.connect()` call in a `try...except mysql.connector.Error` block and ensure the connection object is not `None` before attempting to create a cursor. Example: `try: cnx = mysql.connector.connect(...) except mysql.connector.Error as err: print(f'Connection error: {err}')`","cause":"This error occurs when the `mysql.connector.connect()` call fails (e.g., due to an `OperationalError` or incorrect credentials) and returns `None`, and subsequent code attempts to call `cursor()` on this `None` object.","error":"AttributeError: 'NoneType' object has no attribute 'cursor'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.5,"disk_size":"21.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":15.6,"disk_size":"33.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5.5,"disk_size":"35.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":5.6,"disk_size":"120M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":15.6,"disk_size":"133M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":5.6,"disk_size":"135M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":6.3,"disk_size":"23.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":16.9,"disk_size":"36.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.24,"mem_mb":6.3,"disk_size":"38.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":6.4,"disk_size":"123M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":16.9,"disk_size":"136M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":6.4,"disk_size":"138M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":6.1,"disk_size":"15.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":17.2,"disk_size":"28.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":6.1,"disk_size":"30.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.24,"mem_mb":6.2,"disk_size":"114M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.81,"mem_mb":17.2,"disk_size":"128M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":6.2,"disk_size":"129M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":6.3,"disk_size":"14.8M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.75,"mem_mb":18,"disk_size":"27.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":6.3,"disk_size":"29.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":6.4,"disk_size":"114M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.73,"mem_mb":18,"disk_size":"127M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":6.4,"disk_size":"129M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":5.4,"disk_size":"20.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.4,"mem_mb":15.2,"disk_size":"31.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":5.4,"disk_size":"35.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":5.5,"disk_size":"111M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"telemetry","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.35,"mem_mb":15.2,"disk_size":"123M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"webauthn","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":5.5,"disk_size":"126M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","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}]}}