diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index 7f01c32c74..7fdcfae149 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 ` 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 ` is extensive. + * You can :meth:`annotate <.QuerySet.annotate>` and :doc:`aggregate + ` using many built-in :doc:`database functions + `. Beyond those, you can create + :doc:`custom query expressions `. + + Before using raw SQL, explore :doc:`the ORM `. Ask on + |django-users| or the `#django IRC channel + `_ 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 `. + __ https://www.postgresql.org/docs/current/static/functions-datetime.html Passing parameters into ``raw()``