| 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. |