Fixed #23446 -- Officially recommended mysqlclient as MySQL driver

Thanks Corey Farwell for the report and Tim Graham for the review.
Thanks also to Inada Naoki for creating and maintaining mysqlclient.

1 files changed, 15 insertions, 9 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 689fedcffb..cbc75d6a9c 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -223,26 +223,30 @@ running ``migrate``::
 MySQL DB API Drivers
 --------------------
 
-The Python Database API is described in `PEP 249`_. MySQL has two prominent
+The Python Database API is described in `PEP 249`_. MySQL has three prominent
 drivers that implement this API:
 
 .. _PEP 249: http://www.python.org/dev/peps/pep-0249/
 
 - `MySQLdb`_ is a native driver that has been developed and supported for over
   a decade by Andy Dustman.
+- `mysqlclient` is a fork of ``MySQLdb`` which notably supports Python 3 and
+  can be used as a drop-in replacement for MySQLdb. At the time of this writing,
+  this is **the recommended choice** for using MySQL with Django.
 - `MySQL Connector/Python`_ is a pure Python driver from Oracle that does not
   require the MySQL client library or any Python modules outside the standard
   library.
 
 .. _MySQLdb: https://pypi.python.org/pypi/MySQL-python/1.2.4
+.. _mysqlclient: https://pypi.python.org/pypi/mysqlclient
 .. _MySQL Connector/Python: http://dev.mysql.com/downloads/connector/python
 
-Both drivers are thread-safe and both provide connection pooling. The major
-difference is that MySQL Connector/Python supports Python 3.
+All these drivers are thread-safe and provide connection pooling. ``MySQLdb``
+is the only one not supporting Python 3 currently.
 
 In addition to a DB API driver, Django needs an adapter to access the database
-drivers from its ORM. Django provides an adapter for MySQLdb while MySQL
-Connector/Python includes `its own`_.
+drivers from its ORM. Django provides an adapter for MySQLdb/mysqlclient while
+MySQL Connector/Python includes `its own`_.
 
 .. _its own: http://dev.mysql.com/doc/refman/5.6/en/connector-python-django-backend.html
 
@@ -270,12 +274,14 @@ Django requires MySQLdb version 1.2.1p2 or later.
 .. note::
     At the time of writing, the latest release of MySQLdb (1.2.4) doesn't
     support Python 3. In order to use MySQLdb under Python 3, you'll have to
-    install an unofficial fork, such as `MySQL-for-Python-3`_.
+    install ``mysqlclient``.
 
-    This port is still in alpha. In particular, it doesn't support binary
-    data, making it impossible to use :class:`django.db.models.BinaryField`.
+mysqlclient
+~~~~~~~~~~~
 
-.. _MySQL-for-Python-3: https://github.com/clelland/MySQL-for-Python-3
+Django requires mysqlclient 1.3.3 or later. Note that Python 3.2 is not
+supported. Except for the Python 3.3+ support, mysqlclient should mostly behave
+the same as MySQLDB.
 
 MySQL Connector/Python
 ~~~~~~~~~~~~~~~~~~~~~~