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

Backport of 97fa7fe961 from master

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:
 

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

docs/topics/security.txt

@@ -94,7 +94,8 @@ write :ref:`raw queries <executing-raw-queries>` or execute
 :ref:`custom sql <executing-custom-sql>`. These capabilities should be used
 sparingly and you should always be careful to properly escape any parameters
 that the user can control. In addition, you should exercise caution when using
-:meth:`extra() <django.db.models.query.QuerySet.extra>`.
+:meth:`~django.db.models.query.QuerySet.extra` and
+:class:`~django.db.models.expressions.RawSQL`.
 
 Clickjacking protection
 =======================