sqlalchemy.ext.asyncio.session.AsyncSession

Undocumented

Undocumented

Construct a new _asyncio.AsyncSession.

All parameters other than sync_session_class are passed to the sync_session_class callable directly to instantiate a new _orm.Session. Refer to _orm.Session.__init__ for parameter documentation.

Undocumented

Return an _asyncio.AsyncSessionTransaction object.

The underlying _orm.Session will perform the "begin" action when the _asyncio.AsyncSessionTransaction object is entered:

async with async_session.begin():
    # .. ORM transaction is begun

Note that database IO will not normally occur when the session-level transaction is begun, as database transactions begin on an on-demand basis. However, the begin block is async to accommodate for a _orm.SessionEvents.after_transaction_create event hook that may perform IO.

For a general description of ORM begin, see _orm.Session.begin.

Return an _asyncio.AsyncSessionTransaction object which will begin a "nested" transaction, e.g. SAVEPOINT.

Behavior is the same as that of _asyncio.AsyncSession.begin.

For a general description of ORM begin nested, see _orm.Session.begin_nested.

Close out the transactional resources and ORM objects used by this _asyncio.AsyncSession.

This expunges all ORM objects associated with this _asyncio.AsyncSession, ends any transaction in progress and :term:`releases` any _asyncio.AsyncConnection objects which this _asyncio.AsyncSession itself has checked out from associated _asyncio.AsyncEngine objects. The operation then leaves the _asyncio.AsyncSession in a state which it may be used again.

Return a _asyncio.AsyncConnection object corresponding to this .Session object's transactional state.

This method may also be used to establish execution options for the database connection used by the current transaction.

Mark an instance as deleted.

The database delete operation occurs upon flush().

As this operation may need to cascade along unloaded relationships, it is awaitable to allow for those queries to take place.

Execute a statement and return a buffered _engine.Result object.

Flush all the object changes to the database.

Return an instance based on the given primary key identifier, or None if not found.

Return a "bind" to which the synchronous proxied _orm.Session is bound.

Unlike the _orm.Session.get_bind method, this method is currently not used by this .AsyncSession in any way in order to resolve engines for requests.

The pattern introduced at :ref:`session_custom_partitioning` illustrates how to apply a custom bind-lookup scheme to a _orm.Session given a set of _engine.Engine objects. To apply a corresponding _orm.Session.get_bind implementation for use with a .AsyncSession and .AsyncEngine objects, continue to subclass _orm.Session and apply it to .AsyncSession using :paramref:`.AsyncSession.sync_session_class`. The inner method must continue to return _engine.Engine instances, which can be acquired from a _asyncio.AsyncEngine using the _asyncio.AsyncEngine.sync_engine attribute:

# using example from "Custom Vertical Partitioning"


import random

from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.orm import Session, sessionmaker

# construct async engines w/ async drivers
engines = {
    'leader':create_async_engine("sqlite+aiosqlite:///leader.db"),
    'other':create_async_engine("sqlite+aiosqlite:///other.db"),
    'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"),
    'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"),
}

class RoutingSession(Session):
    def get_bind(self, mapper=None, clause=None, **kw):
        # within get_bind(), return sync engines
        if mapper and issubclass(mapper.class_, MyOtherClass):
            return engines['other'].sync_engine
        elif self._flushing or isinstance(clause, (Update, Delete)):
            return engines['leader'].sync_engine
        else:
            return engines[
                random.choice(['follower1','follower2'])
            ].sync_engine

# apply to AsyncSession using sync_session_class
AsyncSessionMaker = sessionmaker(
    class_=AsyncSession,
    sync_session_class=RoutingSession
)

The _orm.Session.get_bind method is called in a non-asyncio, implicitly non-blocking context in the same manner as ORM event hooks and functions that are invoked via .AsyncSession.run_sync, so routines that wish to run SQL commands inside of _orm.Session.get_bind can continue to do so using blocking-style code, which will be translated to implicitly async calls at the point of invoking IO on the database drivers.

Return the current nested transaction in progress, if any.

Return the current root transaction in progress, if any.

Close this Session, using connection invalidation.

For a complete description, see _orm.Session.invalidate.

Copy the state of a given instance into a corresponding instance within this _asyncio.AsyncSession.

Expire and refresh the attributes on the given instance.

A query will be issued to the database and all attributes will be refreshed with their current database value.

This is the async version of the _orm.Session.refresh method. See that method for a complete description of all options.

Invoke the given sync callable passing sync self as the first argument.

This method maintains the asyncio event loop all the way through to the database connection by running the given callable in a specially instrumented greenlet.

E.g.:

with AsyncSession(async_engine) as session:
    await session.run_sync(some_business_method)

Execute a statement and return a scalar result.

Execute a statement and return scalar results.

Execute a statement and return a stream of scalar results.