[1.8.x] Fixed #24925 -- Document using Coalesce on MySQL

Add warning for using Coalesce with python values on MySQL and document
workaround.

Backport of 14dead04acf4ac877d0f4025f142fe9e872ce8ac from master

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index cdd46ff1a2..717dc94cbf 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -55,6 +55,17 @@ Usage examples::
     >>> print(aggregated['combined_age_default'])
     None
 
+.. warning::
+
+    A python value passed to ``Coalesce`` on MySQL may be converted to an
+    incorrect type unless explicitly cast to the correct database type:
+
+    >>> from django.db.models.expressions import RawSQL
+    >>> from django.utils import timezone
+    >>> now = timezone.now()
+    >>> now_sql = RawSQL("cast(%s as datetime)", (now,))
+    >>> Coalesce('updated', now_sql)
+
 Concat
 ------