[2.1.x] Fixed #29940 -- Recommended using the ORM rather than raw SQL.

Backport of 9886dffdf45873a5ce427eded9277f37d4a30ef1 from master.

1 files changed, 21 insertions, 5 deletions

diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt
index 39a54e4239..20b7f4ba90 100644
--- a/docs/topics/db/sql.txt
+++ b/docs/topics/db/sql.txt
@@ -4,15 +4,28 @@ Performing raw SQL queries
 
 .. currentmodule:: django.db.models
 
-When the :doc:`model query APIs </topics/db/queries>` don't go far enough, you
-can fall back to writing raw SQL. Django gives you two ways of performing raw
-SQL queries: you can use :meth:`Manager.raw()` to `perform raw queries and
-return model instances`__, or you can avoid the model layer entirely and
-`execute custom SQL directly`__.
+Django gives you two ways of performing raw SQL queries: you can use
+:meth:`Manager.raw()` to `perform raw queries and return model instances`__, or
+you can avoid the model layer entirely and `execute custom SQL directly`__.
 
 __ `performing raw queries`_
 __ `executing custom SQL directly`_
 
+.. admonition:: Explore the ORM before using raw SQL!
+
+    The Django ORM provides many tools to express queries without writing raw
+    SQL. For example:
+
+    * The :doc:`QuerySet API </ref/models/querysets>` is extensive.
+    * You can :meth:`annotate <.QuerySet.annotate>` and :doc:`aggregate
+      </topics/db/aggregation>` using many built-in :doc:`database functions
+      </ref/models/database-functions>`. Beyond those, you can create
+      :doc:`custom query expressions </ref/models/expressions/>`.
+
+    Before using raw SQL, explore :doc:`the ORM </topics/db/index>`. Ask on
+    |django-users| or the `#django IRC channel
+    <irc://irc.freenode.net/django>`_ to see if the ORM supports your use case.
+
 .. warning::
 
     You should be very careful whenever you write raw SQL. Every time you use
@@ -174,6 +187,9 @@ of people with their ages calculated by the database::
     Jane is 42.
     ...
 
+You can often avoid using raw SQL to compute annotations by instead using a
+:ref:`Func() expression <func-expressions>`.
+
 __ https://www.postgresql.org/docs/current/static/functions-datetime.html
 
 Passing parameters into ``raw()``