Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #1906 from DanSears/master

Added description of MySQL Connector/Python
  • Loading branch information...
commit 15592a04d769782e0bd98f07e96ed1c406f51c01 2 parents dbbd10e + a17fc36
@aaugustin aaugustin authored
Showing with 47 additions and 14 deletions.
  1. +47 −14 docs/ref/databases.txt
View
61 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
----------------------
Please sign in to comment.
Something went wrong with that request. Please try again.