From 97fa7fe961f961b6c93a11b50a7a1ed35c8bce8d Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Mon, 3 Aug 2015 16:27:49 -0400
Subject: [PATCH] Fixed #25212 -- Documented the RawSQL expression.

---
 docs/ref/databases.txt          | 12 +++++++-----
 docs/ref/models/expressions.txt | 27 +++++++++++++++++++++++++++
 docs/topics/security.txt        |  3 ++-
 3 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 96829724b5..831d32170a 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -571,11 +571,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 29ee59a29d..e114fb56ed 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -391,6 +391,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
 =====================
 
diff --git a/docs/topics/security.txt b/docs/topics/security.txt
index 6eab39efed..3d535bb85e 100644
--- a/docs/topics/security.txt
+++ b/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
 =======================