dave
/
relstorage
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clean up mysqlconnector driver name. Clean up installation docs and driver statement docs.

This commit is contained in:
Jason Madden 2017-01-26 11:58:05 -06:00
parent 41b9670498
commit 8e7b49d2a6
No known key found for this signature in database
GPG Key ID: 349F84431A08B99E
8 changed files with 115 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -19,7 +19,7 @@ matrix:
- python: 2.7
env:
- ENV=cmysqlconnector
- RS_MY_DRIVER=cmysqlconnector
- RS_MY_DRIVER="C MySQL Connector/Python"
- python: 3.6
env: ENV=mysqlconnector
- python: pypy-5.4.1

1
.travis/setup-cmysqlconnector.sh
View File

@ -3,4 +3,5 @@ tar -xf mysql-connector-python-2.1.5.tar.gz
cd ./mysql-connector-python-2.1.5
python ./setup.py install --with-mysql-capi=/usr
cd ..
python -c 'import relstorage.adapters.mysql.drivers as D; print(D.preferred_driver_name,D.driver_map)'
`dirname $0`/mysql.sh

1
.travis/setup-mysqlconnector.sh
View File

@ -1,2 +1,3 @@
pip install https://dev.mysql.com/get/Downloads/Connector-Python/mysql-connector-python-2.1.5.tar.gz
python -c 'import relstorage.adapters.mysql.drivers as D; print(D.preferred_driver_name,D.driver_map)'
`dirname $0`/mysql.sh

2
.travis/setup-pymysqlconnector.sh
View File

@ -1,2 +0,0 @@
pip install https://dev.mysql.com/get/Downloads/Connector-Python/mysql-connector-python-2.1.5.tar.gz
`dirname $0`/mysql.sh

2
.travis/setup-umysqldb.sh
View File

@ -1,5 +1,5 @@
pip install -U pymysql
pip install git+https://github.com/NextThought/umysqldb.git#egg=umysqldb
export RS_MY_DRIVER=umysqldb
python -c 'import relstorage.adapters._mysql_drivers as D; print(D.preferred_driver_name,D.driver_map)'
python -c 'import relstorage.adapters.mysql.drivers as D; print(D.preferred_driver_name,D.driver_map)'
`dirname $0`/mysql.sh

84
doc/db-specific-options.rst
View File

@ -30,11 +30,22 @@ PostgreSQL Adapter Options
The PostgreSQL adapter accepts:
driver
Either "psycopg2" or "psycopg2cffi" for the native libpg based
drivers. "pg8000" is a pure-python driver suitable for use with
gevent.
The possible options are:
.. note:: pg8000 requires PostgreSQL 9.4 or above for BLOB support.
psycopg2
A C-based driver that requires the PostgreSQL development
libraries. Optimal on CPython, but not compatible with gevent.
psycopg2cffi
A C-based driver that requires the PostgreSQL development
libraries. Optimal on PyPy and almost indistinguishable from
psycopg2 on CPython. Not compatible with gevent.
pg8000
A pure-Python driver suitable for use with gevent. Works on all
supported platforms.
.. note:: pg8000 requires PostgreSQL 9.4 or above for BLOB support.
dsn
Specifies the data source name for connecting to PostgreSQL.
@ -54,11 +65,66 @@ The MySQL adapter accepts most parameters supported by the mysqlclient
library (the maintained version of MySQL-python), including:
driver
Either "MySQLdb" (which can be provided by the either of the
PyPI distributions `mysqlclient
<https://pypi.python.org/pypi/mysqlclient>`_ or `MySQL-python
<https://pypi.python.org/pypi/MySQL-python/>`_), or "PyMySQL", or
"umysqldb" or "mysqlconnector" for the `official client <https://dev.mysql.com/doc/connector-python/en/>`_.
The possible options are:
MySQLdb
A C-based driver that requires the MySQL client development
libraries.. This is best provided by the PyPI distribution
`mysqlclient <https://pypi.python.org/pypi/mysqlclient>`_. (It
can also be provided by the legacy `MySQL-python
<https://pypi.python.org/pypi/MySQL-python/>`_ distribution,
but only on CPython 2; this distribution is no longer tested.)
These drivers are *not* compatible with gevent.
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.
umysqldb
A C-based driver that builds on PyMySQL. It is compatible with
gevent, but only works on CPython 2. It does not require the
MySQL client development libraries but uses a project called
``umysql`` to communicate with the server using only sockets.
.. note:: Make sure the server has a
``max_allowed_packet`` setting no larger than 16MB. Also
make sure that RelStorage's ``blob-chunk-size`` is less than
16MB as well.
.. note:: `This fork of umysqldb
<https://github.com/NextThought/umysqldb.git>`_ is
recommended. The ``full-buffer`` branch of `this ultramysql
fork
<https://github.com/NextThought/ultramysql/tree/full-buffer>`_
is also recommended if you encounter strange MySQL packet
errors.
MySQL Connector/Python
This is the `official client
<https://dev.mysql.com/doc/connector-python/en/>`_ provided by
Oracle. It generally cannot be installed from PyPI or by pip if
you want the optional C extension. It has an optional C
extension that must be built manually. The C extension (which
requires the MySQL client development libraries) performs
about as well as mysqlclient, but the pure-python version
somewhat slower than PyMySQL. However, it supports more advanced
options for failover and high availability.
When using this name, RelStorage will use the C extension if
available, otherwise it will use the Python version.
Binary packages are distributed by Oracle for many platforms
and include the necessary native libraries and C extension.
C MySQL Connector/Python
The same as above, but RelStorage will only use the C extension.
This is not compatible with gevent.
Py MySQL Connector/Python
Like the above, but RelStorage will use the pure-Python version
only. This is compatible with gevent.
host
string, host to connect

67
doc/install.rst
View File

@ -38,46 +38,43 @@ database.
On CPython2, install psycopg2 2.6.1+, mysqlclient 1.3.7+, or cx_Oracle
5.2+; PyMySQL 0.7 and umysql are also known to work as is pg8000. For
CPython3, install psycopg2, mysqlclient 1.3.7+ or cx_Oracle; PyMySQL
and pg8000 are also known to work. On PyPy, install psycopg2cffi
2.7.4+ or PyMySQL 0.6.6+ (PyPy will generally work with psycopg2 and
mysqlclient, but it will be *much* slower; in contrast, pg8000
performs nearly as well. cx_Oracle is untested on PyPy).
5.2+; PyMySQL 0.7, MySQL Connector/Python 2.1.5 and umysql are also
known to work as is pg8000.
Here's a table of known working adapters; adapters **in bold** are the recommended
adapter; adapters in *italic* are also tested:
For CPython3, install psycopg2, mysqlclient or cx_Oracle;
PyMySQL, MySQL Connector/Python and pg8000 are also known to work.
======== ================= ================= ======
Platform MySQL PostgreSQL Oracle
======== ================= ================= ======
CPython2 MySQL-python; **psycopg2**; **cx_Oracle**
**mysqlclient**; psycopg2cffi;
*PyMySQL*; *pg8000*
*umysqldb*;
*MySQL Connector*
CPython3 **mysqlclient**; **psycopg2**; **cx_Oracle**
*PyMySQL* *pg8000*
*MySQL Connector*
PyPy **PyMySQL**; **psycopg2cffi**;
*pg8000*
*MySQL Connector*
======== ================= ================= ======
On PyPy, install psycopg2cffi 2.7.4+ or PyMySQL 0.6.6+ (PyPy will
generally work with psycopg2 and mysqlclient, but it will be *much*
slower; in contrast, pg8000 performs nearly as well. cx_Oracle is
untested on PyPy).
.. note:: If you use umysql, make sure the server has a
``max_allowed_packet`` setting no larger than 16MB. Also
make sure that RelStorage's ``blob-chunk-size`` is less than
16MB as well.
Here's a table of known (tested) working adapters; adapters **in
bold** are the recommended adapter.
.. note:: `This fork of umysqldb
<https://github.com/NextThought/umysqldb.git>`_ is
recommended. The ``full-buffer`` branch of `this ultramysql
fork
<https://github.com/NextThought/ultramysql/tree/full-buffer>`_
is also recommended if you encounter strange MySQL packet
errors.
+----------+---------------------+---------------------+--------------+
| Platform | MySQL | PostgreSQL | Oracle |
+==========+=====================+=====================+==============+
| CPython2 | | 1. **psycopg2** | **cx_Oracle**|
| | 1. **mysqlclient** | 2. pg8000 | |
| | 2. PyMySQL | | |
| | 3. umysqldb | | |
| | 4. MySQL Connector | | |
+----------+---------------------+---------------------+--------------+
| CPython3 | 1. **mysqlclient** | 1. **psycopg2** | **cx_Oracle**|
| | 2. PyMySQL | 2. pg8000 | |
| | 3. MySQL Connector | | |
+----------+---------------------+---------------------+--------------+
| PyPy | 1. **PyMySQL** | 1. **psycopg2cffi** | |
| | 2. MySQL Connector | 2. pg8000 | |
+----------+---------------------+---------------------+--------------+
mysqlclient, pg8000 and umysql are compatible (cooperative) with gevent.
mysqlclient, MySQL Connector/Python (without its C extension), pg8000
and umysql are compatible (cooperative) with gevent.
For additional details, see the "driver" section for each database in
:doc:`db-specific-options`.
Memcache Integration
====================

8
relstorage/adapters/mysql/drivers.py
View File

@ -146,7 +146,7 @@ else:
@implementer(IDBDriver)
class MySQLConnectorDriver(AbstractDriver):
# See https://github.com/zodb/relstorage/issues/155
__name__ = "mysqlconnector"
__name__ = "MySQL Connector/Python"
disconnected_exceptions, close_exceptions, lock_exceptions = _standard_exceptions(mysql.connector)
use_replica_exceptions = (mysql.connector.OperationalError,)
@ -197,17 +197,17 @@ else:
preferred_driver_name = driver.__name__
if driver.have_cext:
driver_map['c' + driver.__name__] = driver
driver_map['C ' + driver.__name__] = driver
class PyMySQLConnectorDriver(MySQLConnectorDriver):
__name__ = 'py' + driver.__name__
__name__ = 'Py ' + driver.__name__
have_cext = False
driver = PyMySQLConnectorDriver()
driver_map[driver.__name__] = driver
else:
driver_map['py' + driver.__name__] = driver
driver_map['Py ' + driver.__name__] = driver
del driver