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.

Note

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.

Caution

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

driver

The possible options are:

MySQLdb

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.

PyMySQL

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.

Caution

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:

host

string, host to connect

user

string, user to connect as

passwd

string, password to use

db

string, database to use

port

integer, TCP/IP port to connect to

unix_socket

string, location of unix_socket (UNIX-ish only)

conv

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

connect_timeout

number of seconds to wait before the connection attempt fails.

compress

if set, gzip network compression is enabled

named_pipe

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

init_command

command which is run once the connection is created

read_default_file

see the MySQL documentation for mysql_options()

read_default_group

see the MySQL documentation for mysql_options()

client_flag

client flags from MySQLdb.constants.CLIENT

load_infile

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