mysql-connector-python

MySQL Connector/Python is Oracle’s official driver for connecting Python applications to MySQL servers and MySQL HeatWave. It implements the Python Database API Specification v2.0 (PEP 249) as the classic mysql.connector API, while a separate mysqlx module implements MySQL’s document-oriented X DevAPI for working with the MySQL Document Store using a MongoDB-like find/collection interface.

The driver ships three parallel implementations of the connection/cursor layer: a pure-Python path (connection.py, cursor.py), a compiled C-extension path (connection_cext.py, cursor_cext.py) that wraps MySQL’s C client library for lower overhead, and a native asyncio path under mysql.connector.aio mirroring the same abstractions for non-blocking use in async frameworks. Authentication is handled through a pluggable plugin system supporting caching_sha2_password, sha256_password, Kerberos, LDAP SASL, OpenID Connect, WebAuthn, and OCI IAM, and connection pooling, OpenTelemetry span instrumentation, and an optional HeatWave GenAI/AutoML bridge (mysql.ai) round out the package.

What You Get

• A PEP 249-compliant classic API (mysql.connector) plus the document-store X DevAPI (mysqlx)
• Synchronous and native asyncio connection, cursor, and pooling implementations under mysql.connector.aio
• An optional compiled C extension (_mysql_connector) wrapping MySQL’s C client library alongside the pure-Python path
• Pluggable authentication plugins covering SHA-256, caching_sha2, Kerberos, LDAP SASL, OpenID Connect, WebAuthn, and OCI IAM
• Built-in connection pooling via MySQLConnectionPool, available for both sync and async APIs
• OpenTelemetry span instrumentation for queries and connections
• An optional HeatWave GenAI/AutoML bridge (mysql.ai) exposing LangChain- and Scikit-Learn-compatible classes

Common Use Cases

• Connecting Python web and API backends to MySQL or MySQL HeatWave databases
• Running database I/O inside asyncio-based frameworks without blocking the event loop
• Querying MySQL’s Document Store through the X DevAPI’s find/collection interface
• Authenticating against MySQL with Kerberos, LDAP SASL, or WebAuthn instead of plaintext passwords
• Training Scikit-Learn-compatible models directly against HeatWave via the mysql.ai AutoML bridge

Under The Hood

Architecture The driver is layered around an abstract base, MySQLConnectionAbstract in abstracts.py, with three concrete implementations that all satisfy the same interface: MySQLConnection (connection.py) is the pure-Python wire-protocol implementation built on protocol.py and network.py; CMySQLConnection (connection_cext.py) delegates protocol handling to the compiled _mysql_connector C extension for lower overhead; and mysql.connector.aio mirrors both the abstract base and the pure-Python connection/cursor/pooling classes on top of asyncio for non-blocking I/O. Authentication is factored out into a plugins/ package (duplicated under aio/plugins/) so each mechanism (caching_sha2, SHA-256, Kerberos, LDAP SASL, OpenID Connect, WebAuthn, OCI IAM) is a swappable module rather than a branch inside the connection class. pooling.py sits above the connection layer and is shared conceptually between sync and async pool implementations. Cross-cutting concerns — data type conversion (conversion.py), charset tables (charsets.py), and error types (errors.py, errorcode.py) — are isolated into their own modules used by every connection variant, so changing the wire protocol (protocol.py) or type conversion touches a well-defined seam rather than three duplicated code paths.

Tech Stack The package is pure Python 3.10+ with an optional C extension (src/mysql_capi.c, src/mysql_connector.c) built via setuptools/Extension in setup.py, using a custom cpydist build backend (BuildExt, DistWheel, DistBinary) for cross-platform binary wheels. Optional extras add dnspython for DNS-SRV lookups, gssapi for Kerberos, fido2 for WebAuthn, and the opentelemetry-api/opentelemetry-sdk/opentelemetry-exporter-otlp-proto-http stack for tracing. The optional mysql.ai module integrates with langchain, pandas, and scikit-learn for HeatWave GenAI/AutoML workflows, kept out of the base install to keep the core driver lightweight. There is no external ORM or web framework dependency — this package sits underneath tools like SQLAlchemy or Django’s MySQL backend.

Code Quality The project has an extensive test suite under tests/ (over 25 top-level test modules plus cext/, aio-specific, otel, and issues subdirectories, with 100+ test functions in test_connection.py alone) exercising both the pure-Python and C-extension connection paths against a real or mocked MySQL server. Type hints are used throughout (from typing import ... in every core module) with a py.typed marker shipped for both mysql.connector and mysql.connector.aio, and .pre-commit-config.yaml wires up black, isort, and mypy --disallow-untyped-defs as enforced pre-commit hooks. Errors are modeled as a typed exception hierarchy rooted at Error (errors.py) with structured error codes (errorcode.py) rather than bare exceptions, and connection/cursor classes are explicit ABCs (abstracts.py) rather than duck-typed structures.

API Design The classic API deliberately mirrors PEP 249 (connect(), .cursor(), .execute(), .fetchone()) so it’s a drop-in replacement for any DB-API-compliant MySQL driver, minimizing onboarding cost for anyone who has used another Python database driver. The async API (mysql.connector.aio) keeps the same method names as async equivalents (await cnx.cursor(), await cur.execute()), so switching from sync to async code is a mechanical await-insertion exercise rather than a new API to learn. The X DevAPI (mysqlx) instead adopts a fluent, chainable builder style (collection.find(...).bind(...).limit(...).execute()) that intentionally reads like MongoDB’s driver API, which is a deliberate departure from PEP 249 aimed at developers coming from document-store tooling.