Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Proof-read and adjusted the transactions docs.

  • Loading branch information...
commit 5d8342f321c1e1017e63555270999c9378f10185 1 parent 93af822
Aymeric Augustin authored March 13, 2013
14  docs/internals/deprecation.txt
@@ -329,14 +329,19 @@ these changes.
329 329
 1.8
330 330
 ---
331 331
 
  332
+* ``django.contrib.comments`` will be removed.
  333
+
332 334
 * The following transaction management APIs will be removed:
333 335
 
334 336
   - ``TransactionMiddleware``,
335 337
   - the decorators and context managers ``autocommit``, ``commit_on_success``,
336  
-    and ``commit_manually``,
  338
+    and ``commit_manually``, defined in ``django.db.transaction``,
  339
+  - the functions ``commit_unless_managed`` and ``rollback_unless_managed``,
  340
+    also defined in ``django.db.transaction``,
337 341
   - the ``TRANSACTIONS_MANAGED`` setting.
338 342
 
339  
-  Upgrade paths are described in :ref:`transactions-upgrading-from-1.5`.
  343
+  Upgrade paths are described in the :ref:`transaction management docs
  344
+  <transactions-upgrading-from-1.5>`.
340 345
 
341 346
 * The :ttag:`cycle` and :ttag:`firstof` template tags will auto-escape their
342 347
   arguments. In 1.6 and 1.7, this behavior is provided by the version of these
@@ -358,14 +363,11 @@ these changes.
358 363
   ``ChangeList.root_query_set`` and ``ChangeList.query_set``.
359 364
 
360 365
 * The following private APIs will be removed:
  366
+
361 367
   - ``django.db.close_connection()``
362 368
   - ``django.db.backends.creation.BaseDatabaseCreation.set_autocommit()``
363 369
   - ``django.db.transaction.is_managed()``
364 370
   - ``django.db.transaction.managed()``
365  
-  - ``django.db.transaction.commit_unless_managed()``
366  
-  - ``django.db.transaction.rollback_unless_managed()``
367  
-
368  
-* ``django.contrib.comments`` will be removed.
369 371
 
370 372
 2.0
371 373
 ---
3  docs/releases/1.6.txt
@@ -36,7 +36,8 @@ Improved transaction management
36 36
 Django's transaction management was overhauled. Database-level autocommit is
37 37
 now turned on by default. This makes transaction handling more explicit and
38 38
 should improve performance. The existing APIs were deprecated, and new APIs
39  
-were introduced, as described in :doc:`/topics/db/transactions`.
  39
+were introduced, as described in the :doc:`transaction management docs
  40
+</topics/db/transactions>`.
40 41
 
41 42
 Please review carefully the list of :ref:`known backwards-incompatibilities
42 43
 <transactions-upgrading-from-1.5>` to determine if you need to make changes in
70  docs/topics/db/transactions.txt
@@ -35,10 +35,10 @@ transaction. Set :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` to
35 35
 ``True`` in the configuration of each database for which you want to enable
36 36
 this behavior.
37 37
 
38  
-It works like this. When a request starts, Django starts a transaction. If the
39  
-response is produced without problems, Django commits the transaction. If the
40  
-view function produces an exception, Django rolls back the transaction.
41  
-Middleware always runs outside of this transaction.
  38
+It works like this. Before calling a view function, Django starts a
  39
+transaction. If the response is produced without problems, Django commits the
  40
+transaction. If the view produces an exception, Django rolls back the
  41
+transaction.
42 42
 
43 43
 You may perfom partial commits and rollbacks in your view code, typically with
44 44
 the :func:`atomic` context manager. However, at the end of the view, either
@@ -207,13 +207,6 @@ To avoid this, you can :ref:`deactivate the transaction management
207 207
     Before Django 1.6, autocommit was turned off, and it was emulated by
208 208
     forcing a commit after write operations in the ORM.
209 209
 
210  
-.. warning::
211  
-
212  
-    If you're using the database API directly — for instance, you're running
213  
-    SQL queries with ``cursor.execute()`` — be aware that autocommit is on,
214  
-    and consider wrapping your operations in a transaction, with
215  
-    :func:`atomic`, to ensure consistency.
216  
-
217 210
 .. _deactivate-transaction-management:
218 211
 
219 212
 Deactivating transaction management
@@ -251,8 +244,8 @@ Autocommit
251 244
 
252 245
 .. versionadded:: 1.6
253 246
 
254  
-Django provides a straightforward API to manage the autocommit state of each
255  
-database connection, if you need to.
  247
+Django provides a straightforward API in the :mod:`django.db.transaction`
  248
+module to manage the autocommit state of each database connection.
256 249
 
257 250
 .. function:: get_autocommit(using=None)
258 251
 
@@ -287,7 +280,7 @@ start a transaction is to disable autocommit with :func:`set_autocommit`.
287 280
 
288 281
 Once you're in a transaction, you can choose either to apply the changes
289 282
 you've performed until this point with :func:`commit`, or to cancel them with
290  
-:func:`rollback`.
  283
+:func:`rollback`. These functions are defined in :mod:`django.db.transaction`.
291 284
 
292 285
 .. function:: commit(using=None)
293 286
 
@@ -332,10 +325,8 @@ Savepoints are controlled by three functions in :mod:`django.db.transaction`:
332 325
 
333 326
 .. function:: savepoint(using=None)
334 327
 
335  
-    Creates a new savepoint. This marks a point in the transaction that
336  
-    is known to be in a "good" state.
337  
-
338  
-    Returns the savepoint ID (``sid``).
  328
+    Creates a new savepoint. This marks a point in the transaction that is
  329
+    known to be in a "good" state. Returns the savepoint ID (``sid``).
339 330
 
340 331
 .. function:: savepoint_commit(sid, using=None)
341 332
 
@@ -388,11 +379,9 @@ While SQLite ≥ 3.6.8 supports savepoints, a flaw in the design of the
388 379
 :mod:`sqlite3` makes them hardly usable.
389 380
 
390 381
 When autocommit is enabled, savepoints don't make sense. When it's disabled,
391  
-:mod:`sqlite3` commits implicitly before savepoint-related statement. (It
  382
+:mod:`sqlite3` commits implicitly before savepoint statements. (In fact, it
392 383
 commits before any statement other than ``SELECT``, ``INSERT``, ``UPDATE``,
393  
-``DELETE`` and ``REPLACE``.)
394  
-
395  
-This has two consequences:
  384
+``DELETE`` and ``REPLACE``.) This bug has two consequences:
396 385
 
397 386
 - The low level APIs for savepoints are only usable inside a transaction ie.
398 387
   inside an :func:`atomic` block.
@@ -407,22 +396,27 @@ depends on your MySQL version and the table types you're using. (By
407 396
 peculiarities are outside the scope of this article, but the MySQL site has
408 397
 `information on MySQL transactions`_.
409 398
 
410  
-If your MySQL setup does *not* support transactions, then Django will function
411  
-in autocommit mode: Statements will be executed and committed as soon as
412  
-they're called. If your MySQL setup *does* support transactions, Django will
413  
-handle transactions as explained in this document.
  399
+If your MySQL setup does *not* support transactions, then Django will always
  400
+function in autocommit mode: statements will be executed and committed as soon
  401
+as they're called. If your MySQL setup *does* support transactions, Django
  402
+will handle transactions as explained in this document.
414 403
 
415 404
 .. _information on MySQL transactions: http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html
416 405
 
417 406
 Handling exceptions within PostgreSQL transactions
418 407
 --------------------------------------------------
419 408
 
420  
-When a call to a PostgreSQL cursor raises an exception (typically
421  
-``IntegrityError``), all subsequent SQL in the same transaction will fail with
422  
-the error "current transaction is aborted, queries ignored until end of
423  
-transaction block". Whilst simple use of ``save()`` is unlikely to raise an
424  
-exception in PostgreSQL, there are more advanced usage patterns which
425  
-might, such as saving objects with unique fields, saving using the
  409
+.. note::
  410
+    This section is relevant only if you're implementing your own transaction
  411
+    management. This problem cannot occur in Django's default mode and
  412
+    :func:`atomic` handles it automatically.
  413
+
  414
+Inside a transaction, when a call to a PostgreSQL cursor raises an exception
  415
+(typically ``IntegrityError``), all subsequent SQL in the same transaction
  416
+will fail with the error "current transaction is aborted, queries ignored
  417
+until end of transaction block". Whilst simple use of ``save()`` is unlikely
  418
+to raise an exception in PostgreSQL, there are more advanced usage patterns
  419
+which might, such as saving objects with unique fields, saving using the
426 420
 force_insert/force_update flag, or invoking custom SQL.
427 421
 
428 422
 There are several ways to recover from this sort of error.
@@ -529,9 +523,9 @@ Django starts in auto mode. ``TransactionMiddleware``,
529 523
 Internally, Django keeps a stack of states. Activations and deactivations must
530 524
 be balanced.
531 525
 
532  
-For example, ``commit_on_success`` switches to managed mode when entering the
533  
-block of code it controls; when exiting the block, it commits or rollbacks,
534  
-and switches back to auto mode.
  526
+For example, :func:`commit_on_success` switches to managed mode when entering
  527
+the block of code it controls; when exiting the block, it commits or
  528
+rollbacks, and switches back to auto mode.
535 529
 
536 530
 So :func:`commit_on_success` really has two effects: it changes the
537 531
 transaction state and it defines an transaction block. Nesting will give the
@@ -568,7 +562,7 @@ you must now use this pattern::
568 562
     my_view.transactions_per_request = False
569 563
 
570 564
 The transaction middleware applied not only to view functions, but also to
571  
-middleware modules that come after it. For instance, if you used the session
  565
+middleware modules that came after it. For instance, if you used the session
572 566
 middleware after the transaction middleware, session creation was part of the
573 567
 transaction. :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` only
574 568
 applies to the view itself.
@@ -651,8 +645,8 @@ same "automatic transaction". If you need to enforce atomicity, you must wrap
651 645
 the sequence of queries in :func:`commit_on_success`.
652 646
 
653 647
 To check for this problem, look for calls to ``cursor.execute()``. They're
654  
-usually followed by a call to ``transaction.commit_unless_managed``, which
655  
-isn't necessary any more and should be removed.
  648
+usually followed by a call to ``transaction.commit_unless_managed()``, which
  649
+isn't useful any more and should be removed.
656 650
 
657 651
 Select for update
658 652
 ~~~~~~~~~~~~~~~~~

0 notes on commit 5d8342f

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