From 8d33889422040351785cd511fe28105c6b5bec71 Mon Sep 17 00:00:00 2001
From: Ian Foote <ian@incuna.com>
Date: Fri, 5 Jun 2015 10:49:12 +0100
Subject: [PATCH] [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
---
 docs/ref/models/database-functions.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

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
 ------