added description of MySQL Connector/Python

Reorganized the MySQLdb section into a "MySQL DB API Drivers" section that describes both MySQLdb and MySQL Connector/Python. Included description of the Django adaptors for these DB API drivers.

1 files changed, 47 insertions, 14 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index d411553fbe..76af24edf2 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -237,11 +237,38 @@ running ``migrate``::
    had reports that the Windows Community Server installer sets up InnoDB as
    the default storage engine, for example.
 
+.. _mysql-db-api-drivers:
+
+MySQL DB API Drivers
+--------------------
+
+The Python Database API is described in `PEP 249`_. MySQL has two 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.
+- `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
+.. _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.
+
+In addition to a DB API driver, Django needs an adaptor to access the database
+drivers from its ORM. Django provides an adaptor for MySQLdb while MySQL
+Connector/Python includes `its own`_.
+
+.. _its own: http://dev.mysql.com/doc/refman/5.6/en/connector-python-django-backend.html
+
 MySQLdb
--------
+~~~~~~~
 
-`MySQLdb`_ is the Python interface to MySQL. Version 1.2.1p2 or later is
-required for full MySQL support in Django.
+Django requires MySQLdb version 1.2.1p2 or later.
 
 .. note::
     If you see ``ImportError: cannot import name ImmutableSet`` when trying to
@@ -253,25 +280,31 @@ required for full MySQL support in Django.
 
 .. note::
     There are known issues with the way MySQLdb converts date strings into
-    datetime objects. Specifically, date strings with value 0000-00-00 are valid for
-    MySQL but will be converted into None by MySQLdb.
+    datetime objects. Specifically, date strings with value 0000-00-00 are
+    valid for MySQL but will be converted into None by MySQLdb.
 
     This means you should be careful while using loaddata/dumpdata with rows
     that may have 0000-00-00 values, as they will be converted to None.
 
-.. _MySQLdb: http://sourceforge.net/projects/mysql-python
+.. 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`_.
 
-Python 3
---------
+    This port is still in alpha. In particular, it doesn't support binary
+    data, making it impossible to use :class:`django.db.models.BinaryField`.
 
-At the time of writing, the latest release of MySQLdb (1.2.4) doesn't support
-Python 3. In order to use MySQL under Python 3, you'll have to install an
-unofficial fork, such as `MySQL-for-Python-3`_.
+.. _MySQL-for-Python-3: https://github.com/clelland/MySQL-for-Python-3
 
-This port is still in alpha. In particular, it doesn't support binary data,
-making it impossible to use :class:`django.db.models.BinaryField`.
+MySQL Connector/Python
+~~~~~~~~~~~~~~~~~~~~~~
 
-.. _MySQL-for-Python-3: https://github.com/clelland/MySQL-for-Python-3
+MySQL Connector/Python is available through two `release branches`_: Generally
+Available (GA, currently 1.0.x) and Development (Dev, currently 1.1.x).
+The Django adapter is currently available in the Dev branch and is described
+as Alpha.
+
+.. _release branches: http://dev.mysql.com/downloads/connector/python/
 
 Creating your database
 ----------------------