Ticket #9919: raw-sql-docs-r9690.patch

docs/ref/models/querysets.txt

@@ -566 +566 @@
 Both the ``depth`` argument and the ability to specify field names in the call
 to ``select_related()`` are new in Django version 1.0.
 
+.. _querysets-extra-modifier:
+
 ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/topics/db/sql.txt

@@ -3 +3 @@
 Performing raw SQL queries
 ==========================
 
-Feel free to write custom SQL statements in custom model methods and
-module-level methods. The object ``django.db.connection`` represents the
-current database connection. To use it, call ``connection.cursor()`` to get a
-cursor object. Then, call ``cursor.execute(sql, [params])`` to execute the SQL
-and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting
-rows. Example::
+Django supports custom SQL statements in custom model methods and
+module-level methods.
 
+.. note::
+
+    If all you want to do is a custom ``WHERE`` clause, the Query API supports
+    the ``where``, ``tables`` and ``params`` arguments using the 
+    :ref:`extra modifier <querysets-extra-modifier>`.
+
+The object ``django.db.connection`` represents the current database
+connection. To use it, call ``connection.cursor()`` to get a cursor object.
+Then, call ``cursor.execute(sql, [params])`` to execute the SQL and
+``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting rows.
+The ``connection`` and ``cursor`` objects mostly implement the standard
+`Python DB-API`_. For example::
+
     def my_custom_sql(self):
         from django.db import connection
         cursor = connection.cursor()
@@ -17 +26 @@
         row = cursor.fetchone()
         return row
 
-``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
-(except when it comes to :ref:`transaction handling <topics-db-transactions>`).
-If you're not familiar with the Python DB-API, note that the SQL statement in
-``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
-directly within the SQL. If you use this technique, the underlying database
-library will automatically add quotes and escaping to your parameter(s) as
-necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the
-``"?"`` placeholder, which is used by the SQLite Python bindings. This is for
-the sake of consistency and sanity.)
+When using cursor ``cursor.execute()`` you should use placeholders rather
+than putting the parameters directly within the SQL. Doing this will let the
+underlying database library automatically add quotes and escape to your
+parameters as necessary. For the sake of consistency and sanity, Django
+expects the ``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is used
+by the SQLite Python bindings.
 
-A final note: If all you want to do is a custom ``WHERE`` clause, you can just
-use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
-API. 
+A major difference from the Python DB-API is the transaction handling.
+Automatic transaction management (which is enabled by default) will not work
+for raw SQL queries that modify the database since Django has no way of
+detecting the changes. You will need to commit the transaction yourself.
+A simple way to do this is to use Django's ``transaction.commit_manually``
+decorator::
 
-.. _Python DB-API: http://www.python.org/peps/pep-0249.html
+    @transaction.commit_manually
+    def my_custom_modifying_sql(self):
+        from django.db import connection
+        cursor = connection.cursor()
+        cursor.execute('UPDATE foo SET bar = bar + 1')
+        transaction.commit()
 
+For more details, see :ref:`transaction handling <topics-db-transactions>`.
+
+.. _Python DB-API: http://www.python.org/peps/pep-0249.html
+ No newline at end of file