Sessions and bound models
A session names where operations run: the pair (using, session_name). using is the name of a connection profile, like a Django database alias; session_name separates independent flows on the same profile. A model bound to a session (a bound model) builds query sets whose operations run on that session.
An operation outside a transaction runs on the runner set with set_runner(), such as the router of the slot pools. With connection profiles configured and no runner set, it runs on the event loop's default router (connection profiles).
import adorm
from club.models import Member
reports = adorm.create_session(using="reports", session_name="nightly")
await Member.objects.filter(active=True).count() # the current session
await reports.Member.filter(active=True).count() # the "reports" sessionCreating sessions
create_session() returns the open session with the given pair, or creates it. A process has one Session object per pair, so sessions compare by identity:
a = adorm.create_session("reports", "nightly")
b = adorm.create_session(using="reports", session_name="nightly")
assert a is b
adorm.create_session() # ("default", "default")A session holds no slot and no connection; creating one does no I/O.
The current session
A context variable holds the current session; the default is ("default", "default"). session.activate() makes a session current for a synchronous with block; it only sets the context variable:
adorm.current_session() # Session('default', 'default')
with reports.activate():
adorm.current_session() # Session('reports', 'nightly')
await Member.objects.count() # runs on "reports"
adorm.current_session() # Session('default', 'default')Tasks inherit the context they are created in (asyncio.create_task(), TaskGroup, gather()) and with it the current session, also after the block that set it has ended. A session activated inside a task does not change the session of its parent.
with reports.activate():
task = asyncio.create_task(Member.objects.count()) # runs on "reports"
await taskSessions on several profiles
A session's using selects the connection profile, and with it the driver and the pool, of every operation in it. The same query code runs on another profile when another session is current, for example one a request selects:
async def member(pk: int, using: str) -> Member:
with adorm.create_session(using, "api").activate():
return await Member.objects.get(pk=pk)
await member(3, "django") # a slot of the "django" profile's pool
await member(3, "asyncpg") # a slot of the "asyncpg" profile's poolTasks that activate different sessions run concurrently on their profiles' pools; each task keeps its own session:
async def page(using: str) -> list[Member]:
with adorm.create_session(using, "compare").activate():
return [member async for member in Member.objects.order_by("last_name")[:20]]
async with asyncio.TaskGroup() as group:
on_django = group.create_task(page("django"))
on_asyncpg = group.create_task(page("asyncpg"))
assert [m.model_dump() for m in on_django.result()] == [m.model_dump() for m in on_asyncpg.result()]Each profile has its own pool; a full pool of one profile does not delay operations on another. The demo runs every example on a profile per driver.
Bound models
Model.objects returns a BoundModel: the model bound to the session that is current when objects is read. session.Member (the class name of a registered model) and session.bind(Member) bind to the given session. bind() also takes a model label, which is required when two registered models share a class name.
Member.objects # <BoundModel club.Member on Session('default', 'default')>
reports.Member # <BoundModel club.Member on Session('reports', 'nightly')>
reports.bind("club.Member") # the same
reports.Member.objects # the bound model itself, for Django-like spelling
reports.Loan.all_loans # another manager of the model, on the same session
reports.bind(Loan, "all_loans") # the sameBinding takes no slot. The binding is fixed when objects is read: a bound model stored at module level stays bound to the session current at import.
# club/queries.py
members = Member.objects # bound to the session current at import
# elsewhere
with reports.activate():
await members.count() # still runs on the import-time session
await Member.objects.count() # runs on "reports"Query sets
A bound model's query methods return a QuerySet: a Query together with the session that runs it. Building a query set does no I/O; each terminal coroutine runs one operation.
active = Member.objects.filter(active=True).order_by("name")
members = [m async for m in active[:20]] # Select
ana = await active.get(name="Ana") # Get
count = await active.count() # Count
await active.filter(fee__lt=5).update(fee=5) # Update
new = await Member.objects.create(name="Bea") # CreateInstances a query set returns run their operations (save(), relation loads) on the same session. An instance the application creates without a query set uses the current session.
Transactions are looked up when an operation runs
A transaction is not part of a binding. When an operation runs, the session looks up its active transaction in the current context. With one bound, the operation runs in it; otherwise the runner acquires a slot for that operation alone. The same bound model runs inside or outside a transaction depending on where it is awaited.
An atomic() block binds its transaction to its session for the block:
from adorm.executor import active_transaction
members = reports.Member # bound outside any transaction
async with reports.atomic() as tx:
active_transaction(reports) # tx
await members.filter(pk=1).update(fee=0) # tx.execute(Update(...))
await members.count() # runner.run(reports, Count(...))bind_transaction() binds any object with an async execute(operation) the same way.
- A transaction of one session does not affect another session, also on the same profile.
- Tasks created inside the block inherit its transaction with the context, also after the block ends. The transaction handles an operation arriving then (an
atomic()block raisesTransactionClosed). - An operation's target is chosen when it starts. An operation running when the block ends stays in the transaction; an
atomic()block waits for it before it commits.
Events
Sessions and bound models emit and consume no events; operation results reach the session through the runner or the transaction that executes them.