Browse files

Fixed #9919 -- Added note on the need to mark transactions as dirty w…

…hen using raw SQL.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 1a7238c commit 992ded1ad1a46b5605769735d28aad22d4cb04d5 @freakboy3742 freakboy3742 committed Jun 17, 2009
Showing with 46 additions and 2 deletions.
  1. +2 −0 docs/ref/models/querysets.txt
  2. +44 −2 docs/topics/db/sql.txt
@@ -616,6 +616,8 @@ call, since they are conflicting options.
Both the ``depth`` argument and the ability to specify field names in the call
to ``select_related()`` are new in Django version 1.0.
+.. _extra:
``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
@@ -29,6 +29,45 @@ is required. For example::
return row
+.. _transactions-and-raw-sql:
+Transactions and raw SQL
+If you are using transaction decorators (such as ``commit_on_success``) to
+wrap your views and provide transaction control, you don't have to make a
+manual call to ``transaction.commit_unless_managed()`` -- you can manually
+commit if you want to, but you aren't required to, since the decorator will
+commit for you. However, if you don't manually commit your changes, you will
+need to manually mark the transaction as dirty, using
+ @commit_on_success
+ def my_custom_sql_view(request, value):
+ from django.db import connection, transaction
+ cursor = connection.cursor()
+ # Data modifying operation
+ cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [value])
+ # Since we modified data, mark the transaction as dirty
+ transaction.set_dirty()
+ # Data retrieval operation. This doesn't dirty the transaction,
+ # so no call to set_dirty() is required.
+ cursor.execute("SELECT foo FROM bar WHERE baz = %s", [value])
+ row = cursor.fetchone()
+ return render_to_response('template.html', {'row': row})
+The call to ``set_dirty()`` is made automatically when you use the Django ORM
+to make data modifying database calls. However, when you use raw SQL, Django
+has no way of knowing if your SQL modifies data or not. The manual call to
+``set_dirty()`` ensures that Django knows that there are modifications that
+must be committed.
+Connections and cursors
``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
@@ -39,9 +78,12 @@ 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.)
+An easier option?
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
+use the ``where``, ``tables`` and ``params`` arguments to the
+:ref:`extra clause <extra>` in the standard queryset API.
.. _Python DB-API:

0 comments on commit 992ded1

Please sign in to comment.