Added documentation to explain the gains and losses when using utf8_bin

collation in MySQL. This should help people to make a reasonably informed
decision. Usually, leaving the MySQL collation alone will be the best solution,
but if you must change it, this gives a start to the information you need and
pointers to the appropriate place in the MySQL docs.

There's a small chance I also got all the necessary Sphinx markup correct, too
(it builds without errors, but I may have missed some chances for glory and
linkage).

Fixed #2335, #8506.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8568 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 22 insertions, 10 deletions

diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index f0638d1ea5..7faa07d4f7 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -340,6 +340,14 @@ The admin represents this as an ``<input type="text">`` (a single-line input).
     The maximum length (in characters) of the field. The max_length is enforced
     at the database level and in Django's validation.
 
+.. admonition:: MySQL users
+
+    If you are using this field with MySQLdb 1.2.2 and the ``utf8_bin``
+    collation (which is *not* the default), there are some issues to be aware
+    of. Refer to the :ref:`MySQL database notes <mysql-collation>` for
+    details.
+
+
 ``CommaSeparatedIntegerField``
 ------------------------------
 
@@ -689,6 +697,13 @@ Like an :class:`IntegerField`, but only allows values under a certain
 A large text field. The admin represents this as a ``<textarea>`` (a multi-line
 input).
 
+.. admonition:: MySQL users
+
+    If you are using this field with MySQLdb 1.2.1p2 and the ``utf8_bin``
+    collation (which is *not* the default), there are some issues to be aware
+    of. Refer to the :ref:`MySQL database notes <mysql-collation>` for
+    details.
+
 ``TimeField``
 -------------
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index b5de2e3aa2..62f255b43c 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -729,16 +729,13 @@ anything. It has now been changed to behave the same as ``id__isnull=True``.
 
 .. admonition:: MySQL comparisons
 
-    In MySQL, whether or not ``exact`` comparisons are case-sensitive depends
-    upon the collation setting of the table involved. The default is usually
-    ``latin1_swedish_ci`` or ``utf8_swedish_ci``, which results in
-    case-insensitive comparisons. Change the collation to
-    ``latin1_swedish_cs`` or ``utf8_bin`` for case sensitive comparisons.
-
-    For more details, refer to the MySQL manual section about `character sets
-    and collations`_.
-
-.. _character sets and collations: http://dev.mysql.com/doc/refman/5.0/en/charset.html
+    In MySQL, whether or not ``exact`` comparisons are case-insensitive by
+    default. This is controlled by the collation setting on the database
+    tables (this is a database setting, *not* a Django setting).  It is
+    possible to configured you MySQL tables to use case-sensitive comparisons,
+    however there are some trade-offs involved. For more information about
+    this, see the :ref:`collation section <mysql-collation>` in the
+    :ref:`databases <ref-databases>` documentation.
 
 iexact
 ~~~~~~