Transactions
atomic() blocks, on_commit callbacks and the active transactions of a context, in adorm.executor. atomic, Atomic, on_commit and TransactionOutcome are also importable from adorm. See the transactions topic.
from adorm import atomic, Atomic, on_commit, TransactionOutcome
from adorm.executor import active_transaction, bind_transaction, debug_enabled, set_debug, TransactionAtomic blocks
adorm.atomic()
An Atomic block on the current session (current_session() when atomic() is called). Session.atomic() returns one on a given session.
async with adorm.atomic() as tx:
await Member.objects.filter(pk=1).update(active=False)
@adorm.atomic()
async def deactivate(pk: int) -> None:
await Member.objects.filter(pk=pk).update(active=False)As a decorator it runs every call in a new block on the session current at that call.
adorm.Atomic
A transaction block on one session, used with async with. Atomic(session) takes a Session (TypeError otherwise); atomic() and Session.atomic() create it. A block is entered once; entering it again raises TransactionManagementError.
Decorating (__call__(func)): func is a coroutine function (TypeError otherwise). Every call of the returned function runs func in a new Atomic block: on the session current at the call when the block came from adorm.atomic(), else on the block's session. The decorating block itself is never entered.
Entering (__aenter__, returns the block itself):
- When the session has no active transaction in the context, the block acquires a slot through the runner's
slot(session)(Router.slot()) and sendsbeginwith the database connection options in effect; the slot sets them (SET,RESET) before theBEGIN.- The acquisition raises
SessionTimeoutorDeadlockErrorafter theacquire_timeoutconnection option in effect. - The lease's
commit_timeoutis thecommit_timeoutoption in effect at entry. - A runner that is not a
TransactionRunner, or no runner, raisesInterfaceError. - When
beginfails or is cancelled, the slot is discarded and the error propagates.
- The acquisition raises
- When the active transaction of the session is an
Atomic, the block is a savepoint of it, on the same slot.- It waits until a savepoint another task opened in the same enclosing block ends; after the
acquire_timeoutconnection option in effect the wait raisesDeadlockErrorwith the session inheld_sessions. - An enclosing block that has ended raises
TransactionClosed; one with a failed operation raisesTransactionManagementError. - A driver without savepoints raises
NotSupportedError.
- It waits until a savepoint another task opened in the same enclosing block ends; after the
- Any other active transaction (
bind_transaction()) raisesTransactionManagementError.
The entered block is the session's active transaction for the context of the async with statement and of tasks created inside it.
Exiting (__aexit__), in order:
- closes the block to further operations and new savepoints;
- closes savepoint blocks of other tasks still open inside it;
- waits for the operations already sent;
- rolls back to the outermost savepoint it closed, when it would commit or release;
- ends the block:
| Exit | Transaction | Savepoint |
|---|---|---|
| normal | commit | release_savepoint |
| with an exception | rollback | rollback_to_savepoint, then release_savepoint |
| normal, after a failed operation | rollback, then raises TransactionManagementError from the failure | rollback_to_savepoint, release_savepoint, then raises TransactionManagementError |
| after the slot aborted the transaction | nothing; a normal exit raises TransactionClosed | the requests raise TransactionClosed: a normal exit raises it and marks the enclosing block as failed, an exit with an exception logs it |
after commit() or rollback() | nothing | nothing |
while commit() or rollback() of another task runs | waits for it; a normal exit raises its error | waits for it; a normal exit raises its error |
| normal, after the enclosing block closed it | raises TransactionClosed |
- The
commitcarries the database connection options in effect where the block ends; the slot sets them (SET LOCAL) before theCOMMIT. With an option the driver does not declare, the transaction rolls back instead and the exit raisesTransactionManagementErrorfrom theNotSupportedError. - A failing
commitorrelease_savepointpropagates. - A failing rollback on an exit with an exception is logged and the block's exception propagates.
- A failing rollback to a savepoint closed by the end is logged and the block rolls back to its own savepoint, as after a failed operation.
- A transaction block returns its slot to the pool at the end; a slot whose commit or rollback did not succeed leaves the pool.
- A savepoint whose end failed or was cancelled, or whose rollback failed with any error, marks the enclosing block as failed: its further operations raise
TransactionManagementErrorand it rolls back.
| Member | Meaning |
|---|---|
session | the Session |
parent | the enclosing Atomic of a savepoint, None for a transaction |
root | the outermost block of the transaction |
savepoint | the savepoint name, None for a transaction |
lease | the SlotLease of the transaction's slot, None before entry |
closed | whether the block no longer takes operations: it is ending or has ended |
outcome | the TransactionOutcome of the transaction; for a savepoint ROLLED_BACK when it or a savepoint around it was rolled back, else the outermost block's; None while the transaction is open and for a block that never began; final once the end of the block has returned or raised |
- When the end of the block is cancelled during the commit, it raises
CancelledErroronce the slot has finished a sent commit;outcometells whether it committed. After a confirmed commit theon_commit()callbacks run in a task of their own, which logs an exception a callback raises on theadorm.executorlogger. - When another task's
commit()ended the block and was cancelled before the commit was confirmed, the end of the owner'sasync withraisesTransactionManagementErrorwith thatCancelledErroras__cause__.
See cancellation.
block = adorm.atomic()
try:
async with block:
await Member.objects.filter(pk=1).update(active=False)
except asyncio.CancelledError:
if block.outcome is TransactionOutcome.UNKNOWN:
... # the update may or may not be committed
raiseasync execute(operation)
Runs operation on the transaction's slot and returns its result, with the database connection options in effect (resolve_options()), which the slot sets with SET LOCAL. Operations of a session's bound models reach the block through Session.execute().
- An option the driver does not declare raises
NotSupportedErrorbefore anything is sent. - While a savepoint block of another task is open directly inside this block, it first waits until that savepoint ends; after the
acquire_timeoutconnection option in effect it raisesDeadlockError. - Raises
TransactionClosedonce the block (or an enclosing block) is closed or the slot aborted the transaction, andTransactionManagementErrorafter an operation of the block failed. - An operation that fails with a
DatabaseErrororInterfaceError, or is cancelled after it reached the slot's connection, marks the block as failed. ANotSupportedErrorwithoutsqlstateandoriginal(a client-side capability check) and a cancellation of a queued operation do not. - A cancellation while the operation waits for a savepoint carries
CancellationOutcome.NOT_STARTED; a cancellation after the request was sent carries the outcomeSlotLease.call()gives it. - Enclosing
adorm.timeout()blocks see the operation as"waiting_for_slot"while it waits for the savepoint, then"executing", and the block's own requests by name ("begin","savepoint","commit","rollback"…).
async commit()
Ends the block as a normal exit does: commits (releases the savepoint) after the operations already sent. Raises TransactionClosed when the block is not open, and TransactionManagementError after a failed operation (once it has rolled back).
async with adorm.atomic() as tx:
await Member.objects.create(name="Ana")
await tx.commit()async rollback()
Ends the block as an exit with an exception does: rolls back (to the savepoint). Raises TransactionClosed when the block is not open. A failing rollback propagates; after a failed operation of the block it is logged instead.
async with adorm.atomic() as tx:
invoice = await Invoice.objects.create(member_id=member.id, total=total)
if not await charge(invoice):
await tx.rollback() # the invoice is not kept; the block ends hereon_commit(func, *, robust=False)
Registers func to run after the transaction commits; a synchronous method. func() is called without arguments; an awaitable it returns is awaited.
- The callbacks run after the commit succeeded and the slot is back in the pool, in registration order, in a copy of the block's context without this session's transaction; an operation in a callback takes a slot of its own. The block runs them when the slot delivers
CallbackEvent(ON_COMMIT)for itscommitrequest. - A savepoint passes its callbacks to the enclosing block when it is released and drops them when it rolls back or the enclosing block closes it.
- A rollback, an exit with an exception, a failed operation and an abort by the slot drop the callbacks. So does a commit cancelled before the slot confirmed it. After a confirmed commit whose end was cancelled, the callbacks run in a task of their own, which logs an exception a callback raises on the
adorm.executorlogger. - A callback that raises stops the remaining ones; the exception propagates from the end of the outermost block, or from
commit(), after the commit. It does not reach other tasks waiting for that end. Withrobust=Truethe exception is logged on theadorm.executorlogger and the next callback runs. - Cancelling the task that ends the block while a callback runs cancels the callback.
A func that is not callable raises TypeError; a block that is not open raises TransactionClosed.
async with adorm.atomic() as tx:
member = await Member.objects.create(name="Ana")
tx.on_commit(lambda: mailer.send_welcome(member.pk))adorm.on_commit(func, *, robust=False, session=None)
A coroutine function: registers func with Atomic.on_commit() on the active transaction of session (default: current_session()) in the current context, the innermost savepoint when one is open. Without an active transaction it calls func() now and awaits the result; robust=True then logs an exception instead of raising it. An active transaction that is not an Atomic raises TransactionManagementError; a func that is not callable raises TypeError.
async def close_account(member_id):
await Member.objects.filter(pk=member_id).update(active=False)
await adorm.on_commit(lambda: billing.cancel_subscription(member_id)) # after COMMIT, or now outside oneadorm.TransactionOutcome
A StrEnum of how a transaction ended in the database, the value of Atomic.outcome.
| Member | Value | When |
|---|---|---|
COMMITTED | "committed" | the slot delivered CallbackEvent("on_commit"): the commit succeeded, also when the end of the block was cancelled while it ran |
ROLLED_BACK | "rolled_back" | the block rolled back, the slot aborted the transaction, the commit failed with an error other than a lost connection, or the end was cancelled before the commit reached the driver connection |
UNKNOWN | "unknown" | the commit was cancelled after it reached the slot, or failed with a lost connection (is_connection_error()): the transaction may have committed |
tx = adorm.atomic()
try:
async with tx:
await payment.save()
finally:
if tx.outcome is adorm.TransactionOutcome.UNKNOWN:
log.warning("payment %s may have been committed", payment.pk)Transactions in the context
adorm.executor.Transaction
The protocol of an object that runs a session's operations inside a transaction: await transaction.execute(operation). Atomic implements it.
adorm.executor.active_transaction(session)
The transaction bound to session in the current context, None when there is none.
async with reports.atomic() as tx:
assert active_transaction(reports) is txadorm.executor.bind_transaction(session, transaction)
A synchronous context manager that makes transaction the active transaction of session for its block and yields it. The binding is a context variable; tasks created inside the block inherit it, also after the block ends. A binding for the same session inside the block replaces it until the inner block ends; other sessions' bindings are unaffected. An object without an async execute(operation) raises TypeError.
with bind_transaction(reports, transaction):
assert active_transaction(reports) is transaction
await reports.Member.filter(pk=1).update(fee=0) # transaction.execute(...)
assert active_transaction(reports) is NoneWarnings
In debug mode (debug_enabled()), the end of a block issues a RuntimeWarning naming the tasks that ran operations in it, or in its savepoints, and are still running.
Debug mode
The executor's debug checks run when its debug switch is on. The switch is set by:
adorm.configure(debug=...);- the
debugkey of theADORMDjango setting, which the Django app passes toadorm.configure()ondjango.setup()and when a test overridesADORM, orDATABASESwhileADORMhas noprofiles; set_debug().
True turns the checks on and False off. None makes them follow the running event loop's debug mode (asyncio.run(..., debug=True), loop.set_debug(True) or PYTHONASYNCIODEBUG=1); it is the value before the switch is set. Every adorm.configure() call that does not raise sets the switch, to None when debug is not given; a call that raises leaves it unchanged. The value set last applies.
adorm.executor.set_debug(value)
Turns the executor's debug checks on (True) or off (False); None makes them follow the running event loop's debug mode. Returns the previous value. Anything else raises TypeError.
from adorm.executor import set_debug
set_debug(True)adorm.executor.debug_enabled()
Whether the executor's debug checks run: the debug switch when it is True or False, or else loop.get_debug() of the running event loop (False outside one).