Debian Codegraph @

docs/topics/db/transactions.txt

raw
1 =====================
2 Database transactions
3 =====================
4
5 .. module:: django.db.transaction
6
7 Django gives you a few ways to control how database transactions are managed.
8
9 Managing database transactions
10 ==============================
11
12 Django's default transaction behavior
13 -------------------------------------
14
15 Django's default behavior is to run in autocommit mode. Each query is
16 immediately committed to the database, unless a transaction is active.
17 :ref:`See below for details <autocommit-details>`.
18
19 Django uses transactions or savepoints automatically to guarantee the
20 integrity of ORM operations that require multiple queries, especially
21 :ref:`delete() <topics-db-queries-delete>` and :ref:`update()
22 <topics-db-queries-update>` queries.
23
24 Django's :class:`~django.test.TestCase` class also wraps each test in a
25 transaction for performance reasons.
26
27 .. _tying-transactions-to-http-requests:
28
29 Tying transactions to HTTP requests
30 -----------------------------------
31
32 A common way to handle transactions on the web is to wrap each request in a
33 transaction. Set :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` to
34 ``True`` in the configuration of each database for which you want to enable
35 this behavior.
36
37 It works like this. Before calling a view function, Django starts a
38 transaction. If the response is produced without problems, Django commits the
39 transaction. If the view produces an exception, Django rolls back the
40 transaction.
41
42 You may perform subtransactions using savepoints in your view code, typically
43 with the :func:`atomic` context manager. However, at the end of the view,
44 either all or none of the changes will be committed.
45
46 .. warning::
47
48 While the simplicity of this transaction model is appealing, it also makes it
49 inefficient when traffic increases. Opening a transaction for every view has
50 some overhead. The impact on performance depends on the query patterns of your
51 application and on how well your database handles locking.
52
53 .. admonition:: Per-request transactions and streaming responses
54
55 When a view returns a :class:`~django.http.StreamingHttpResponse`, reading
56 the contents of the response will often execute code to generate the
57 content. Since the view has already returned, such code runs outside of
58 the transaction.
59
60 Generally speaking, it isn't advisable to write to the database while
61 generating a streaming response, since there's no sensible way to handle
62 errors after starting to send the response.
63
64 In practice, this feature wraps every view function in the :func:`atomic`
65 decorator described below.
66
67 Note that only the execution of your view is enclosed in the transactions.
68 Middleware runs outside of the transaction, and so does the rendering of
69 template responses.
70
71 When :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` is enabled, it's
72 still possible to prevent views from running in a transaction.
73
74 .. function:: non_atomic_requests(using=None)
75
76 This decorator will negate the effect of :setting:`ATOMIC_REQUESTS
77 <DATABASE-ATOMIC_REQUESTS>` for a given view::
78
79 from django.db import transaction
80
81
82 @transaction.non_atomic_requests
83 def my_view(request):
84 do_stuff()
85
86
87 @transaction.non_atomic_requests(using="other")
88 def my_other_view(request):
89 do_stuff_on_the_other_database()
90
91 It only works if it's applied to the view itself.
92
93 Controlling transactions explicitly
94 -----------------------------------
95
96 Django provides a single API to control database transactions.
97
98 .. function:: atomic(using=None, savepoint=True, durable=False)
99
100 Atomicity is the defining property of database transactions. ``atomic``
101 allows us to create a block of code within which the atomicity on the
102 database is guaranteed. If the block of code is successfully completed, the
103 changes are committed to the database. If there is an exception, the
104 changes are rolled back.
105
106 ``atomic`` blocks can be nested. In this case, when an inner block
107 completes successfully, its effects can still be rolled back if an
108 exception is raised in the outer block at a later point.
109
110 It is sometimes useful to ensure an ``atomic`` block is always the
111 outermost ``atomic`` block, ensuring that any database changes are
112 committed when the block is exited without errors. This is known as
113 durability and can be achieved by setting ``durable=True``. If the
114 ``atomic`` block is nested within another it raises a ``RuntimeError``.
115
116 ``atomic`` is usable both as a :py:term:`decorator`::
117
118 from django.db import transaction
119
120
121 @transaction.atomic
122 def viewfunc(request):
123 # This code executes inside a transaction.
124 do_stuff()
125
126 and as a :py:term:`context manager`::
127
128 from django.db import transaction
129
130
131 def viewfunc(request):
132 # This code executes in autocommit mode (Django's default).
133 do_stuff()
134
135 with transaction.atomic():
136 # This code executes inside a transaction.
137 do_more_stuff()
138
139 Wrapping ``atomic`` in a try/except block allows for natural handling of
140 integrity errors::
141
142 from django.db import IntegrityError, transaction
143
144
145 @transaction.atomic
146 def viewfunc(request):
147 create_parent()
148
149 try:
150 with transaction.atomic():
151 generate_relationships()
152 except IntegrityError:
153 handle_exception()
154
155 add_children()
156
157 In this example, even if ``generate_relationships()`` causes a database
158 error by breaking an integrity constraint, you can execute queries in
159 ``add_children()``, and the changes from ``create_parent()`` are still
160 there and bound to the same transaction. Note that any operations attempted
161 in ``generate_relationships()`` will already have been rolled back safely
162 when ``handle_exception()`` is called, so the exception handler can also
163 operate on the database if necessary.
164
165 .. admonition:: Avoid catching exceptions inside ``atomic``!
166
167 When exiting an ``atomic`` block, Django looks at whether it's exited
168 normally or with an exception to determine whether to commit or roll
169 back. If you catch and handle exceptions inside an ``atomic`` block,
170 you may hide from Django the fact that a problem has happened. This
171 can result in unexpected behavior.
172
173 This is mostly a concern for :exc:`~django.db.DatabaseError` and its
174 subclasses such as :exc:`~django.db.IntegrityError`. After such an
175 error, the transaction is broken and Django will perform a rollback at
176 the end of the ``atomic`` block. If you attempt to run database
177 queries before the rollback happens, Django will raise a
178 :class:`~django.db.transaction.TransactionManagementError`. You may
179 also encounter this behavior when an ORM-related signal handler raises
180 an exception.
181
182 The correct way to catch database errors is around an ``atomic`` block
183 as shown above. If necessary, add an extra ``atomic`` block for this
184 purpose. This pattern has another advantage: it delimits explicitly
185 which operations will be rolled back if an exception occurs.
186
187 If you catch exceptions raised by raw SQL queries, Django's behavior
188 is unspecified and database-dependent.
189
190 .. admonition:: You may need to manually revert app state when rolling back a transaction.
191
192 The values of a model's fields won't be reverted when a transaction
193 rollback happens. This could lead to an inconsistent model state unless
194 you manually restore the original field values.
195
196 For example, given ``MyModel`` with an ``active`` field, this snippet
197 ensures that the ``if obj.active`` check at the end uses the correct
198 value if updating ``active`` to ``True`` fails in the transaction::
199
200 from django.db import DatabaseError, transaction
201
202 obj = MyModel(active=False)
203 obj.active = True
204 try:
205 with transaction.atomic():
206 obj.save()
207 except DatabaseError:
208 obj.active = False
209
210 if obj.active:
211 ...
212
213 This also applies to any other mechanism that may hold app state, such
214 as caching or global variables. For example, if the code proactively
215 updates data in the cache after saving an object, it's recommended to
216 use :ref:`transaction.on_commit() <performing-actions-after-commit>`
217 instead, to defer cache alterations until the transaction is actually
218 committed.
219
220 In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
221 to commit, roll back, or change the autocommit state of the database
222 connection within an ``atomic`` block will raise an exception.
223
224 ``atomic`` takes a ``using`` argument which should be the name of a
225 database. If this argument isn't provided, Django uses the ``"default"``
226 database.
227
228 Under the hood, Django's transaction management code:
229
230 - opens a transaction when entering the outermost ``atomic`` block;
231 - creates a savepoint when entering an inner ``atomic`` block;
232 - releases or rolls back to the savepoint when exiting an inner block;
233 - commits or rolls back the transaction when exiting the outermost block.
234
235 You can disable the creation of savepoints for inner blocks by setting the
236 ``savepoint`` argument to ``False``. If an exception occurs, Django will
237 perform the rollback when exiting the first parent block with a savepoint
238 if there is one, and the outermost block otherwise. Atomicity is still
239 guaranteed by the outer transaction. This option should only be used if
240 the overhead of savepoints is noticeable. It has the drawback of breaking
241 the error handling described above.
242
243 You may use ``atomic`` when autocommit is turned off. It will only use
244 savepoints, even for the outermost block.
245
246 .. admonition:: Performance considerations
247
248 Open transactions have a performance cost for your database server. To
249 minimize this overhead, keep your transactions as short as possible. This
250 is especially important if you're using :func:`atomic` in long-running
251 processes, outside of Django's request / response cycle.
252
253 Autocommit
254 ==========
255
256 .. _autocommit-details:
257
258 Why Django uses autocommit
259 --------------------------
260
261 In the SQL standards, each SQL query starts a transaction, unless one is
262 already active. Such transactions must then be explicitly committed or rolled
263 back.
264
265 This isn't always convenient for application developers. To alleviate this
266 problem, most databases provide an autocommit mode. When autocommit is turned
267 on and no transaction is active, each SQL query gets wrapped in its own
268 transaction. In other words, not only does each such query start a
269 transaction, but the transaction also gets automatically committed or rolled
270 back, depending on whether the query succeeded.
271
272 :pep:`249`, the Python Database API Specification v2.0, requires autocommit to
273 be initially turned off. Django overrides this default and turns autocommit
274 on.
275
276 To avoid this, you can :ref:`deactivate the transaction management
277 <deactivate-transaction-management>`, but it isn't recommended.
278
279 .. _deactivate-transaction-management:
280
281 Deactivating transaction management
282 -----------------------------------
283
284 You can totally disable Django's transaction management for a given database
285 by setting :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>` to ``False`` in its
286 configuration. If you do this, Django won't enable autocommit, and won't
287 perform any commits. You'll get the regular behavior of the underlying
288 database library.
289
290 This requires you to commit explicitly every transaction, even those started
291 by Django or by third-party libraries. Thus, this is best used in situations
292 where you want to run your own transaction-controlling middleware or do
293 something really strange.
294
295 .. _performing-actions-after-commit:
296
297 Performing actions after commit
298 ===============================
299
300 Sometimes you need to perform an action related to the current database
301 transaction, but only if the transaction successfully commits. Examples might
302 include a background task, an email notification, or a cache invalidation.
303
304 :func:`on_commit` allows you to register callbacks that will be executed after
305 the open transaction is successfully committed:
306
307 .. function:: on_commit(func, using=None, robust=False)
308
309 Pass a function, or any callable, to :func:`on_commit`::
310
311 from django.db import transaction
312
313
314 def send_welcome_email(): ...
315
316
317 transaction.on_commit(send_welcome_email)
318
319 Callbacks will not be passed any arguments, but you can bind them with
320 :func:`functools.partial`::
321
322 from functools import partial
323
324 for user in users:
325 transaction.on_commit(partial(send_invite_email, user=user))
326
327 Callbacks are called after the open transaction is successfully committed. If
328 the transaction is instead rolled back (typically when an unhandled exception
329 is raised in an :func:`atomic` block), the callback will be discarded, and
330 never called.
331
332 If you call ``on_commit()`` while there isn't an open transaction,
333 the callback will be executed immediately.
334
335 It's sometimes useful to register callbacks that can fail. Passing
336 ``robust=True`` allows the next callbacks to be executed even if the current
337 one throws an exception. All errors derived from Python's ``Exception`` class
338 are caught and logged to the ``django.db.backends.base`` logger.
339
340 You can use :meth:`.TestCase.captureOnCommitCallbacks` to test callbacks
341 registered with :func:`on_commit`.
342
343 Savepoints
344 ----------
345
346 Savepoints (i.e. nested :func:`atomic` blocks) are handled correctly. That is,
347 an :func:`on_commit` callable registered after a savepoint (in a nested
348 :func:`atomic` block) will be called after the outer transaction is committed,
349 but not if a rollback to that savepoint or any previous savepoint occurred
350 during the transaction::
351
352 with transaction.atomic(): # Outer atomic, start a new transaction
353 transaction.on_commit(foo)
354
355 with transaction.atomic(): # Inner atomic block, create a savepoint
356 transaction.on_commit(bar)
357
358 # foo() and then bar() will be called when leaving the outermost block
359
360 On the other hand, when a savepoint is rolled back (due to an exception being
361 raised), the inner callable will not be called::
362
363 with transaction.atomic(): # Outer atomic, start a new transaction
364 transaction.on_commit(foo)
365
366 try:
367 with transaction.atomic(): # Inner atomic block, create a savepoint
368 transaction.on_commit(bar)
369 raise SomeError() # Raising an exception - abort the savepoint
370 except SomeError:
371 pass
372
373 # foo() will be called, but not bar()
374
375 Order of execution
376 ------------------
377
378 On-commit functions for a given transaction are executed in the order they were
379 registered.
380
381 Exception handling
382 ------------------
383
384 If one on-commit function registered with ``robust=False`` within a given
385 transaction raises an uncaught exception, no later registered functions in that
386 same transaction will run. This is the same behavior as if you'd executed the
387 functions sequentially yourself without :func:`on_commit`.
388
389 Timing of execution
390 -------------------
391
392 Your callbacks are executed *after* a successful commit, so a failure in a
393 callback will not cause the transaction to roll back. They are executed
394 conditionally upon the success of the transaction, but they are not *part* of
395 the transaction. For the intended use cases (mail notifications, background
396 tasks, etc.), this should be fine. If it's not (if your follow-up action is so
397 critical that its failure should mean the failure of the transaction itself),
398 then you don't want to use the :func:`on_commit` hook. Instead, you may want
399 `two-phase commit`_ such as the :ref:`psycopg Two-Phase Commit protocol support
400 <psycopg:two-phase-commit>` and the :pep:`optional Two-Phase Commit Extensions
401 in the Python DB-API specification <249#optional-two-phase-commit-extensions>`.
402
403 Callbacks are not run until autocommit is restored on the connection following
404 the commit (because otherwise any queries done in a callback would open an
405 implicit transaction, preventing the connection from going back into autocommit
406 mode).
407
408 When in autocommit mode and outside of an :func:`atomic` block, the function
409 will run immediately, not on commit.
410
411 On-commit functions only work with :ref:`autocommit mode <managing-autocommit>`
412 and the :func:`atomic` (or :setting:`ATOMIC_REQUESTS
413 <DATABASE-ATOMIC_REQUESTS>`) transaction API. Calling :func:`on_commit` when
414 autocommit is disabled and you are not within an atomic block will result in an
415 error.
416
417 .. _two-phase commit: https://en.wikipedia.org/wiki/Two-phase_commit_protocol
418
419 Use in tests
420 ------------
421
422 Django's :class:`~django.test.TestCase` class wraps each test in a transaction
423 and rolls back that transaction after each test, in order to provide test
424 isolation. This means that no transaction is ever actually committed, thus your
425 :func:`on_commit` callbacks will never be run.
426
427 You can overcome this limitation by using
428 :meth:`.TestCase.captureOnCommitCallbacks`. This captures your
429 :func:`on_commit` callbacks in a list, allowing you to make assertions on them,
430 or emulate the transaction committing by calling them.
431
432 Another way to overcome the limitation is to use
433 :class:`~django.test.TransactionTestCase` instead of
434 :class:`~django.test.TestCase`. This will mean your transactions are committed,
435 and the callbacks will run. However
436 :class:`~django.test.TransactionTestCase` flushes the database between tests,
437 which is significantly slower than :class:`~django.test.TestCase`\'s isolation.
438
439 Why no rollback hook?
440 ---------------------
441
442 A rollback hook is harder to implement robustly than a commit hook, since a
443 variety of things can cause an implicit rollback.
444
445 For instance, if your database connection is dropped because your process was
446 killed without a chance to shut down gracefully, your rollback hook will never
447 run.
448
449 But there is a solution: instead of doing something during the atomic block
450 (transaction) and then undoing it if the transaction fails, use
451 :func:`on_commit` to delay doing it in the first place until after the
452 transaction succeeds. It's a lot easier to undo something you never did in the
453 first place!
454
455 Low-level APIs
456 ==============
457
458 .. warning::
459
460 Always prefer :func:`atomic` if possible at all. It accounts for the
461 idiosyncrasies of each database and prevents invalid operations.
462
463 The low level APIs are only useful if you're implementing your own
464 transaction management.
465
466 .. _managing-autocommit:
467
468 Autocommit
469 ----------
470
471 Django provides an API in the :mod:`django.db.transaction` module to manage the
472 autocommit state of each database connection.
473
474 .. function:: get_autocommit(using=None)
475
476 .. function:: set_autocommit(autocommit, using=None)
477
478 These functions take a ``using`` argument which should be the name of a
479 database. If it isn't provided, Django uses the ``"default"`` database.
480
481 Autocommit is initially turned on. If you turn it off, it's your
482 responsibility to restore it.
483
484 Once you turn autocommit off, you get the default behavior of your database
485 adapter, and Django won't help you. Although that behavior is specified in
486 :pep:`249`, implementations of adapters aren't always consistent with one
487 another. Review the documentation of the adapter you're using carefully.
488
489 You must ensure that no transaction is active, usually by issuing a
490 :func:`commit` or a :func:`rollback`, before turning autocommit back on.
491
492 Django will refuse to turn autocommit off when an :func:`atomic` block is
493 active, because that would break atomicity.
494
495 Transactions
496 ------------
497
498 A transaction is an atomic set of database queries. Even if your program
499 crashes, the database guarantees that either all the changes will be applied,
500 or none of them.
501
502 Django doesn't provide an API to start a transaction. The expected way to
503 start a transaction is to disable autocommit with :func:`set_autocommit`.
504
505 Once you're in a transaction, you can choose either to apply the changes
506 you've performed until this point with :func:`commit`, or to cancel them with
507 :func:`rollback`. These functions are defined in :mod:`django.db.transaction`.
508
509 .. function:: commit(using=None)
510
511 .. function:: rollback(using=None)
512
513 These functions take a ``using`` argument which should be the name of a
514 database. If it isn't provided, Django uses the ``"default"`` database.
515
516 Django will refuse to commit or to rollback when an :func:`atomic` block is
517 active, because that would break atomicity.
518
519 .. _topics-db-transactions-savepoints:
520
521 Savepoints
522 ----------
523
524 A savepoint is a marker within a transaction that enables you to roll back
525 part of a transaction, rather than the full transaction. Savepoints are
526 available with the SQLite, PostgreSQL, Oracle, and MySQL (when using the InnoDB
527 storage engine) backends. Other backends provide the savepoint functions, but
528 they're empty operations -- they don't actually do anything.
529
530 Savepoints aren't especially useful if you are using autocommit, the default
531 behavior of Django. However, once you open a transaction with :func:`atomic`,
532 you build up a series of database operations awaiting a commit or rollback. If
533 you issue a rollback, the entire transaction is rolled back. Savepoints
534 provide the ability to perform a fine-grained rollback, rather than the full
535 rollback that would be performed by ``transaction.rollback()``.
536
537 When the :func:`atomic` decorator is nested, it creates a savepoint to allow
538 partial commit or rollback. You're strongly encouraged to use :func:`atomic`
539 rather than the functions described below, but they're still part of the
540 public API, and there's no plan to deprecate them.
541
542 Each of these functions takes a ``using`` argument which should be the name of
543 a database for which the behavior applies. If no ``using`` argument is
544 provided then the ``"default"`` database is used.
545
546 Savepoints are controlled by three functions in :mod:`django.db.transaction`:
547
548 .. function:: savepoint(using=None)
549
550 Creates a new savepoint. This marks a point in the transaction that is
551 known to be in a "good" state. Returns the savepoint ID (``sid``).
552
553 .. function:: savepoint_commit(sid, using=None)
554
555 Releases savepoint ``sid``. The changes performed since the savepoint was
556 created become part of the transaction.
557
558 .. function:: savepoint_rollback(sid, using=None)
559
560 Rolls back the transaction to savepoint ``sid``.
561
562 These functions do nothing if savepoints aren't supported or if the database
563 is in autocommit mode.
564
565 In addition, there's a utility function:
566
567 .. function:: clean_savepoints(using=None)
568
569 Resets the counter used to generate unique savepoint IDs.
570
571 The following example demonstrates the use of savepoints::
572
573 from django.db import transaction
574
575
576 # open a transaction
577 @transaction.atomic
578 def viewfunc(request):
579 a.save()
580 # transaction now contains a.save()
581
582 sid = transaction.savepoint()
583
584 b.save()
585 # transaction now contains a.save() and b.save()
586
587 if want_to_keep_b:
588 transaction.savepoint_commit(sid)
589 # open transaction still contains a.save() and b.save()
590 else:
591 transaction.savepoint_rollback(sid)
592 # open transaction now contains only a.save()
593
594 Savepoints may be used to recover from a database error by performing a partial
595 rollback. If you're doing this inside an :func:`atomic` block, the entire block
596 will still be rolled back, because it doesn't know you've handled the situation
597 at a lower level! To prevent this, you can control the rollback behavior with
598 the following functions.
599
600 .. function:: get_rollback(using=None)
601
602 .. function:: set_rollback(rollback, using=None)
603
604 Setting the rollback flag to ``True`` forces a rollback when exiting the
605 innermost atomic block. This may be useful to trigger a rollback without
606 raising an exception.
607
608 Setting it to ``False`` prevents such a rollback. Before doing that, make sure
609 you've rolled back the transaction to a known-good savepoint within the current
610 atomic block! Otherwise you're breaking atomicity and data corruption may
611 occur.
612
613 Database-specific notes
614 =======================
615
616 .. _savepoints-in-sqlite:
617
618 Savepoints in SQLite
619 --------------------
620
621 While SQLite supports savepoints, a flaw in the design of the :mod:`sqlite3`
622 module makes them hardly usable.
623
624 When autocommit is enabled, savepoints don't make sense. When it's disabled,
625 :mod:`sqlite3` commits implicitly before savepoint statements. (In fact, it
626 commits before any statement other than ``SELECT``, ``INSERT``, ``UPDATE``,
627 ``DELETE`` and ``REPLACE``.) This bug has two consequences:
628
629 - The low level APIs for savepoints are only usable inside a transaction i.e.
630 inside an :func:`atomic` block.
631 - It's impossible to use :func:`atomic` when autocommit is turned off.
632
633 Transactions in MySQL
634 ---------------------
635
636 If you're using MySQL, your tables may or may not support transactions; it
637 depends on your MySQL version and the table types you're using. (By
638 "table types," we mean something like "InnoDB" or "MyISAM".) MySQL transaction
639 peculiarities are outside the scope of this article, but the MySQL site has
640 `information on MySQL transactions`_.
641
642 If your MySQL setup does *not* support transactions, then Django will always
643 function in autocommit mode: statements will be executed and committed as soon
644 as they're called. If your MySQL setup *does* support transactions, Django
645 will handle transactions as explained in this document.
646
647 .. _information on MySQL transactions: https://dev.mysql.com/doc/refman/en/sql-transactional-statements.html
648
649 Handling exceptions within PostgreSQL transactions
650 --------------------------------------------------
651
652 .. note::
653
654 This section is relevant only if you're implementing your own transaction
655 management. This problem cannot occur in Django's default mode and
656 :func:`atomic` handles it automatically.
657
658 Inside a transaction, when a call to a PostgreSQL cursor raises an exception
659 (typically ``IntegrityError``), all subsequent SQL in the same transaction
660 will fail with the error "current transaction is aborted, queries ignored
661 until end of transaction block". While the basic use of ``save()`` is unlikely
662 to raise an exception in PostgreSQL, there are more advanced usage patterns
663 which might, such as saving objects with unique fields, saving using the
664 ``force_insert``/``force_update`` flag, or invoking custom SQL.
665
666 There are several ways to recover from this sort of error.
667
668 Transaction rollback
669 ~~~~~~~~~~~~~~~~~~~~
670
671 The first option is to roll back the entire transaction. For example::
672
673 a.save() # Succeeds, but may be undone by transaction rollback
674 try:
675 b.save() # Could throw exception
676 except IntegrityError:
677 transaction.rollback()
678 c.save() # Succeeds, but a.save() may have been undone
679
680 Calling ``transaction.rollback()`` rolls back the entire transaction. Any
681 uncommitted database operations will be lost. In this example, the changes
682 made by ``a.save()`` would be lost, even though that operation raised no error
683 itself.
684
685 Savepoint rollback
686 ~~~~~~~~~~~~~~~~~~
687
688 You can use :ref:`savepoints <topics-db-transactions-savepoints>` to control
689 the extent of a rollback. Before performing a database operation that could
690 fail, you can set or update the savepoint; that way, if the operation fails,
691 you can roll back the single offending operation, rather than the entire
692 transaction. For example::
693
694 a.save() # Succeeds, and never undone by savepoint rollback
695 sid = transaction.savepoint()
696 try:
697 b.save() # Could throw exception
698 transaction.savepoint_commit(sid)
699 except IntegrityError:
700 transaction.savepoint_rollback(sid)
701 c.save() # Succeeds, and a.save() is never undone
702
703 In this example, ``a.save()`` will not be undone in the case where
704 ``b.save()`` raises an exception.