From 110e4f68ef3b1d1e696d185dac5a5ad09658dcb2 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 7 Jun 2009 03:26:12 +0000 Subject: [PATCH] [soc2009/multidb] Updated the transactions documentation for parts of the API that were extended to support multiple databases. git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/multidb@10937 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/topics/db/transactions.txt | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index b374609ab9..8902f6506c 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -56,7 +56,10 @@ Controlling transaction management in views For most people, implicit request-based transactions work wonderfully. However, if you need more fine-grained control over how transactions are managed, you can use Python decorators to change the way transactions are handled by a -particular view function. +particular view function. All of the decorators take an option ``using`` +parameter which should be the alias for a database connection for which the +behavior applies to. If no alias is specified then the ``"default"`` database +is used. .. note:: @@ -79,9 +82,14 @@ Example:: def viewfunc(request): .... + @transaction.autocommit(using="my_other_database") + def viewfunc2(request): + .... + Within ``viewfunc()``, transactions will be committed as soon as you call ``model.save()``, ``model.delete()``, or any other function that writes to the -database. +database. ``viewfunc2()`` will have this same behavior, but for the +``"my_other_database"`` connection. ``django.db.transaction.commit_on_success`` ------------------------------------------- @@ -95,6 +103,10 @@ all the work done in a function:: def viewfunc(request): .... + @transaction.commit_on_success(using="my_other_database") + def viewfunc2(request): + .... + If the function returns successfully, then Django will commit all work done within the function at that point. If the function raises an exception, though, Django will roll back the transaction. @@ -127,6 +139,10 @@ Manual transaction management looks like this:: else: transaction.commit() + @transaction.commit_manually(using="my_other_database") + def viewfunc2(request): + .... + .. admonition:: An important note to users of earlier Django releases: The database ``connection.commit()`` and ``connection.rollback()`` methods @@ -169,21 +185,25 @@ issue a rollback, the entire transaction is rolled back. Savepoints provide the ability to perform a fine-grained rollback, rather than the full rollback that would be performed by ``transaction.rollback()``. +Each of these functions takes a ``using`` argument which should be the name of +a database for which the behavior applies. If no ``using`` argument is +provided then the ``"default"`` database is used. + Savepoints are controlled by three methods on the transaction object: -.. method:: transaction.savepoint() +.. method:: transaction.savepoint(using=None) Creates a new savepoint. This marks a point in the transaction that is known to be in a "good" state. Returns the savepoint ID (sid). -.. method:: transaction.savepoint_commit(sid) +.. method:: transaction.savepoint_commit(sid, using=None) Updates the savepoint to include any operations that have been performed since the savepoint was created, or since the last commit. -.. method:: transaction.savepoint_rollback(sid) +.. method:: transaction.savepoint_rollback(sid, using=None) Rolls the transaction back to the last point at which the savepoint was committed.