MySQL Adapter Options#

The ZConfig section name is <mysql>.

RelStorage 3.0 requires MySQL 5.7.19 or above. MySQL 5.7.21 or higher, or MySQL 8.0.16 or higher, is strongly recommended.


MySQL versions earlier than 8.0.16 do not support or preserve table CHECK constraints. Upgrading a RelStorage schema from MySQL 5.7.x to 8.0.x will thus not have any defined or enforced table CHECK constraints, but creating a new RelStorage schema under MySQL 8.0 will include enforced CHECK constraints.


MySQL 5.0.18 and earlier contain crashing bugs. See pull request #287 for details.


The possible options are:


A C-based driver that requires the MySQL client libraries.. This is best provided by the PyPI distribution mysqlclient. This driver is not compatible with gevent, though alternate distributions exist and were used in the past.

This is the default and preferred driver on CPython on all platforms except Windows.

gevent MySQLdb

Like MySQLdb, but explicitly uses’s gevent’s event loop to avoid blocking on the socket as much as possible when communicating with MySQL.

Note that this is fairly coarse-grained: When sending a query, we can only yield until the socket is ready to write, and then we must write the entire query (because that portion is implemented in C). Likewise, we can only yield until results are ready to be read, and then we must read the entire results, unless a server-side cursor is used.

Supports RelStorage’s critical commit section. Supports server-side cursors for large result sets, and if they are large, will periodically yield to gevent while iterating them.


A pure-Python driver provided by the distribution of the same name. It works with CPython 2 and 3 and PyPy (where it is preferred). It is compatible with gevent if gevent’s monkey-patching is used.

This is the default and preferred driver on Windows and on PyPy.

Py MySQL Connector/Python

This is the official client built by Oracle and distributed as mysql-connector-python on PyPI.

It has an optional C extension. The C extension (which uses the MySQL client libraries) performs about as well as mysqlclient, but the pure-python version is somewhat slower than PyMySQL. However, it supports more advanced options for failover and high availability.

RelStorage will only use the pure-Python implementation when using this name; this is compatible with gevent monkey-patching.

Binary packages are distributed by Oracle for many platforms and include the necessary native libraries and C extension. These can be installed from PyPI or downloaded from Oracle.

New in version 2.1a1.

C MySQL Connector/Python

The same as above, but RelStorage will only use the C extension. This is not compatible with gevent.


At least through version 8.0.16, this driver is not recommended.

It fails the checks established by CPython 3.7’s development mode; trying to use it with development mode enabled will crash the interpreter with “Fatal Python error: Python memory allocator called without holding the GIL.” This signals potentially serious internal problems.

The MySQL adapter accepts most parameters supported by the mysqlclient library (the maintained version of MySQL-python). If a particular driver doesn’t support a parameter, it will be ignored. The parameters include:


string, host to connect


string, user to connect as


string, password to use


string, database to use


integer, TCP/IP port to connect to


string, location of unix_socket (UNIX-ish only)


mapping, maps MySQL FIELD_TYPE.* to Python functions which convert a string to the appropriate Python type


number of seconds to wait before the connection attempt fails.


if set, gzip network compression is enabled


if set, connect to server via named pipe (Windows only)


command which is run once the connection is created


see the MySQL documentation for mysql_options()


see the MySQL documentation for mysql_options()


client flags from MySQLdb.constants.CLIENT


int, non-zero enables LOAD LOCAL INFILE, zero disables