From b42930e4b7f344256cf5625d8b26c7626a354244 Mon Sep 17 00:00:00 2001
From: Claude Paroz <claude@2xlibre.net>
Date: Sat, 25 Oct 2014 11:05:38 +0200
Subject: [PATCH] [1.7.x] 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.
Backport of 7f089ac2e3 from master.
---
 django/db/backends/mysql/base.py |  3 ++-
 docs/ref/databases.txt           | 24 +++++++++++++++---------
 tests/requirements/mysql.txt     |  2 +-
 3 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/django/db/backends/mysql/base.py b/django/db/backends/mysql/base.py
index 697a35a1ddb..6f389dbdd6a 100644
--- a/django/db/backends/mysql/base.py
+++ b/django/db/backends/mysql/base.py
@@ -1,7 +1,8 @@
 """
 MySQL database backend for Django.
 
-Requires MySQLdb: http://sourceforge.net/projects/mysql-python
+Requires mysqclient: https://pypi.python.org/pypi/mysqlclient/
+MySQLdb is supported for Python 2 only: http://sourceforge.net/projects/mysql-python
 """
 from __future__ import unicode_literals
 
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 7822b615f46..dc29dce784b 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -247,26 +247,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
 
@@ -294,12 +298,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
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/tests/requirements/mysql.txt b/tests/requirements/mysql.txt
index c7a23474071..18c098ae967 100644
--- a/tests/requirements/mysql.txt
+++ b/tests/requirements/mysql.txt
@@ -1 +1 @@
-MySQL-python
+mysqlclient