Fixed #31777 -- Added support for database collations to Char/TextFields.

Thanks Simon Charette and Mariusz Felisiak for reviews.

3 files changed, 53 insertions, 8 deletions

diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index 0e1ee50b46..ffb629f96c 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -196,6 +196,8 @@ Model fields
 * **fields.E170**: ``BinaryField``’s ``default`` cannot be a string. Use bytes
   content instead.
 * **fields.E180**: ``<database>`` does not support ``JSONField``\s.
+* **fields.E190**: ``<database>`` does not support a database collation on
+  ``<field_type>``\s.
 * **fields.E900**: ``IPAddressField`` has been removed except for support in
   historical migrations.
 * **fields.W900**: ``IPAddressField`` has been deprecated. Support for it
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index fd7e88d168..93c011fe2c 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -593,20 +593,36 @@ For large amounts of text, use :class:`~django.db.models.TextField`.
 
 The default form widget for this field is a :class:`~django.forms.TextInput`.
 
-:class:`CharField` has one extra required argument:
+:class:`CharField` has two extra arguments:
 
 .. attribute:: CharField.max_length
 
-    The maximum length (in characters) of the field. The max_length is enforced
-    at the database level and in Django's validation using
+    Required. The maximum length (in characters) of the field. The max_length
+    is enforced at the database level and in Django's validation using
     :class:`~django.core.validators.MaxLengthValidator`.
 
-.. note::
+    .. note::
+
+        If you are writing an application that must be portable to multiple
+        database backends, you should be aware that there are restrictions on
+        ``max_length`` for some backends. Refer to the :doc:`database backend
+        notes </ref/databases>` for details.
+
+.. attribute:: CharField.db_collation
+
+    .. versionadded:: 3.2
+
+    Optional. The database collation name of the field.
+
+    .. note::
+
+        Collation names are not standardized. As such, this will not be
+        portable across multiple database backends.
 
-    If you are writing an application that must be portable to multiple
-    database backends, you should be aware that there are restrictions on
-    ``max_length`` for some backends. Refer to the :doc:`database backend
-    notes </ref/databases>` for details.
+    .. admonition:: Oracle
+
+        Oracle supports collations only when the ``MAX_STRING_SIZE`` database
+        initialization parameter is set to ``EXTENDED``.
 
 ``DateField``
 -------------
@@ -1329,6 +1345,21 @@ If you specify a ``max_length`` attribute, it will be reflected in the
 However it is not enforced at the model or database level. Use a
 :class:`CharField` for that.
 
+.. attribute:: TextField.db_collation
+
+    .. versionadded:: 3.2
+
+    The database collation name of the field.
+
+    .. note::
+
+        Collation names are not standardized. As such, this will not be
+        portable across multiple database backends.
+
+    .. admonition:: Oracle
+
+        Oracle does not support collations for a ``TextField``.
+
 ``TimeField``
 -------------
 
diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index e66e5777d5..2c59c488c0 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -308,6 +308,11 @@ Models
   :class:`~django.db.models.functions.TruncTime` database functions allows
   truncating datetimes in a specific timezone.
 
+* The new ``db_collation`` argument for
+  :attr:`CharField <django.db.models.CharField.db_collation>` and
+  :attr:`TextField <django.db.models.TextField.db_collation>` allows setting a
+  database collation for the field.
+
 Pagination
 ~~~~~~~~~~
 
@@ -431,6 +436,13 @@ backends.
   unique constraints (:attr:`.UniqueConstraint.include`), set
   ``DatabaseFeatures.supports_covering_indexes`` to ``True``.
 
+* Third-party database backends must implement support for column database
+  collations on ``CharField``\s and ``TextField``\s or set
+  ``DatabaseFeatures.supports_collation_on_charfield`` and
+  ``DatabaseFeatures.supports_collation_on_textfield`` to ``False``. If
+  non-deterministic collations are not supported, set
+  ``supports_non_deterministic_collations`` to ``False``.
+
 :mod:`django.contrib.admin`
 ---------------------------