Transactions.txt Guest on 29th April 2021 06:42:38 AM
  1. =====================
  2. Database transactions
  3. =====================
  5. .. module:: django.db.transaction
  7. Django gives you a few ways to control how database transactions are managed.
  9. Managing database transactions
  10. ==============================
  12. Django's default transaction behavior
  13. -------------------------------------
  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>`.
  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.
  24. Django's :class:`~django.test.TestCase` class also wraps each test in a
  25. transaction for performance reasons.
  27. .. _tying-transactions-to-http-requests:
  29. Tying transactions to HTTP requests
  30. -----------------------------------
  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.
  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.
  42. You may perform partial commits and rollbacks in your view code, typically with
  43. the :func:`atomic` context manager. However, at the end of the view, either
  44. all the changes will be committed, or none of them.
  46. .. warning::
  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.
  53. .. admonition:: Per-request transactions and streaming responses
  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.
  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.
  64. In practice, this feature simply wraps every view function in the :func:`atomic`
  65. decorator described below.
  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.
  71. When :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` is enabled, it's
  72. still possible to prevent views from running in a transaction.
  74. .. function:: non_atomic_requests(using=None)
  76.     This decorator will negate the effect of :setting:`ATOMIC_REQUESTS
  77.     <DATABASE-ATOMIC_REQUESTS>` for a given view::
  79.         from django.db import transaction
  81.         @transaction.non_atomic_requests
  82.         def my_view(request):
  83.             do_stuff()
  85.         @transaction.non_atomic_requests(using='other')
  86.         def my_other_view(request):
  87.             do_stuff_on_the_other_database()
  89.     It only works if it's applied to the view itself.
  91. Controlling transactions explicitly
  92. -----------------------------------
  94. Django provides a single API to control database transactions.
  96. .. function:: atomic(using=None, savepoint=True)
  98.     Atomicity is the defining property of database transactions. ``atomic``
  99.     allows us to create a block of code within which the atomicity on the
  100.     database is guaranteed. If the block of code is successfully completed, the
  101.     changes are committed to the database. If there is an exception, the
  102.     changes are rolled back.
  104.     ``atomic`` blocks can be nested. In this case, when an inner block
  105.     completes successfully, its effects can still be rolled back if an
  106.     exception is raised in the outer block at a later point.
  108.     ``atomic`` is usable both as a :py:term:`decorator`::
  110.         from django.db import transaction
  112.         @transaction.atomic
  113.         def viewfunc(request):
  114.             # This code executes inside a transaction.
  115.             do_stuff()
  117.     and as a :py:term:`context manager`::
  119.         from django.db import transaction
  121.         def viewfunc(request):
  122.             # This code executes in autocommit mode (Django's default).
  123.             do_stuff()
  125.             with transaction.atomic():
  126.                 # This code executes inside a transaction.
  127.                 do_more_stuff()
  129.     Wrapping ``atomic`` in a try/except block allows for natural handling of
  130.     integrity errors::
  132.         from django.db import IntegrityError, transaction
  134.         @transaction.atomic
  135.         def viewfunc(request):
  136.             create_parent()
  138.             try:
  139.                 with transaction.atomic():
  140.                     generate_relationships()
  141.             except IntegrityError:
  142.                 handle_exception()
  144.             add_children()
  146.     In this example, even if ``generate_relationships()`` causes a database
  147.     error by breaking an integrity constraint, you can execute queries in
  148.     ``add_children()``, and the changes from ``create_parent()`` are still
  149.     there. Note that any operations attempted in ``generate_relationships()``
  150.     will already have been rolled back safely when ``handle_exception()`` is
  151.     called, so the exception handler can also operate on the database if
  152.     necessary.
  154.     .. admonition:: Avoid catching exceptions inside ``atomic``!
  156.         When exiting an ``atomic`` block, Django looks at whether it's exited
  157.         normally or with an exception to determine whether to commit or roll
  158.         back. If you catch and handle exceptions inside an ``atomic`` block,
  159.         you may hide from Django the fact that a problem has happened. This
  160.         can result in unexpected behavior.
  162.         This is mostly a concern for :exc:`~django.db.DatabaseError` and its
  163.         subclasses such as :exc:`~django.db.IntegrityError`. After such an
  164.         error, the transaction is broken and Django will perform a rollback at
  165.         the end of the ``atomic`` block. If you attempt to run database
  166.         queries before the rollback happens, Django will raise a
  167.         :class:`~django.db.transaction.TransactionManagementError`. You may
  168.         also encounter this behavior when an ORM-related signal handler raises
  169.         an exception.
  171.         The correct way to catch database errors is around an ``atomic`` block
  172.         as shown above. If necessary, add an extra ``atomic`` block for this
  173.         purpose. This pattern has another advantage: it delimits explicitly
  174.         which operations will be rolled back if an exception occurs.
  176.         If you catch exceptions raised by raw SQL queries, Django's behavior
  177.         is unspecified and database-dependent.
  179.     In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
  180.     to commit, roll back, or change the autocommit state of the database
  181.     connection within an ``atomic`` block will raise an exception.
  183.     ``atomic`` takes a ``using`` argument which should be the name of a
  184.     database. If this argument isn't provided, Django uses the ``"default"``
  185.     database.
  187.     Under the hood, Django's transaction management code:
  189.     - opens a transaction when entering the outermost ``atomic`` block;
  190.     - creates a savepoint when entering an inner ``atomic`` block;
  191.     - releases or rolls back to the savepoint when exiting an inner block;
  192.     - commits or rolls back the transaction when exiting the outermost block.
  194.     You can disable the creation of savepoints for inner blocks by setting the
  195.     ``savepoint`` argument to ``False``. If an exception occurs, Django will
  196.     perform the rollback when exiting the first parent block with a savepoint
  197.     if there is one, and the outermost block otherwise. Atomicity is still
  198.     guaranteed by the outer transaction. This option should only be used if
  199.     the overhead of savepoints is noticeable. It has the drawback of breaking
  200.     the error handling described above.
  202.     You may use ``atomic`` when autocommit is turned off. It will only use
  203.     savepoints, even for the outermost block, and it will raise an exception
  204.     if the outermost block is declared with ``savepoint=False``.
  206. .. admonition:: Performance considerations
  208.     Open transactions have a performance cost for your database server. To
  209.     minimize this overhead, keep your transactions as short as possible. This
  210.     is especially important if you're using :func:`atomic` in long-running
  211.     processes, outside of Django's request / response cycle.
  213. Autocommit
  214. ==========
  216. .. _autocommit-details:
  218. Why Django uses autocommit
  219. --------------------------
  221. In the SQL standards, each SQL query starts a transaction, unless one is
  222. already active. Such transactions must then be explicitly committed or rolled
  223. back.
  225. This isn't always convenient for application developers. To alleviate this
  226. problem, most databases provide an autocommit mode. When autocommit is turned
  227. on and no transaction is active, each SQL query gets wrapped in its own
  228. transaction. In other words, not only does each such query start a
  229. transaction, but the transaction also gets automatically committed or rolled
  230. back, depending on whether the query succeeded.
  232. :pep:`249`, the Python Database API Specification v2.0, requires autocommit to
  233. be initially turned off. Django overrides this default and turns autocommit
  234. on.
  236. To avoid this, you can :ref:`deactivate the transaction management
  237. <deactivate-transaction-management>`, but it isn't recommended.
  239. .. _deactivate-transaction-management:
  241. Deactivating transaction management
  242. -----------------------------------
  244. You can totally disable Django's transaction management for a given database
  245. by setting :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>` to ``False`` in its
  246. configuration. If you do this, Django won't enable autocommit, and won't
  247. perform any commits. You'll get the regular behavior of the underlying
  248. database library.
  250. This requires you to commit explicitly every transaction, even those started
  251. by Django or by third-party libraries. Thus, this is best used in situations
  252. where you want to run your own transaction-controlling middleware or do
  253. something really strange.
  255. Low-level APIs
  256. ==============
  258. .. warning::
  260.     Always prefer :func:`atomic` if possible at all. It accounts for the
  261.     idiosyncrasies of each database and prevents invalid operations.
  263.     The low level APIs are only useful if you're implementing your own
  264.     transaction management.
  266. .. _managing-autocommit:
  268. Autocommit
  269. ----------
  271. Django provides a straightforward API in the :mod:`django.db.transaction`
  272. module to manage the autocommit state of each database connection.
  274. .. function:: get_autocommit(using=None)
  276. .. function:: set_autocommit(autocommit, using=None)
  278. These functions take a ``using`` argument which should be the name of a
  279. database. If it isn't provided, Django uses the ``"default"`` database.
  281. Autocommit is initially turned on. If you turn it off, it's your
  282. responsibility to restore it.
  284. Once you turn autocommit off, you get the default behavior of your database
  285. adapter, and Django won't help you. Although that behavior is specified in
  286. :pep:`249`, implementations of adapters aren't always consistent with one
  287. another. Review the documentation of the adapter you're using carefully.
  289. You must ensure that no transaction is active, usually by issuing a
  290. :func:`commit` or a :func:`rollback`, before turning autocommit back on.
  292. Django will refuse to turn autocommit off when an :func:`atomic` block is
  293. active, because that would break atomicity.
  295. Transactions
  296. ------------
  298. A transaction is an atomic set of database queries. Even if your program
  299. crashes, the database guarantees that either all the changes will be applied,
  300. or none of them.
  302. Django doesn't provide an API to start a transaction. The expected way to
  303. start a transaction is to disable autocommit with :func:`set_autocommit`.
  305. Once you're in a transaction, you can choose either to apply the changes
  306. you've performed until this point with :func:`commit`, or to cancel them with
  307. :func:`rollback`. These functions are defined in :mod:`django.db.transaction`.
  309. .. function:: commit(using=None)
  311. .. function:: rollback(using=None)
  313. These functions take a ``using`` argument which should be the name of a
  314. database. If it isn't provided, Django uses the ``"default"`` database.
  316. Django will refuse to commit or to rollback when an :func:`atomic` block is
  317. active, because that would break atomicity.
  319. .. _topics-db-transactions-savepoints:
  321. Savepoints
  322. ----------
  324. A savepoint is a marker within a transaction that enables you to roll back
  325. part of a transaction, rather than the full transaction. Savepoints are
  326. available with the SQLite (≥ 3.6.8), PostgreSQL, Oracle and MySQL (when using
  327. the InnoDB storage engine) backends. Other backends provide the savepoint
  328. functions, but they're empty operations -- they don't actually do anything.
  330. Savepoints aren't especially useful if you are using autocommit, the default
  331. behavior of Django. However, once you open a transaction with :func:`atomic`,
  332. you build up a series of database operations awaiting a commit or rollback. If
  333. you issue a rollback, the entire transaction is rolled back. Savepoints
  334. provide the ability to perform a fine-grained rollback, rather than the full
  335. rollback that would be performed by ``transaction.rollback()``.
  337. When the :func:`atomic` decorator is nested, it creates a savepoint to allow
  338. partial commit or rollback. You're strongly encouraged to use :func:`atomic`
  339. rather than the functions described below, but they're still part of the
  340. public API, and there's no plan to deprecate them.
  342. Each of these functions takes a ``using`` argument which should be the name of
  343. a database for which the behavior applies.  If no ``using`` argument is
  344. provided then the ``"default"`` database is used.
  346. Savepoints are controlled by three functions in :mod:`django.db.transaction`:
  348. .. function:: savepoint(using=None)
  350.     Creates a new savepoint. This marks a point in the transaction that is
  351.     known to be in a "good" state. Returns the savepoint ID (``sid``).
  353. .. function:: savepoint_commit(sid, using=None)
  355.     Releases savepoint ``sid``. The changes performed since the savepoint was
  356.     created become part of the transaction.
  358. .. function:: savepoint_rollback(sid, using=None)
  360.     Rolls back the transaction to savepoint ``sid``.
  362. These functions do nothing if savepoints aren't supported or if the database
  363. is in autocommit mode.
  365. In addition, there's a utility function:
  367. .. function:: clean_savepoints(using=None)
  369.     Resets the counter used to generate unique savepoint IDs.
  371. The following example demonstrates the use of savepoints::
  373.     from django.db import transaction
  375.     # open a transaction
  376.     @transaction.atomic
  377.     def viewfunc(request):
  379.         a.save()
  380.         # transaction now contains a.save()
  382.         sid = transaction.savepoint()
  384.         b.save()
  385.         # transaction now contains a.save() and b.save()
  387.         if want_to_keep_b:
  388.             transaction.savepoint_commit(sid)
  389.             # open transaction still contains a.save() and b.save()
  390.         else:
  391.             transaction.savepoint_rollback(sid)
  392.             # open transaction now contains only a.save()
  394. Savepoints may be used to recover from a database error by performing a partial
  395. rollback. If you're doing this inside an :func:`atomic` block, the entire block
  396. will still be rolled back, because it doesn't know you've handled the situation
  397. at a lower level! To prevent this, you can control the rollback behavior with
  398. the following functions.
  400. .. function:: get_rollback(using=None)
  402. .. function:: set_rollback(rollback, using=None)
  404. Setting the rollback flag to ``True`` forces a rollback when exiting the
  405. innermost atomic block. This may be useful to trigger a rollback without
  406. raising an exception.
  408. Setting it to ``False`` prevents such a rollback. Before doing that, make sure
  409. you've rolled back the transaction to a known-good savepoint within the current
  410. atomic block! Otherwise you're breaking atomicity and data corruption may
  411. occur.
  413. Database-specific notes
  414. =======================
  416. .. _savepoints-in-sqlite:
  418. Savepoints in SQLite
  419. --------------------
  421. While SQLite ≥ 3.6.8 supports savepoints, a flaw in the design of the
  422. :mod:`sqlite3` module makes them hardly usable.
  424. When autocommit is enabled, savepoints don't make sense. When it's disabled,
  425. :mod:`sqlite3` commits implicitly before savepoint statements. (In fact, it
  426. commits before any statement other than ``SELECT``, ``INSERT``, ``UPDATE``,
  427. ``DELETE`` and ``REPLACE``.) This bug has two consequences:
  429. - The low level APIs for savepoints are only usable inside a transaction ie.
  430.   inside an :func:`atomic` block.
  431. - It's impossible to use :func:`atomic` when autocommit is turned off.
  433. Transactions in MySQL
  434. ---------------------
  436. If you're using MySQL, your tables may or may not support transactions; it
  437. depends on your MySQL version and the table types you're using. (By
  438. "table types," we mean something like "InnoDB" or "MyISAM".) MySQL transaction
  439. peculiarities are outside the scope of this article, but the MySQL site has
  440. `information on MySQL transactions`_.
  442. If your MySQL setup does *not* support transactions, then Django will always
  443. function in autocommit mode: statements will be executed and committed as soon
  444. as they're called. If your MySQL setup *does* support transactions, Django
  445. will handle transactions as explained in this document.
  447. .. _information on MySQL transactions: http://dev.mysql.com/doc/refman/5.6/en/sql-syntax-transactions.html
  449. Handling exceptions within PostgreSQL transactions
  450. --------------------------------------------------
  452. .. note::
  454.     This section is relevant only if you're implementing your own transaction
  455.     management. This problem cannot occur in Django's default mode and
  456.     :func:`atomic` handles it automatically.
  458. Inside a transaction, when a call to a PostgreSQL cursor raises an exception
  459. (typically ``IntegrityError``), all subsequent SQL in the same transaction
  460. will fail with the error "current transaction is aborted, queries ignored
  461. until end of transaction block". Whilst simple use of ``save()`` is unlikely
  462. to raise an exception in PostgreSQL, there are more advanced usage patterns
  463. which might, such as saving objects with unique fields, saving using the
  464. force_insert/force_update flag, or invoking custom SQL.
  466. There are several ways to recover from this sort of error.
  468. Transaction rollback
  469. ~~~~~~~~~~~~~~~~~~~~
  471. The first option is to roll back the entire transaction. For example::
  473.     a.save() # Succeeds, but may be undone by transaction rollback
  474.     try:
  475.         b.save() # Could throw exception
  476.     except IntegrityError:
  477.         transaction.rollback()
  478.     c.save() # Succeeds, but a.save() may have been undone
  480. Calling ``transaction.rollback()`` rolls back the entire transaction. Any
  481. uncommitted database operations will be lost. In this example, the changes
  482. made by ``a.save()`` would be lost, even though that operation raised no error
  483. itself.
  485. Savepoint rollback
  486. ~~~~~~~~~~~~~~~~~~
  488. You can use :ref:`savepoints <topics-db-transactions-savepoints>` to control
  489. the extent of a rollback. Before performing a database operation that could
  490. fail, you can set or update the savepoint; that way, if the operation fails,
  491. you can roll back the single offending operation, rather than the entire
  492. transaction. For example::
  494.     a.save() # Succeeds, and never undone by savepoint rollback
  495.     sid = transaction.savepoint()
  496.     try:
  497.         b.save() # Could throw exception
  498.         transaction.savepoint_commit(sid)
  499.     except IntegrityError:
  500.         transaction.savepoint_rollback(sid)
  501.     c.save() # Succeeds, and a.save() is never undone
  503. In this example, ``a.save()`` will not be undone in the case where
  504. ``b.save()`` raises an ex

Paste-bin is for source code and general debugging text.

Login or Register to edit, delete and keep track of your pastes and more.

Raw Paste

Login or Register to edit or fork this paste. It's free.