MySQL Connector/Python: the MySQL client protocol implemented in Python

The protocol implemented in Python, with no client library needed

MySQL Connector/Python is an implementation of the MySQL client/server protocol written completely in Python. The consequence that matters in practice is stated in the project description: no MySQL libraries are needed, and no compilation is necessary to run it.

That is a different proposition from most database drivers. A driver that wraps libmysqlclient inherits that library's platform support, its release cadence and its build requirements. A pure Python driver is installable wherever Python runs, including platforms where a C client library is awkward to provide, and it upgrades with the interpreter rather than with the operating system's package manager.

The driver is compliant with the Python Database API Specification v2.0, PEP 249, which is the interface contract most Python database tooling expects. The project calls that interface the Classic API. Anything written against the DB API conventions, cursor handling, parameter substitution and the connection lifecycle, works with it.

The audience is Python developers and teams who need a supported MySQL driver without the deployment friction of a native client. The repository is the Oracle-maintained MySQL Connector/Python project, with the copyright headers in the source naming Oracle and its affiliates, and the documentation is published at dev.mysql.com/doc/connector-python/en.

The project also ships a second interface, an implementation of the X DevAPI, which is an application programming interface for working with the MySQL Document Store. That second API is the main reason the repository contains two separate connector directories rather than one.

Two packages installed separately, not one

A detail that trips people up on first contact is that Connector/Python contains the Classic and X DevAPI connector APIs, which are installed separately. They are two distributions with two import names and two roles.

The Classic API installs as:

$ pip install mysql-connector-python

The X DevAPI installs as:

$ pip install mysqlx-connector-python

So a project that only needs the traditional relational interface can install one package and ignore the other entirely, and a project using the document store installs the X DevAPI and does not need the Classic API unless it also wants relational access.

The repository layout mirrors this split at the top level, with a mysql-connector-python/ directory and a mysqlx-connector-python/ directory side by side, along with a shared pyproject.toml, an automation/ directory, and the top-level files for changes, contribution and security.

For packaging, binaries are distributed in two formats, RPM and WHEEL. The source code is distributed as a compressed file from which a wheel package can be built. The recommended installation route is pip, which relies on the WHEEL packages, and the documentation points at the official MySQL Connector/Python Installation page for installing from an RPM or building and installing a wheel from a source distribution.

One practical instruction in the README is worth repeating: before installing a package with pip, it is strongly suggested to have the most recent pip version installed on the system, updating it if needed or using the standalone pip installer.

Optional extras and the feature flags they switch on

The connector packages allow you to install optional dependencies to unleash certain functionalities. The mechanism is standard Python extras syntax, with a distinct set per API.

For the Classic API, telemetry is installed as an extra:

# 3rd party packages to unleash the telemetry functionality are installed
$ pip install mysql-connector-python[telemetry]

For the X DevAPI, the extra is compression:

# 3rd party packages to unleash the compression functionality are installed
$ pip install mysqlx-connector-python[compression]

The full set of available options is listed. The Classic API connector offers dns-srv, gssapi, webauthn and telemetry. The X DevAPI connector offers dns-srv and compression.

Two of these deserve a word because they point at infrastructure decisions rather than code. dns-srv means the connector can resolve a host through DNS SRV records, which is how you address a clustered deployment or a service behind a load balancer without hardcoding an endpoint. gssapi is for Kerberos style authentication in an enterprise environment, and webauthn covers passwordless sign-in with a security key.

The README is careful about the framing. This installation option can be seen as a shortcut to install all the dependencies needed by a particular feature, and it is optional, with the note that you are free to install the required dependencies by yourself. So the extras are convenience, not a requirement, and a team with a pinned dependency policy can install the underlying libraries directly and skip the shortcut.

The four feature areas the project lists for the Classic API are asynchronous connectivity, the C extension, telemetry and the X DevAPI.

The Classic API shape: connect, cursor, execute, fetch, close

The Classic API sample in the README is short enough to take in one look, and it follows the DB API conventions closely.

import mysql.connector

cnx = mysql.connector.connect(
    host="127.0.0.1",
    port=3306,
    user="mike",
    password="s3cre3t!")

cur = cnx.cursor()
cur.execute("SELECT CURDATE()")
row = cur.fetchone()
print("Current date is: {0}".format(row[0]))

cnx.close()

The steps are the familiar ones: import the module, open a connection with the host, port, user and password, take a cursor from the connection, execute a statement, fetch a row, and close the connection explicitly.

Two details are worth noticing. The connection is closed explicitly at the end rather than left to garbage collection, which is the right habit for a database handle in a long-running process but is also a reminder that the driver does not hide resource management from you. And the query result is accessed by index, row[0], rather than by column name, which is how PEP 249 describes a plain cursor without a dictionary cursor.

For a project moving from another MySQL driver, the practical point is that this is the interface most Python database libraries and ORMs already expect, so a migration usually touches connection setup rather than every query.

The X DevAPI shape: sessions, schemas and bound parameters

The X DevAPI is a different style of interface, aimed at the document store, and the sample shows why it is a separate package rather than a mode of the first one.

import mysqlx

session = mysqlx.get_session(
   host="127.0.0.1",
   port=33060,
   user="mike",
   password="s3cr3t!")
schema = session.get_schema("test")
collection = schema.get_collection("my_collection")

result = collection.find("name like :param") \
                   .bind("param", "S%") \
                   .limit(1) \
                   .execute()

The connection model differs first. Instead of a connection and a cursor, you open a session, and the session resolves to a schema and then to a collection. The port is different too, 33060 in the sample rather than the 3306 used by the Classic API.

The query model differs as well. The find call takes a filter expression with a named placeholder, and the parameters are bound through a chain of calls, bind, limit and execute, before the statement is run. That chaining is the X DevAPI style, and it is why the package ships its own client rather than reusing the Classic one.

The result of find is not fetched row by row in the sample. The chain ends at execute(), and the query returns a result object, which reflects that the document store API is designed for cursors over documents rather than the classic row-fetch loop.

For a team, the choice is straightforward. If your data is relational, the Classic API is the relevant one. If you are using the MySQL Document Store and want it from Python, the X DevAPI package is the one that talks to it.

The optional C extension and what it actually changes

One of the four features listed for the Classic API is a C-extension, and the repository layout shows there is native code in the tree. The top-level entries include a .clang-format file and a .gitmodules file, and the presence of a C extension in a driver otherwise written in Python is a deliberate option rather than a requirement.

The distinction that matters is that the pure Python implementation is complete enough to run the driver without any compilation. The C extension is an additional choice. That framing is important because the project description says no compilation is necessary to run the driver, and a team that reads that sentence should not assume that a C toolchain is a prerequisite.

What a C extension typically buys is speed in the hot paths, most obviously the parsing and serialisation of protocol data on the way in and out. The project does not document, in the README, a benchmark or a decision rule for when to enable it, and it does not describe a configuration switch for it in the installation instructions, so choosing it means reading the connector documentation rather than the README.

The same restraint applies to the other listed features. Asynchronous connectivity is named as a feature with its own documentation page, and telemetry is named as a feature that needs third-party packages installed through the extra. None of them change the fundamental shape of the code you write, which remains DB API style for the Classic API.

Licensing under GPLv2 with the Universal FOSS Exception

The licensing summary in the project metadata calls it a custom licence that GitHub cannot classify, and the pointer to the truth is the README's own instruction: refer to the README.txt and LICENSE.txt files available in the repository for further details.

What the licence header in the source file says is more informative than the label. The program is free software distributed under the terms of the GNU General Public License, version 2.0. It is also described as designed to work with certain software, including but not limited to OpenSSL, that is licensed under separate terms, and the authors grant an additional permission to link the program and derivative works with the separately licensed software that they have either included or referenced in the documentation.

The Universal FOSS Exception, version 1.0, applies to the file as well, with a copy at the Oracle FOSS exception address. The standard disclaimer applies, that the program is distributed in the hope that it will be useful, but without any warranty.

So the practical shape is GPLv2 with a link exception for separately licensed dependencies, plus an explicit linking permission. That combination is what allows the connector to be used in a proprietary application that links it, rather than requiring the whole application to become GPL.

This article does not give legal advice, and the classification mismatch means the short summary in the README metadata is not something to rely on. Read LICENSE.txt and README.txt for the terms that actually apply to your distribution, and check SECURITY.md for how to report a vulnerability, since the project has a dedicated file for that.

Where the packages come from and how the project moves

The distribution story is straightforward once the two packages are separated.

Binaries ship as RPM and WHEEL. The source is distributed as a compressed archive that can be turned into a wheel, and the build configuration in pyproject.toml declares setuptools and wheel with the setuptools build backend. pip is the recommended route, with the official installation documentation covering the RPM path and the from-source wheel build.

The repository itself is on the trunk branch, not master, which is worth knowing if you script against the default branch. There are no GitHub releases for the project, so version tracking happens through the packages themselves and through the CHANGES.txt file at the repository root.

The last push was on 2026-07-29, and the project is not archived. The repository also carries a.pre-commit-config.yaml, which is consistent with a project that expects contributions to pass formatting and lint checks before review, and a CONTRIBUTING.md that the README points to for details on how to report issues and send code.

For a driver maintained by the vendor of the database itself, that combination of a small public surface, an explicit licence file and a security policy is what you are really buying: an implementation of the interface standards Python already agreed on.

Editorial conclusion

Adopt MySQL Connector/Python when your project must talk to MySQL from Python without depending on a compiled client library, when you need the document store through the X DevAPI, or when you need one of the optional extras such as telemetry, compression, dns-srv, gssapi or webauthn. Skip it if your stack already standardises on another driver and the extras do not apply, or if the GPLv2 with Universal FOSS Exception terms do not match your distribution model. Before adopting, read LICENSE.txt and README.txt rather than the short summary in the README, confirm whether the optional C extension is wanted in your environment, and check the support for the authentication method your server requires.

Frequently asked questions

Official sources

1. Issues
2. mysql/mysql-connector-python on GitHub
3. README