Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.0.X] Fixed #9919 -- Added note on the need to mark transactions as…

… dirty when using raw SQL.

Merge of r11022 from trunk.


git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@11024 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 40bcd34fab32d112645fcdaecb1b92388094287b 1 parent e63e0bb
Russell Keith-Magee authored June 17, 2009
2  docs/ref/models/querysets.txt
@@ -566,6 +566,8 @@ call, since they are conflicting options.
566 566
 Both the ``depth`` argument and the ability to specify field names in the call
567 567
 to ``select_related()`` are new in Django version 1.0.
568 568
 
  569
+.. _extra:
  570
+
569 571
 ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
570 572
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
571 573
 
46  docs/topics/db/sql.txt
@@ -29,6 +29,45 @@ is required. For example::
29 29
 
30 30
         return row
31 31
 
  32
+.. _transactions-and-raw-sql:
  33
+
  34
+Transactions and raw SQL
  35
+------------------------
  36
+If you are using transaction decorators (such as ``commit_on_success``) to
  37
+wrap your views and provide transaction control, you don't have to make a
  38
+manual call to ``transaction.commit_unless_managed()`` -- you can manually
  39
+commit if you want to, but you aren't required to, since the decorator will
  40
+commit for you. However, if you don't manually commit your changes, you will
  41
+need to manually mark the transaction as dirty, using
  42
+``transaction.set_dirty()``::
  43
+
  44
+    @commit_on_success
  45
+    def my_custom_sql_view(request, value):
  46
+        from django.db import connection, transaction
  47
+        cursor = connection.cursor()
  48
+
  49
+        # Data modifying operation
  50
+        cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [value])
  51
+
  52
+        # Since we modified data, mark the transaction as dirty
  53
+        transaction.set_dirty()
  54
+
  55
+        # Data retrieval operation. This doesn't dirty the transaction,
  56
+        # so no call to set_dirty() is required.
  57
+        cursor.execute("SELECT foo FROM bar WHERE baz = %s", [value])
  58
+        row = cursor.fetchone()
  59
+
  60
+        return render_to_response('template.html', {'row': row})
  61
+
  62
+The call to ``set_dirty()`` is made automatically when you use the Django ORM
  63
+to make data modifying database calls. However, when you use raw SQL, Django
  64
+has no way of knowing if your SQL modifies data or not. The manual call to
  65
+``set_dirty()`` ensures that Django knows that there are modifications that
  66
+must be committed.
  67
+
  68
+Connections and cursors
  69
+-----------------------
  70
+
32 71
 ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
33 72
 (except when it comes to :ref:`transaction handling <topics-db-transactions>`).
34 73
 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
39 78
 ``"?"`` placeholder, which is used by the SQLite Python bindings. This is for
40 79
 the sake of consistency and sanity.)
41 80
 
  81
+An easier option?
  82
+-----------------
  83
+
42 84
 A final note: If all you want to do is a custom ``WHERE`` clause, you can just
43  
-use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
44  
-API.
  85
+use the ``where``, ``tables`` and ``params`` arguments to the
  86
+:ref:`extra clause <extra>` in the standard queryset API.
45 87
 
46 88
 .. _Python DB-API: http://www.python.org/peps/pep-0249.html
47 89
 

0 notes on commit 40bcd34

Please sign in to comment.
Something went wrong with that request. Please try again.