[1.8.x] Fixed #25212 -- Documented the RawSQL expression.

Backport of 97fa7fe961f961b6c93a11b50a7a1ed35c8bce8d from master

2 files changed, 34 insertions, 5 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index abc7828fd5..1b601234bf 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -558,11 +558,13 @@ query for ``WHERE mycolumn=0``, both rows will match. Similarly, ``WHERE mycolum
 will match the value ``'abc1'``. Therefore, string type fields included in Django
 will always cast the value to a string before using it in a query.
 
-If you implement custom model fields that inherit from :class:`~django.db.models.Field`
-directly, are overriding :meth:`~django.db.models.Field.get_prep_value`, or use
-:meth:`extra() <django.db.models.query.QuerySet.extra>` or
-:meth:`raw() <django.db.models.Manager.raw>`, you should ensure that you
-perform the appropriate typecasting.
+If you implement custom model fields that inherit from
+:class:`~django.db.models.Field` directly, are overriding
+:meth:`~django.db.models.Field.get_prep_value`, or use
+:class:`~django.db.models.expressions.RawSQL`,
+:meth:`~django.db.models.query.QuerySet.extra`, or
+:meth:`~django.db.models.Manager.raw`, you should ensure that you perform
+appropriate typecasting.
 
 .. _sqlite-notes:
 
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index f83523145e..2f780e4205 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -395,6 +395,33 @@ Conditional expressions allow you to use :keyword:`if` ... :keyword:`elif` ...
 :keyword:`else` logic in queries. Django natively supports SQL ``CASE``
 expressions. For more details see :doc:`conditional-expressions`.
 
+Raw SQL expressions
+-------------------
+
+.. versionadded:: 1.8
+
+.. currentmodule:: django.db.models.expressions
+
+.. class:: RawSQL(sql, params, output_field=None)
+
+Sometimes database expressions can't easily express a complex ``WHERE`` clause.
+In these edge cases, use the ``RawSQL`` expression. For example::
+
+    >>> from django.db.models.expressions import RawSQL
+    >>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))
+
+These extra lookups may not be portable to different database engines (because
+you're explicitly writing SQL code) and violate the DRY principle, so you
+should avoid them if possible.
+
+.. warning::
+
+    You should be very careful to escape any parameters that the user can
+    control by using ``params`` in order to protect against :ref:`SQL injection
+    attacks <sql-injection-protection>`.
+
+.. currentmodule:: django.db.models
+
 Technical Information
 =====================