SQLAlchemy 2.0 Documentation - 私家版日本語訳ドキュメント

Connection.execution_options()

method sqlalchemy.ext.asyncio.AsyncEngine.update_execution_options(**opt: Any) → None¶

Update the default execution_options dictionary of this Engine.

Proxied for the Engine class on behalf of the AsyncEngine class.

The given keys/values in **opt are added to the default execution options that will be used for all connections. The initial contents of this dictionary can be sent via the execution_options parameter to create_engine().

See also

Engine.execution_options()

attribute sqlalchemy.ext.asyncio.AsyncEngine.url¶: Proxy for the Engine.url attribute on behalf of the AsyncEngine class.

class sqlalchemy.ext.asyncio.AsyncConnection¶

An asyncio proxy for a Connection.

AsyncConnection is acquired using the AsyncEngine.connect() method of AsyncEngine:

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")

async with engine.connect() as conn:
    result = await conn.execute(select(table))

New in version 1.4.

Class signature

class sqlalchemy.ext.asyncio.AsyncConnection (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.base.StartableContext, sqlalchemy.ext.asyncio.AsyncConnectable)

method sqlalchemy.ext.asyncio.AsyncConnection.async aclose() → None¶

A synonym for AsyncConnection.close().

The AsyncConnection.aclose() name is specifically to support the Python standard library @contextlib.aclosing context manager function.

New in version 2.0.20.

method sqlalchemy.ext.asyncio.AsyncConnection.begin() → AsyncTransaction¶: Begin a transaction prior to autobegin occurring.

method sqlalchemy.ext.asyncio.AsyncConnection.begin_nested() → AsyncTransaction¶: Begin a nested transaction and return a transaction handle.

method sqlalchemy.ext.asyncio.AsyncConnection.async close() → None¶

Close this AsyncConnection.

This has the effect of also rolling back the transaction if one is in place.

attribute sqlalchemy.ext.asyncio.AsyncConnection.closed¶: Return True if this connection is closed.

Proxied for the Connection class on behalf of the AsyncConnection class.

method sqlalchemy.ext.asyncio.AsyncConnection.async commit() → None¶

Commit the transaction that is currently in progress.

This method commits the current transaction if one has been started. If no transaction was started, the method has no effect, assuming the connection is in a non-invalidated state.

A transaction is begun on a Connection automatically whenever a statement is first executed, or when the Connection.begin() method is called.

attribute sqlalchemy.ext.asyncio.AsyncConnection.connection¶: Not implemented for async; call AsyncConnection.get_raw_connection().

attribute sqlalchemy.ext.asyncio.AsyncConnection.default_isolation_level¶

The initial-connection time isolation level associated with the Dialect in use.

Proxied for the Connection class on behalf of the AsyncConnection class.

This value is independent of the Connection.execution_options.isolation_level and Engine.execution_options.isolation_level execution options, and is determined by the Dialect when the first connection is created, by performing a SQL query against the database for the current isolation level before any additional commands have been emitted.

Calling this accessor does not invoke any new SQL queries.

See also

Connection.get_isolation_level() - view current actual isolation level

create_engine.isolation_level - set per Engine isolation level

Connection.execution_options.isolation_level - set per Connection isolation level

attribute sqlalchemy.ext.asyncio.AsyncConnection.dialect¶: Proxy for the Connection.dialect attribute on behalf of the AsyncConnection class.

method sqlalchemy.ext.asyncio.AsyncConnection.async exec_driver_sql(statement: str, parameters: _DBAPIAnyExecuteParams | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → CursorResult[Any]¶: Executes a driver-level SQL string and return buffered Result.

method sqlalchemy.ext.asyncio.AsyncConnection.async execute(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → CursorResult[Any]¶

Executes a SQL statement construct and return a buffered Result.

Parameters:

object¶ –
The statement to be executed. This is always an object that is in both the ClauseElement and Executable hierarchies, including:
- Select
- Insert, Update, Delete
- TextClause and TextualSelect
- DDL and objects which inherit from ExecutableDDLElement
parameters¶ – parameters which will be bound into the statement. This may be either a dictionary of parameter names to values, or a mutable sequence (e.g. a list) of dictionaries. When a list of dictionaries is passed, the underlying statement execution will make use of the DBAPI cursor.executemany() method. When a single dictionary is passed, the DBAPI cursor.execute() method will be used.
execution_options¶ – optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by Connection.execution_options().

Returns:

a Result object.

method sqlalchemy.ext.asyncio.AsyncConnection.async execution_options(**opt: Any) → AsyncConnection¶

Set non-SQL options for the connection which take effect during execution.

This returns this AsyncConnection object with the new options added.

See Connection.execution_options() for full details on this method.

method sqlalchemy.ext.asyncio.AsyncConnection.get_nested_transaction() → AsyncTransaction | None¶

Return an AsyncTransaction representing the current nested (savepoint) transaction, if any.

This makes use of the underlying synchronous connection’s Connection.get_nested_transaction() method to get the current Transaction, which is then proxied in a new AsyncTransaction object.

New in version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.async get_raw_connection() → PoolProxiedConnection¶

Return the pooled DBAPI-level connection in use by this AsyncConnection.

This is a SQLAlchemy connection-pool proxied connection which then has the attribute _ConnectionFairy.driver_connection that refers to the actual driver connection. Its _ConnectionFairy.dbapi_connection refers instead to an AdaptedConnection instance that adapts the driver connection to the DBAPI protocol.

method sqlalchemy.ext.asyncio.AsyncConnection.get_transaction() → AsyncTransaction | None¶

Return an AsyncTransaction representing the current transaction, if any.

This makes use of the underlying synchronous connection’s Connection.get_transaction() method to get the current Transaction, which is then proxied in a new AsyncTransaction object.

New in version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.in_nested_transaction() → bool¶: Return True if a transaction is in progress.

New in version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.in_transaction() → bool¶: Return True if a transaction is in progress.

attribute sqlalchemy.ext.asyncio.AsyncConnection.info¶

Return the Connection.info dictionary of the underlying Connection.

This dictionary is freely writable for user-defined state to be associated with the database connection.

This attribute is only available if the AsyncConnection is currently connected. If the AsyncConnection.closed attribute is True, then accessing this attribute will raise ResourceClosedError.

New in version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.async invalidate(exception: BaseException | None = None) → None¶

Invalidate the underlying DBAPI connection associated with this Connection.

See the method Connection.invalidate() for full detail on this method.

attribute sqlalchemy.ext.asyncio.AsyncConnection.invalidated¶

Return True if this connection was invalidated.

Proxied for the Connection class on behalf of the AsyncConnection class.

This does not indicate whether or not the connection was invalidated at the pool level, however

method sqlalchemy.ext.asyncio.AsyncConnection.async rollback() → None¶

Roll back the transaction that is currently in progress.

This method rolls back the current transaction if one has been started. If no transaction was started, the method has no effect. If a transaction was started and the connection is in an invalidated state, the transaction is cleared using this method.

A transaction is begun on a Connection automatically whenever a statement is first executed, or when the Connection.begin() method is called.

method sqlalchemy.ext.asyncio.AsyncConnection.async run_sync(fn: ~typing.Callable[[~typing.Concatenate[~sqlalchemy.engine.base.Connection, ~_P]], ~sqlalchemy.ext.asyncio.engine._T], *arg: ~typing.~_P, **kw: ~typing.~_P) → _T¶

Invoke the given synchronous (i.e. not async) callable, passing a synchronous-style Connection as the first argument.

This method allows traditional synchronous SQLAlchemy functions to run within the context of an asyncio application.

E.g.:

def do_something_with_core(conn: Connection, arg1: int, arg2: str) -> str:
    '''A synchronous function that does not require awaiting

    :param conn: a Core SQLAlchemy Connection, used synchronously

    :return: an optional return value is supported

    '''
    conn.execute(
        some_table.insert().values(int_col=arg1, str_col=arg2)
    )
    return "success"


async def do_something_async(async_engine: AsyncEngine) -> None:
    '''an async function that uses awaiting'''

    async with async_engine.begin() as async_conn:
        # run do_something_with_core() with a sync-style
        # Connection, proxied into an awaitable
        return_code = await async_conn.run_sync(do_something_with_core, 5, "strval")
        print(return_code)

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.

The most rudimentary use of AsyncConnection.run_sync() is to invoke methods such as MetaData.create_all(), given an AsyncConnection that needs to be provided to MetaData.create_all() as a Connection object:

# run metadata.create_all(conn) with a sync-style Connection,
# proxied into an awaitable
with async_engine.begin() as conn:
    await conn.run_sync(metadata.create_all)

Note

The provided callable is invoked inline within the asyncio event loop, and will block on traditional IO calls. IO within this callable should only call into SQLAlchemy’s asyncio database APIs which will be properly adapted to the greenlet context.

See also

AsyncSession.run_sync()

Running Synchronous Methods and Functions under asyncio

method sqlalchemy.ext.asyncio.AsyncConnection.async scalar(statement: Executable, parameters: _CoreSingleExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → Any¶

Executes a SQL statement construct and returns a scalar object.

This method is shorthand for invoking the Result.scalar() method after invoking the Connection.execute() method. Parameters are equivalent.

Returns:: a scalar Python value representing the first column of the first row returned.

method sqlalchemy.ext.asyncio.AsyncConnection.async scalars(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → ScalarResult[Any]¶

Executes a SQL statement construct and returns a scalar objects.

This method is shorthand for invoking the Result.scalars() method after invoking the Connection.execute() method. Parameters are equivalent.

Returns:: a ScalarResult object.

New in version 1.4.24.

method sqlalchemy.ext.asyncio.AsyncConnection.async start(is_ctxmanager: bool = False) → AsyncConnection¶: Start this AsyncConnection object’s context outside of using a Python with: block.

method sqlalchemy.ext.asyncio.AsyncConnection.stream(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → AsyncIterator[AsyncResult[Any]]¶

Execute a statement and return an awaitable yielding a AsyncResult object.

E.g.:

result = await conn.stream(stmt):
async for row in result:
    print(f"{row}")

The AsyncConnection.stream() method supports optional context manager use against the AsyncResult object, as in:

async with conn.stream(stmt) as result:
    async for row in result:
        print(f"{row}")

In the above pattern, the AsyncResult.close() method is invoked unconditionally, even if the iterator is interrupted by an exception throw. Context manager use remains optional, however, and the function may be called in either an async with fn(): or await fn() style.

New in version 2.0.0b3: added context manager support

Returns:: an awaitable object that will yield an AsyncResult object.

See also

AsyncConnection.stream_scalars()

method sqlalchemy.ext.asyncio.AsyncConnection.stream_scalars(statement: Executable, parameters: _CoreSingleExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → AsyncIterator[AsyncScalarResult[Any]]¶

Execute a statement and return an awaitable yielding a AsyncScalarResult object.

E.g.:

result = await conn.stream_scalars(stmt)
async for scalar in result:
    print(f"{scalar}")

This method is shorthand for invoking the AsyncResult.scalars() method after invoking the Connection.stream() method. Parameters are equivalent.

The AsyncConnection.stream_scalars() method supports optional context manager use against the AsyncScalarResult object, as in:

async with conn.stream_scalars(stmt) as result:
    async for scalar in result:
        print(f"{scalar}")

In the above pattern, the AsyncScalarResult.close() method is invoked unconditionally, even if the iterator is interrupted by an exception throw. Context manager use remains optional, however, and the function may be called in either an async with fn(): or await fn() style.

New in version 2.0.0b3: added context manager support

Returns:: an awaitable object that will yield an AsyncScalarResult object.

New in version 1.4.24.

See also

AsyncConnection.stream()

attribute sqlalchemy.ext.asyncio.AsyncConnection.sync_connection: Connection | None¶

Reference to the sync-style Connection this AsyncConnection proxies requests towards.

This instance can be used as an event target.

See also

attribute sqlalchemy.ext.asyncio.AsyncConnection.sync_engine: Engine¶

Reference to the sync-style Engine this AsyncConnection is associated with via its underlying Connection.

This instance can be used as an event target.

See also

AsyncResult.partitions()

class sqlalchemy.ext.asyncio.AsyncTransaction¶

An asyncio proxy for a Transaction.

Members

close(), commit(), rollback(), start()

Class signature

class sqlalchemy.ext.asyncio.AsyncTransaction (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.base.StartableContext)

method sqlalchemy.ext.asyncio.AsyncTransaction.async close() → None¶

Close this AsyncTransaction.

If this transaction is the base transaction in a begin/commit nesting, the transaction will rollback(). Otherwise, the method returns.

This is used to cancel a Transaction without affecting the scope of an enclosing transaction.

method sqlalchemy.ext.asyncio.AsyncTransaction.async commit() → None¶: Commit this AsyncTransaction.

method sqlalchemy.ext.asyncio.AsyncTransaction.async rollback() → None¶: Roll back this AsyncTransaction.

method sqlalchemy.ext.asyncio.AsyncTransaction.async start(is_ctxmanager: bool = False) → AsyncTransaction¶: Start this AsyncTransaction object’s context outside of using a Python with: block.

Result Set API Documentation¶

AsyncResult オブジェクトは Result オブジェクトの非同期版です。 AsyncConnection.stream() または AsyncSession.stream() メソッドを使用した場合にのみ返されます。これらのメソッドは、アクティブなデータベースカーソルの上にある結果オブジェクトを返します。

Object Name	Description
AsyncMappingResult	A wrapper for a `AsyncResult` that returns dictionary values rather than `Row` values.
AsyncResult	An asyncio wrapper around a `Result` object.
AsyncScalarResult	A wrapper for a `AsyncResult` that returns scalar values rather than `Row` values.
AsyncTupleResult	A `AsyncResult` that’s typed as returning plain Python tuples instead of rows.

class sqlalchemy.ext.asyncio.AsyncResult¶

An asyncio wrapper around a Result object.

The AsyncResult only applies to statement executions that use a server-side cursor. It is returned only from the AsyncConnection.stream() and AsyncSession.stream() methods.

Note

As is the case with Result, this object is used for ORM results returned by AsyncSession.execute(), which can yield instances of ORM mapped objects either individually or within tuple-like rows. Note that these result objects do not deduplicate instances or rows automatically as is the case with the legacy Query object. For in-Python de-duplication of instances or rows, use the AsyncResult.unique() modifier method.

New in version 1.4.

Members

all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), freeze(), keys(), mappings(), one(), one_or_none(), partitions(), scalar(), scalar_one(), scalar_one_or_none(), scalars(), t, tuples(), unique(), yield_per()

Class signature

class sqlalchemy.ext.asyncio.AsyncResult (sqlalchemy.engine._WithKeys, sqlalchemy.ext.asyncio.AsyncCommon)

method sqlalchemy.ext.asyncio.AsyncResult.async all() → Sequence[Row[_TP]]¶

Return all rows in a list.

Closes the result set after invocation. Subsequent invocations will return an empty list.

Returns:: a list of Row objects.

method sqlalchemy.ext.asyncio.AsyncResult.async close() → None¶: inherited from the AsyncCommon.close() method of AsyncCommon

Close this result.

attribute sqlalchemy.ext.asyncio.AsyncResult.closed¶: inherited from the AsyncCommon.closed attribute of AsyncCommon

proxies the .closed attribute of the underlying result object, if any, else raises AttributeError.

New in version 2.0.0b3.

method sqlalchemy.ext.asyncio.AsyncResult.columns(*col_expressions: _KeyIndexType) → Self¶

Establish the columns that should be returned in each row.

Refer to Result.columns() in the synchronous SQLAlchemy API for a complete behavioral description.

method sqlalchemy.ext.asyncio.AsyncResult.async fetchall() → Sequence[Row[_TP]]¶: A synonym for the AsyncResult.all() method.

New in version 2.0.

method sqlalchemy.ext.asyncio.AsyncResult.async fetchmany(size: int | None = None) → Sequence[Row[_TP]]¶

Fetch many rows.

When all rows are exhausted, returns an empty list.

This method is provided for backwards compatibility with SQLAlchemy 1.x.x.

To fetch rows in groups, use the AsyncResult.partitions() method.

Returns:: a list of Row objects.

See also

method sqlalchemy.ext.asyncio.AsyncResult.async fetchone() → Row[_TP] | None¶

Fetch one row.

When all rows are exhausted, returns None.

This method is provided for backwards compatibility with SQLAlchemy 1.x.x.

To fetch the first row of a result only, use the AsyncResult.first() method. To iterate through all rows, iterate the AsyncResult object directly.

Returns:: a Row object if no filters are applied, or None if no rows remain.

method sqlalchemy.ext.asyncio.AsyncResult.async first() → Row[_TP] | None¶

Fetch the first row or None if no row is present.

Closes the result set and discards remaining rows.

Note

This method returns one row, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the AsyncResult.scalar() method, or combine AsyncResult.scalars() and AsyncResult.first().

Additionally, in contrast to the behavior of the legacy ORM Query.first() method, no limit is applied to the SQL query which was invoked to produce this AsyncResult; for a DBAPI driver that buffers results in memory before yielding rows, all rows will be sent to the Python process and all but the first row will be discarded.

See also

ORM Query Unified with Core Select

Returns:: a Row object, or None if no rows remain.

See also

AsyncResult.scalar()

AsyncResult.one()

method sqlalchemy.ext.asyncio.AsyncResult.async freeze() → FrozenResult[_TP]¶

Return a callable object that will produce copies of this AsyncResult when invoked.

The callable object returned is an instance of FrozenResult.

This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method will consume the result fully. When the FrozenResult is retrieved from a cache, it can be called any number of times where it will produce a new Result object each time against its stored set of rows.

See also

Re-Executing Statements - example usage within the ORM to implement a result-set cache.

method sqlalchemy.ext.asyncio.AsyncResult.keys() → RMKeyView¶

inherited from the sqlalchemy.engine._WithKeys.keys method of sqlalchemy.engine._WithKeys

Return an iterable view which yields the string keys that would be represented by each Row.

The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm execution.

The view also can be tested for key containment using the Python in operator, which will test both for the string keys represented in the view, as well as for alternate keys such as column objects.

Changed in version 1.4: a key view object is returned rather than a plain list.

method sqlalchemy.ext.asyncio.AsyncResult.mappings() → AsyncMappingResult¶

Apply a mappings filter to returned rows, returning an instance of AsyncMappingResult.

When this filter is applied, fetching rows will return RowMapping objects instead of Row objects.

Returns:: a new AsyncMappingResult filtering object referring to the underlying Result object.

method sqlalchemy.ext.asyncio.AsyncResult.async one() → Row[_TP]¶

Return exactly one row or raise an exception.

Raises NoResultFound if the result returns no rows, or MultipleResultsFound if multiple rows would be returned.

Note

This method returns one row, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the AsyncResult.scalar_one() method, or combine AsyncResult.scalars() and AsyncResult.one().

New in version 1.4.

Returns:: The first Row.
Raises:: MultipleResultsFound, NoResultFound

See also

AsyncResult.first()

AsyncResult.one_or_none()

AsyncResult.scalar_one()

method sqlalchemy.ext.asyncio.AsyncResult.async one_or_none() → Row[_TP] | None¶

Return at most one result or raise an exception.

Returns None if the result has no rows. Raises MultipleResultsFound if multiple rows are returned.

New in version 1.4.

Returns:: The first Row or None if no row is available.
Raises:: MultipleResultsFound

See also

AsyncResult.first()

AsyncResult.one()

method sqlalchemy.ext.asyncio.AsyncResult.async partitions(size: int | None = None) → AsyncIterator[Sequence[Row[_TP]]]¶

Iterate through sub-lists of rows of the size given.

An async iterator is returned:

async def scroll_results(connection):
    result = await connection.stream(select(users_table))

    async for partition in result.partitions(100):
        print("list of rows: %s" % partition)

Refer to Result.partitions() in the synchronous SQLAlchemy API for a complete behavioral description.

method sqlalchemy.ext.asyncio.AsyncResult.async scalar() → Any¶

Fetch the first column of the first row, and close the result set.

Returns None if there are no rows to fetch.

No validation is performed to test if additional rows remain.

After calling this method, the object is fully closed, e.g. the CursorResult.close() method will have been called.

Returns:: a Python scalar value, or None if no rows remain.

method sqlalchemy.ext.asyncio.AsyncResult.async scalar_one() → Any¶

Return exactly one scalar result or raise an exception.

This is equivalent to calling AsyncResult.scalars() and then AsyncResult.one().

See also

AsyncResult.one()

AsyncResult.scalars()

method sqlalchemy.ext.asyncio.AsyncResult.async scalar_one_or_none() → Any | None¶

Return exactly one scalar result or None.

This is equivalent to calling AsyncResult.scalars() and then AsyncResult.one_or_none().

See also

AsyncResult.one_or_none()

AsyncResult.scalars()

method sqlalchemy.ext.asyncio.AsyncResult.scalars(index: _KeyIndexType = 0) → AsyncScalarResult[Any]¶

Return an AsyncScalarResult filtering object which will return single elements rather than Row objects.

Refer to Result.scalars() in the synchronous SQLAlchemy API for a complete behavioral description.

Parameters:: index¶ – integer or row key indicating the column to be fetched from each row, defaults to 0 indicating the first column.
Returns:: a new AsyncScalarResult filtering object referring to this AsyncResult object.

attribute sqlalchemy.ext.asyncio.AsyncResult.t¶

Apply a “typed tuple” typing filter to returned rows.

The AsyncResult.t attribute is a synonym for calling the AsyncResult.tuples() method.

New in version 2.0.

method sqlalchemy.ext.asyncio.AsyncResult.tuples() → AsyncTupleResult[_TP]¶

Apply a “typed tuple” typing filter to returned rows.

This method returns the same AsyncResult object at runtime, however annotates as returning a AsyncTupleResult object that will indicate to PEP 484 typing tools that plain typed Tuple instances are returned rather than rows. This allows tuple unpacking and __getitem__ access of Row objects to by typed, for those cases where the statement invoked itself included typing information.

New in version 2.0.

Returns:: the AsyncTupleResult type at typing time.

See also

AsyncResult.t - shorter synonym

Row.t - Row version

method sqlalchemy.ext.asyncio.AsyncResult.unique(strategy: _UniqueFilterType | None = None) → Self¶

Apply unique filtering to the objects returned by this AsyncResult.

Refer to Result.unique() in the synchronous SQLAlchemy API for a complete behavioral description.

method sqlalchemy.ext.asyncio.AsyncResult.yield_per(num: int) → Self¶

inherited from the FilterResult.yield_per() method of FilterResult

Configure the row-fetching strategy to fetch num rows at a time.

The FilterResult.yield_per() method is a pass through to the Result.yield_per() method. See that method’s documentation for usage notes.

New in version 1.4.40: - added FilterResult.yield_per() so that the method is available on all result set implementations

See also

Using Server Side Cursors (a.k.a. stream results) - describes Core behavior for Result.yield_per()

Fetching Large Result Sets with Yield Per - in the ORM Querying Guide

class sqlalchemy.ext.asyncio.AsyncScalarResult¶

A wrapper for a AsyncResult that returns scalar values rather than Row values.

The AsyncScalarResult object is acquired by calling the AsyncResult.scalars() method.

Refer to the ScalarResult object in the synchronous SQLAlchemy API for a complete behavioral description.

New in version 1.4.

Members

all(), close(), closed, fetchall(), fetchmany(), first(), one(), one_or_none(), partitions(), unique(), yield_per()

Class signature

class sqlalchemy.ext.asyncio.AsyncScalarResult (sqlalchemy.ext.asyncio.AsyncCommon)

method sqlalchemy.ext.asyncio.AsyncScalarResult.async all() → Sequence[_R]¶

Return all scalar values in a list.

Equivalent to AsyncResult.all() except that scalar values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async close() → None¶: inherited from the AsyncCommon.close() method of AsyncCommon

Close this result.

attribute sqlalchemy.ext.asyncio.AsyncScalarResult.closed¶: inherited from the AsyncCommon.closed attribute of AsyncCommon

proxies the .closed attribute of the underlying result object, if any, else raises AttributeError.

New in version 2.0.0b3.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async fetchall() → Sequence[_R]¶: A synonym for the AsyncScalarResult.all() method.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async fetchmany(size: int | None = None) → Sequence[_R]¶

Fetch many objects.

Equivalent to AsyncResult.fetchmany() except that scalar values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async first() → _R | None¶

Fetch the first object or None if no object is present.

Equivalent to AsyncResult.first() except that scalar values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async one() → _R¶

Return exactly one object or raise an exception.

Equivalent to AsyncResult.one() except that scalar values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async one_or_none() → _R | None¶

Return at most one object or raise an exception.

Equivalent to AsyncResult.one_or_none() except that scalar values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async partitions(size: int | None = None) → AsyncIterator[Sequence[_R]]¶

Iterate through sub-lists of elements of the size given.

Equivalent to AsyncResult.partitions() except that scalar values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncScalarResult.unique(strategy: _UniqueFilterType | None = None) → Self¶

Apply unique filtering to the objects returned by this AsyncScalarResult.

See AsyncResult.unique() for usage details.

method sqlalchemy.ext.asyncio.AsyncScalarResult.yield_per(num: int) → Self¶

inherited from the FilterResult.yield_per() method of FilterResult

Configure the row-fetching strategy to fetch num rows at a time.

The FilterResult.yield_per() method is a pass through to the Result.yield_per() method. See that method’s documentation for usage notes.

New in version 1.4.40: - added FilterResult.yield_per() so that the method is available on all result set implementations

See also

Using Server Side Cursors (a.k.a. stream results) - describes Core behavior for Result.yield_per()

Fetching Large Result Sets with Yield Per - in the ORM Querying Guide

class sqlalchemy.ext.asyncio.AsyncMappingResult¶

A wrapper for a AsyncResult that returns dictionary values rather than Row values.

The AsyncMappingResult object is acquired by calling the AsyncResult.mappings() method.

Refer to the MappingResult object in the synchronous SQLAlchemy API for a complete behavioral description.

New in version 1.4.

Members

all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), keys(), one(), one_or_none(), partitions(), unique(), yield_per()

Class signature

class sqlalchemy.ext.asyncio.AsyncMappingResult (sqlalchemy.engine._WithKeys, sqlalchemy.ext.asyncio.AsyncCommon)

method sqlalchemy.ext.asyncio.AsyncMappingResult.async all() → Sequence[RowMapping]¶

Return all rows in a list.

Equivalent to AsyncResult.all() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async close() → None¶: inherited from the AsyncCommon.close() method of AsyncCommon

Close this result.

attribute sqlalchemy.ext.asyncio.AsyncMappingResult.closed¶: inherited from the AsyncCommon.closed attribute of AsyncCommon

proxies the .closed attribute of the underlying result object, if any, else raises AttributeError.

New in version 2.0.0b3.

method sqlalchemy.ext.asyncio.AsyncMappingResult.columns(*col_expressions: _KeyIndexType) → Self¶: Establish the columns that should be returned in each row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchall() → Sequence[RowMapping]¶: A synonym for the AsyncMappingResult.all() method.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchmany(size: int | None = None) → Sequence[RowMapping]¶

Fetch many rows.

Equivalent to AsyncResult.fetchmany() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchone() → RowMapping | None¶

Fetch one object.

Equivalent to AsyncResult.fetchone() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async first() → RowMapping | None¶

Fetch the first object or None if no object is present.

Equivalent to AsyncResult.first() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.keys() → RMKeyView¶

inherited from the sqlalchemy.engine._WithKeys.keys method of sqlalchemy.engine._WithKeys

Return an iterable view which yields the string keys that would be represented by each Row.

The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm execution.

The view also can be tested for key containment using the Python in operator, which will test both for the string keys represented in the view, as well as for alternate keys such as column objects.

Changed in version 1.4: a key view object is returned rather than a plain list.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async one() → RowMapping¶

Return exactly one object or raise an exception.

Equivalent to AsyncResult.one() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async one_or_none() → RowMapping | None¶

Return at most one object or raise an exception.

Equivalent to AsyncResult.one_or_none() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async partitions(size: int | None = None) → AsyncIterator[Sequence[RowMapping]]¶

Iterate through sub-lists of elements of the size given.

Equivalent to AsyncResult.partitions() except that RowMapping values, rather than Row objects, are returned.

method sqlalchemy.ext.asyncio.AsyncMappingResult.unique(strategy: _UniqueFilterType | None = None) → Self¶

Apply unique filtering to the objects returned by this AsyncMappingResult.

See AsyncResult.unique() for usage details.

method sqlalchemy.ext.asyncio.AsyncMappingResult.yield_per(num: int) → Self¶

inherited from the FilterResult.yield_per() method of FilterResult

Configure the row-fetching strategy to fetch num rows at a time.

The FilterResult.yield_per() method is a pass through to the Result.yield_per() method. See that method’s documentation for usage notes.

New in version 1.4.40: - added FilterResult.yield_per() so that the method is available on all result set implementations

See also

Using Server Side Cursors (a.k.a. stream results) - describes Core behavior for Result.yield_per()

Fetching Large Result Sets with Yield Per - in the ORM Querying Guide

class sqlalchemy.ext.asyncio.AsyncTupleResult¶

A AsyncResult that’s typed as returning plain Python tuples instead of rows.

Since Row acts like a tuple in every way already, this class is a typing only class, regular AsyncResult is still used at runtime.

Class signature

class sqlalchemy.ext.asyncio.AsyncTupleResult (sqlalchemy.ext.asyncio.AsyncCommon, sqlalchemy.util.langhelpers.TypingOnly)

ORM Session API Documentation¶

Object Name	Description
async_object_session(instance)	Return the `AsyncSession` to which the given instance belongs.
async_scoped_session	Provides scoped management of `AsyncSession` objects.
async_session(session)	Return the `AsyncSession` which is proxying the given `Session` object, if any.
async_sessionmaker	A configurable `AsyncSession` factory.
AsyncAttrs	Mixin class which provides an awaitable accessor for all attributes.
AsyncSession	Asyncio version of `Session`.
AsyncSessionTransaction	A wrapper for the ORM `SessionTransaction` object.
close_all_sessions()	Close all `AsyncSession` sessions.

function sqlalchemy.ext.asyncio.async_object_session(instance: object) → AsyncSession | None¶

Return the AsyncSession to which the given instance belongs.

This function makes use of the sync-API function object_session to retrieve the Session which refers to the given instance, and from there links it to the original AsyncSession.

If the AsyncSession has been garbage collected, the return value is None.

This functionality is also available from the InstanceState.async_session accessor.

Parameters:: instance¶ – an ORM mapped instance
Returns:: an AsyncSession object, or None.

New in version 1.4.18.

function sqlalchemy.ext.asyncio.async_session(session: Session) → AsyncSession | None¶

Return the AsyncSession which is proxying the given Session object, if any.

Parameters:: session¶ – a Session instance.
Returns:: a AsyncSession instance, or None.

New in version 1.4.18.

function async sqlalchemy.ext.asyncio.close_all_sessions() → None¶: Close all AsyncSession sessions.

New in version 2.0.23.

See also

close_all_sessions()

class sqlalchemy.ext.asyncio.async_sessionmaker¶

A configurable AsyncSession factory.

The async_sessionmaker factory works in the same way as the sessionmaker factory, to generate new AsyncSession objects when called, creating them given the configurational arguments established here.

e.g.:

from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import async_sessionmaker

async def run_some_sql(async_session: async_sessionmaker[AsyncSession]) -> None:
    async with async_session() as session:
        session.add(SomeObject(data="object"))
        session.add(SomeOtherObject(name="other object"))
        await session.commit()

async def main() -> None:
    # an AsyncEngine, which the AsyncSession will use for connection
    # resources
    engine = create_async_engine('postgresql+asyncpg://scott:tiger@localhost/')

    # create a reusable factory for new AsyncSession instances
    async_session = async_sessionmaker(engine)

    await run_some_sql(async_session)

    await engine.dispose()

The async_sessionmaker is useful so that different parts of a program can create new AsyncSession objects with a fixed configuration established up front. Note that AsyncSession objects may also be instantiated directly when not using async_sessionmaker.

New in version 2.0: async_sessionmaker provides a sessionmaker class that’s dedicated to the AsyncSession object, including pep-484 typing support.

See also

Synopsis - ORM - shows example use

sessionmaker - general overview of the: sessionmaker architecture

Opening and Closing a Session - introductory text on creating sessions using sessionmaker.

Members

__call__(), __init__(), begin(), configure()

Class signature

class sqlalchemy.ext.asyncio.async_sessionmaker (typing.Generic)

method sqlalchemy.ext.asyncio.async_sessionmaker.__call__(**local_kw: Any) → _AS¶

Produce a new AsyncSession object using the configuration established in this async_sessionmaker.

In Python, the __call__ method is invoked on an object when it is “called” in the same way as a function:

AsyncSession = async_sessionmaker(async_engine, expire_on_commit=False)
session = AsyncSession()  # invokes sessionmaker.__call__()

method sqlalchemy.ext.asyncio.async_sessionmaker.__init__(bind: Optional[_AsyncSessionBind] = None, *, class_: Type[_AS] = <class 'sqlalchemy.ext.asyncio.session.AsyncSession'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)¶

Construct a new async_sessionmaker.

All arguments here except for class_ correspond to arguments accepted by Session directly. See the AsyncSession.__init__() docstring for more details on parameters.

method sqlalchemy.ext.asyncio.async_sessionmaker.begin() → _AsyncSessionContextManager[_AS]¶

Produce a context manager that both provides a new AsyncSession as well as a transaction that commits.

e.g.:

async def main():
    Session = async_sessionmaker(some_engine)

    async with Session.begin() as session:
        session.add(some_object)

    # commits transaction, closes session

method sqlalchemy.ext.asyncio.async_sessionmaker.configure(**new_kw: Any) → None¶

(Re)configure the arguments for this async_sessionmaker.

e.g.:

AsyncSession = async_sessionmaker(some_engine)

AsyncSession.configure(bind=create_async_engine('sqlite+aiosqlite://'))

class sqlalchemy.ext.asyncio.async_scoped_session¶

Provides scoped management of AsyncSession objects.

See the section Using asyncio scoped session for usage details.

New in version 1.4.19.

Class signature

class sqlalchemy.ext.asyncio.async_scoped_session (typing.Generic)

method sqlalchemy.ext.asyncio.async_scoped_session.__call__(**kw: Any) → _AS¶

Return the current AsyncSession, creating it using the scoped_session.session_factory if not present.

Parameters:: **kw¶ – Keyword arguments will be passed to the scoped_session.session_factory callable, if an existing AsyncSession is not present. If the AsyncSession is present and keyword arguments have been passed, InvalidRequestError is raised.

method sqlalchemy.ext.asyncio.async_scoped_session.__init__(session_factory: async_sessionmaker[_AS], scopefunc: Callable[[], Any])¶

Construct a new async_scoped_session.

Parameters:

session_factory¶ – a factory to create new AsyncSession instances. This is usually, but not necessarily, an instance of async_sessionmaker.
scopefunc¶ – function which defines the current scope. A function such as asyncio.current_task may be useful here.

method sqlalchemy.ext.asyncio.async_scoped_session.async aclose() → None¶

A synonym for AsyncSession.close().

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

The AsyncSession.aclose() name is specifically to support the Python standard library @contextlib.aclosing context manager function.

New in version 2.0.20.

method sqlalchemy.ext.asyncio.async_scoped_session.add(instance: object, _warn: bool = True) → None¶

Place an object into this Session.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

Objects that are in the transient state when passed to the Session.add() method will move to the pending state, until the next flush, at which point they will move to the persistent state.

Objects that are in the detached state when passed to the Session.add() method will move to the persistent state directly.

If the transaction used by the Session is rolled back, objects which were transient when they were passed to Session.add() will be moved back to the transient state, and will no longer be present within this Session.

See also

Session.add_all()

Adding New or Existing Items - at Basics of Using a Session

method sqlalchemy.ext.asyncio.async_scoped_session.add_all(instances: Iterable[object]) → None¶

Add the given collection of instances to this Session.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

See the documentation for Session.add() for a general behavioral description.

See also

Session.add()

Adding New or Existing Items - at Basics of Using a Session

attribute sqlalchemy.ext.asyncio.async_scoped_session.autoflush¶: Proxy for the Session.autoflush attribute on behalf of the AsyncSession class.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

method sqlalchemy.ext.asyncio.async_scoped_session.begin() → AsyncSessionTransaction¶

Return an AsyncSessionTransaction object.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

The underlying Session will perform the “begin” action when the 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 SessionEvents.after_transaction_create() event hook that may perform IO.

For a general description of ORM begin, see Session.begin().

method sqlalchemy.ext.asyncio.async_scoped_session.begin_nested() → AsyncSessionTransaction¶

Return an AsyncSessionTransaction object which will begin a “nested” transaction, e.g. SAVEPOINT.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Behavior is the same as that of AsyncSession.begin().

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

See also

Serializable isolation / Savepoints / Transactional DDL (asyncio version) - special workarounds required with the SQLite asyncio driver in order for SAVEPOINT to work correctly.

attribute sqlalchemy.ext.asyncio.async_scoped_session.bind¶: Proxy for the AsyncSession.bind attribute on behalf of the async_scoped_session class.

method sqlalchemy.ext.asyncio.async_scoped_session.async close() → None¶: Close out the transactional resources and ORM objects used by this AsyncSession.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.close() - main documentation for “close”

Closing - detail on the semantics of AsyncSession.close() and AsyncSession.reset().

async classmethod sqlalchemy.ext.asyncio.async_scoped_session.close_all() → None¶: Close all AsyncSession sessions.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Deprecated since version 2.0: The AsyncSession.close_all() method is deprecated and will be removed in a future release. Please refer to close_all_sessions().

method sqlalchemy.ext.asyncio.async_scoped_session.async commit() → None¶: Commit the current transaction in progress.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.commit() - main documentation for “commit”

method sqlalchemy.ext.asyncio.async_scoped_session.configure(**kwargs: Any) → None¶

reconfigure the sessionmaker used by this scoped_session.

See sessionmaker.configure().

method sqlalchemy.ext.asyncio.async_scoped_session.async connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None, **kw: Any) → AsyncConnection¶

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

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

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

New in version 1.4.24: Added **kw arguments which are passed through to the underlying Session.connection() method.

See also

Session.connection() - main documentation for “connection”

method sqlalchemy.ext.asyncio.async_scoped_session.async delete(instance: object) → None¶

Mark an instance as deleted.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

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.

See also

Session.delete() - main documentation for delete

attribute sqlalchemy.ext.asyncio.async_scoped_session.deleted¶: The set of all instances marked as ‘deleted’ within this Session

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

attribute sqlalchemy.ext.asyncio.async_scoped_session.dirty¶

The set of all persistent instances considered dirty.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

E.g.:

some_mapped_object in session.dirty

Instances are considered dirty when they were modified but not deleted.

Note that this ‘dirty’ calculation is ‘optimistic’; most attribute-setting or collection modification operations will mark an instance as ‘dirty’ and place it in this set, even if there is no net change to the attribute’s value. At flush time, the value of each attribute is compared to its previously saved value, and if there’s no net change, no SQL operation will occur (this is a more expensive operation so it’s only done at flush time).

To check if an instance has actionable net changes to its attributes, use the Session.is_modified() method.

method sqlalchemy.ext.asyncio.async_scoped_session.async execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Result[Any]¶: Execute a statement and return a buffered Result object.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.execute() - main documentation for execute

method sqlalchemy.ext.asyncio.async_scoped_session.expire(instance: object, attribute_names: Iterable[str] | None = None) → None¶

Expire the attributes on an instance.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the Session object’s current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction.

To expire all objects in the Session simultaneously, use Session.expire_all().

The Session object’s default behavior is to expire all state whenever the Session.rollback() or Session.commit() methods are called, so that new state can be loaded for the new transaction. For this reason, calling Session.expire() only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction.

Parameters:

instance¶ – The instance to be refreshed.
attribute_names¶ – optional list of string attribute names indicating a subset of attributes to be expired.

See also

Refreshing / Expiring - introductory material

method sqlalchemy.ext.asyncio.async_scoped_session.expire_all() → None¶

Expires all persistent instances within this Session.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

When any attributes on a persistent instance is next accessed, a query will be issued using the Session object’s current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction.

To expire individual objects and individual attributes on those objects, use Session.expire().

The Session object’s default behavior is to expire all state whenever the Session.rollback() or Session.commit() methods are called, so that new state can be loaded for the new transaction. For this reason, calling Session.expire_all() is not usually needed, assuming the transaction is isolated.

See also

Refreshing / Expiring - introductory material

Session.in_transaction()

method sqlalchemy.ext.asyncio.async_scoped_session.expunge(instance: object) → None¶

Remove the instance from this Session.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

This will free all internal references to the instance. Cascading will be applied according to the expunge cascade rule.

method sqlalchemy.ext.asyncio.async_scoped_session.expunge_all() → None¶

Remove all object instances from this Session.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

This is equivalent to calling expunge(obj) on all objects in this Session.

method sqlalchemy.ext.asyncio.async_scoped_session.async flush(objects: Sequence[Any] | None = None) → None¶: Flush all the object changes to the database.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.flush() - main documentation for flush

method sqlalchemy.ext.asyncio.async_scoped_session.async get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O | None¶: Return an instance based on the given primary key identifier, or None if not found.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.get() - main documentation for get

method sqlalchemy.ext.asyncio.async_scoped_session.get_bind(mapper: _EntityBindKey[_O] | None = None, clause: ClauseElement | None = None, bind: _SessionBind | None = None, **kw: Any) → Engine | Connection¶

Return a “bind” to which the synchronous proxied Session is bound.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

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

Note

This method proxies directly to the Session.get_bind() method, however is currently not useful as an override target, in contrast to that of the Session.get_bind() method. The example below illustrates how to implement custom Session.get_bind() schemes that work with AsyncSession and AsyncEngine.

The pattern introduced at Custom Vertical Partitioning illustrates how to apply a custom bind-lookup scheme to a Session given a set of Engine objects. To apply a corresponding Session.get_bind() implementation for use with a AsyncSession and AsyncEngine objects, continue to subclass Session and apply it to AsyncSession using AsyncSession.sync_session_class. The inner method must continue to return Engine instances, which can be acquired from a AsyncEngine using the 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.ext.asyncio import async_sessionmaker
from sqlalchemy.orm import Session

# 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 = async_sessionmaker(
    sync_session_class=RoutingSession
)

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

method sqlalchemy.ext.asyncio.async_scoped_session.async get_one(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O¶

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

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Raises sqlalchemy.orm.exc.NoResultFound if the query selects no rows.

..versionadded: 2.0.22

See also

Session.get_one() - main documentation for get_one

Return an identity key.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

This is an alias of identity_key().

attribute sqlalchemy.ext.asyncio.async_scoped_session.identity_map¶: Proxy for the Session.identity_map attribute on behalf of the AsyncSession class.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

attribute sqlalchemy.ext.asyncio.async_scoped_session.info¶

A user-modifiable dictionary.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

The initial value of this dictionary can be populated using the info argument to the Session constructor or sessionmaker constructor or factory methods. The dictionary here is always local to this Session and can be modified independently of all other Session objects.

method sqlalchemy.ext.asyncio.async_scoped_session.async invalidate() → None¶

Close this Session, using connection invalidation.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

For a complete description, see Session.invalidate().

attribute sqlalchemy.ext.asyncio.async_scoped_session.is_active¶

True if this Session not in “partial rollback” state.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

Changed in version 1.4: The Session no longer begins a new transaction immediately, so this attribute will be False when the Session is first instantiated.

“partial rollback” state typically indicates that the flush process of the Session has failed, and that the Session.rollback() method must be emitted in order to fully roll back the transaction.

If this Session is not in a transaction at all, the Session will autobegin when it is first used, so in this case Session.is_active will return True.

Otherwise, if this Session is within a transaction, and that transaction has not been rolled back internally, the Session.is_active will also return True.

method sqlalchemy.ext.asyncio.async_scoped_session.is_modified(instance: object, include_collections: bool = True) → bool¶

Return True if the given instance has locally modified attributes.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any.

It is in effect a more expensive and accurate version of checking for the given instance in the Session.dirty collection; a full test for each attribute’s net “dirty” status is performed.

E.g.:

return session.is_modified(someobject)

A few caveats to this method apply:

Instances present in the Session.dirty collection may report False when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in Session.dirty, but ultimately the state is the same as that loaded from the database, resulting in no net change here.
Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the “old” value when a set event occurs, so it skips the expense of a SQL call if the old value isn’t present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn’t, is less expensive on average than issuing a defensive SELECT.

The “old” value is fetched unconditionally upon set only if the attribute container has the active_history flag set to True. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the active_history argument with column_property().

Parameters:

instance¶ – mapped instance to be tested for pending changes.
include_collections¶ – Indicates if multivalued collections should be included in the operation. Setting this to False is a way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush.

method sqlalchemy.ext.asyncio.async_scoped_session.async merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O¶: Copy the state of a given instance into a corresponding instance within this AsyncSession.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.merge() - main documentation for merge

attribute sqlalchemy.ext.asyncio.async_scoped_session.new¶: The set of all instances marked as ‘new’ within this Session.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

attribute sqlalchemy.ext.asyncio.async_scoped_session.no_autoflush¶

Return a context manager that disables autoflush.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

e.g.:

with session.no_autoflush:

    some_object = SomeClass()
    session.add(some_object)
    # won't autoflush
    some_object.related_thing = session.query(SomeRelated).first()

Operations that proceed within the with: block will not be subject to flushes occurring upon query access. This is useful when initializing a series of objects which involve existing database queries, where the uncompleted object should not yet be flushed.

classmethod sqlalchemy.ext.asyncio.async_scoped_session.object_session(instance: object) → Session | None¶

Return the Session to which an object belongs.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Proxied for the Session class on behalf of the AsyncSession class.

This is an alias of object_session().

method sqlalchemy.ext.asyncio.async_scoped_session.async refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None¶

Expire and refresh the attributes on the given instance.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

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 Session.refresh() method. See that method for a complete description of all options.

See also

Session.refresh() - main documentation for refresh

method sqlalchemy.ext.asyncio.async_scoped_session.async remove() → None¶

Dispose of the current AsyncSession, if present.

Different from scoped_session’s remove method, this method would use await to wait for the close method of AsyncSession.

method sqlalchemy.ext.asyncio.async_scoped_session.async reset() → None¶: Close out the transactional resources and ORM objects used by this Session, resetting the session to its initial state.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

New in version 2.0.22.

See also

Session.reset() - main documentation for “reset”

Closing - detail on the semantics of AsyncSession.close() and AsyncSession.reset().

method sqlalchemy.ext.asyncio.async_scoped_session.async rollback() → None¶: Rollback the current transaction in progress.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.rollback() - main documentation for “rollback”

method sqlalchemy.ext.asyncio.async_scoped_session.async scalar(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any¶: Execute a statement and return a scalar result.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

See also

Session.scalar() - main documentation for scalar

method sqlalchemy.ext.asyncio.async_scoped_session.async scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]¶

Execute a statement and return scalar results.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Returns:: a ScalarResult object

New in version 1.4.24: Added AsyncSession.scalars()

New in version 1.4.26: Added async_scoped_session.scalars()

See also

Session.scalars() - main documentation for scalars

AsyncSession.stream_scalars() - streaming version

attribute sqlalchemy.ext.asyncio.async_scoped_session.session_factory: async_sessionmaker[_AS]¶: The session_factory provided to __init__ is stored in this attribute and may be accessed at a later time. This can be useful when a new non-scoped AsyncSession is needed.

method sqlalchemy.ext.asyncio.async_scoped_session.async stream(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncResult[Any]¶: Execute a statement and return a streaming AsyncResult object.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

method sqlalchemy.ext.asyncio.async_scoped_session.async stream_scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncScalarResult[Any]¶

Execute a statement and return a stream of scalar results.

Proxied for the AsyncSession class on behalf of the async_scoped_session class.

Returns:: an AsyncScalarResult object

New in version 1.4.24.

See also

Session.scalars() - main documentation for scalars

AsyncSession.scalars() - non streaming version

class sqlalchemy.ext.asyncio.AsyncAttrs¶

Mixin class which provides an awaitable accessor for all attributes.

E.g.:

from __future__ import annotations

from typing import List

from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy.ext.asyncio import AsyncAttrs
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(AsyncAttrs, DeclarativeBase):
    pass


class A(Base):
    __tablename__ = "a"

    id: Mapped[int] = mapped_column(primary_key=True)
    data: Mapped[str]
    bs: Mapped[List[B]] = relationship()


class B(Base):
    __tablename__ = "b"
    id: Mapped[int] = mapped_column(primary_key=True)
    a_id: Mapped[int] = mapped_column(ForeignKey("a.id"))
    data: Mapped[str]

In the above example, the AsyncAttrs mixin is applied to the declarative Base class where it takes effect for all subclasses. This mixin adds a single new attribute AsyncAttrs.awaitable_attrs to all classes, which will yield the value of any attribute as an awaitable. This allows attributes which may be subject to lazy loading or deferred / unexpiry loading to be accessed such that IO can still be emitted:

a1 = (await async_session.scalars(select(A).where(A.id == 5))).one()

# use the lazy loader on ``a1.bs`` via the ``.awaitable_attrs``
# interface, so that it may be awaited
for b1 in await a1.awaitable_attrs.bs:
    print(b1)

The AsyncAttrs.awaitable_attrs performs a call against the attribute that is approximately equivalent to using the AsyncSession.run_sync() method, e.g.:

for b1 in await async_session.run_sync(lambda sess: a1.bs):
    print(b1)

New in version 2.0.13.

Members

awaitable_attrs

attribute sqlalchemy.ext.asyncio.AsyncAttrs.awaitable_attrs¶

provide a namespace of all attributes on this object wrapped as awaitables.

e.g.:

a1 = (await async_session.scalars(select(A).where(A.id == 5))).one()

some_attribute = await a1.awaitable_attrs.some_deferred_attribute
some_collection = await a1.awaitable_attrs.some_collection

class sqlalchemy.ext.asyncio.AsyncSession¶

Asyncio version of Session.

The AsyncSession is a proxy for a traditional Session instance.

The AsyncSession is not safe for use in concurrent tasks.. See Is the Session thread-safe? Is AsyncSession safe to share in concurrent tasks? for background.

New in version 1.4.

To use an AsyncSession with custom Session implementations, see the AsyncSession.sync_session_class parameter.

Class signature

class sqlalchemy.ext.asyncio.AsyncSession (sqlalchemy.ext.asyncio.base.ReversibleProxy)

attribute sqlalchemy.ext.asyncio.AsyncSession.sync_session_class: Type[Session] = <class 'sqlalchemy.orm.session.Session'>¶

The class or callable that provides the underlying Session instance for a particular AsyncSession.

At the class level, this attribute is the default value for the AsyncSession.sync_session_class parameter. Custom subclasses of AsyncSession can override this.

At the instance level, this attribute indicates the current class or callable that was used to provide the Session instance for this AsyncSession instance.

New in version 1.4.24.

method sqlalchemy.ext.asyncio.AsyncSession.__init__(bind: _AsyncSessionBind | None = None, *, binds: Dict[_SessionBindKey, _AsyncSessionBind] | None = None, sync_session_class: Type[Session] | None = None, **kw: Any)¶

Construct a new AsyncSession.

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

Parameters:

sync_session_class¶ –

A Session subclass or other callable which will be used to construct the Session which will be proxied. This parameter may be used to provide custom Session subclasses. Defaults to the AsyncSession.sync_session_class class-level attribute.

New in version 1.4.24.

method sqlalchemy.ext.asyncio.AsyncSession.async aclose() → None¶

A synonym for AsyncSession.close().

The AsyncSession.aclose() name is specifically to support the Python standard library @contextlib.aclosing context manager function.

New in version 2.0.20.

method sqlalchemy.ext.asyncio.AsyncSession.add(instance: object, _warn: bool = True) → None¶

Place an object into this Session.

Proxied for the Session class on behalf of the AsyncSession class.

Objects that are in the transient state when passed to the Session.add() method will move to the pending state, until the next flush, at which point they will move to the persistent state.

Objects that are in the detached state when passed to the Session.add() method will move to the persistent state directly.

If the transaction used by the Session is rolled back, objects which were transient when they were passed to Session.add() will be moved back to the transient state, and will no longer be present within this Session.

See also

Session.add_all()

Adding New or Existing Items - at Basics of Using a Session

method sqlalchemy.ext.asyncio.AsyncSession.add_all(instances: Iterable[object]) → None¶

Add the given collection of instances to this Session.

Proxied for the Session class on behalf of the AsyncSession class.

See the documentation for Session.add() for a general behavioral description.

See also

Session.add()

Adding New or Existing Items - at Basics of Using a Session

attribute sqlalchemy.ext.asyncio.AsyncSession.autoflush¶: Proxy for the Session.autoflush attribute on behalf of the AsyncSession class.

method sqlalchemy.ext.asyncio.AsyncSession.begin() → AsyncSessionTransaction¶

Return an AsyncSessionTransaction object.

The underlying Session will perform the “begin” action when the 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 SessionEvents.after_transaction_create() event hook that may perform IO.

For a general description of ORM begin, see Session.begin().

method sqlalchemy.ext.asyncio.AsyncSession.begin_nested() → AsyncSessionTransaction¶

Return an AsyncSessionTransaction object which will begin a “nested” transaction, e.g. SAVEPOINT.

Behavior is the same as that of AsyncSession.begin().

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

See also

Serializable isolation / Savepoints / Transactional DDL (asyncio version) - special workarounds required with the SQLite asyncio driver in order for SAVEPOINT to work correctly.

method sqlalchemy.ext.asyncio.AsyncSession.async close() → None¶: Close out the transactional resources and ORM objects used by this AsyncSession.

See also

Session.close() - main documentation for “close”

Closing - detail on the semantics of AsyncSession.close() and AsyncSession.reset().

async classmethod sqlalchemy.ext.asyncio.AsyncSession.close_all() → None¶: Close all AsyncSession sessions.

Deprecated since version 2.0: The AsyncSession.close_all() method is deprecated and will be removed in a future release. Please refer to close_all_sessions().

method sqlalchemy.ext.asyncio.AsyncSession.async commit() → None¶: Commit the current transaction in progress.

See also

Session.commit() - main documentation for “commit”

method sqlalchemy.ext.asyncio.AsyncSession.async connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None, **kw: Any) → AsyncConnection¶

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

New in version 1.4.24: Added **kw arguments which are passed through to the underlying Session.connection() method.

See also

Session.connection() - main documentation for “connection”

method sqlalchemy.ext.asyncio.AsyncSession.async delete(instance: object) → None¶

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.

See also

Session.delete() - main documentation for delete

attribute sqlalchemy.ext.asyncio.AsyncSession.deleted¶: The set of all instances marked as ‘deleted’ within this Session

Proxied for the Session class on behalf of the AsyncSession class.

attribute sqlalchemy.ext.asyncio.AsyncSession.dirty¶

The set of all persistent instances considered dirty.

Proxied for the Session class on behalf of the AsyncSession class.

E.g.:

some_mapped_object in session.dirty

Instances are considered dirty when they were modified but not deleted.

Note that this ‘dirty’ calculation is ‘optimistic’; most attribute-setting or collection modification operations will mark an instance as ‘dirty’ and place it in this set, even if there is no net change to the attribute’s value. At flush time, the value of each attribute is compared to its previously saved value, and if there’s no net change, no SQL operation will occur (this is a more expensive operation so it’s only done at flush time).

To check if an instance has actionable net changes to its attributes, use the Session.is_modified() method.

method sqlalchemy.ext.asyncio.AsyncSession.async execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Result[Any]¶: Execute a statement and return a buffered Result object.

See also

Session.execute() - main documentation for execute

method sqlalchemy.ext.asyncio.AsyncSession.expire(instance: object, attribute_names: Iterable[str] | None = None) → None¶

Expire the attributes on an instance.

Proxied for the Session class on behalf of the AsyncSession class.

Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the Session object’s current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction.

To expire all objects in the Session simultaneously, use Session.expire_all().

The Session object’s default behavior is to expire all state whenever the Session.rollback() or Session.commit() methods are called, so that new state can be loaded for the new transaction. For this reason, calling Session.expire() only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction.

Parameters:

instance¶ – The instance to be refreshed.
attribute_names¶ – optional list of string attribute names indicating a subset of attributes to be expired.

See also

Refreshing / Expiring - introductory material

method sqlalchemy.ext.asyncio.AsyncSession.expire_all() → None¶

Expires all persistent instances within this Session.

Proxied for the Session class on behalf of the AsyncSession class.

When any attributes on a persistent instance is next accessed, a query will be issued using the Session object’s current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction.

To expire individual objects and individual attributes on those objects, use Session.expire().

The Session object’s default behavior is to expire all state whenever the Session.rollback() or Session.commit() methods are called, so that new state can be loaded for the new transaction. For this reason, calling Session.expire_all() is not usually needed, assuming the transaction is isolated.

See also

Refreshing / Expiring - introductory material

Session.in_transaction()

method sqlalchemy.ext.asyncio.AsyncSession.expunge(instance: object) → None¶

Remove the instance from this Session.

Proxied for the Session class on behalf of the AsyncSession class.

This will free all internal references to the instance. Cascading will be applied according to the expunge cascade rule.

method sqlalchemy.ext.asyncio.AsyncSession.expunge_all() → None¶

Remove all object instances from this Session.

Proxied for the Session class on behalf of the AsyncSession class.

This is equivalent to calling expunge(obj) on all objects in this Session.

method sqlalchemy.ext.asyncio.AsyncSession.async flush(objects: Sequence[Any] | None = None) → None¶: Flush all the object changes to the database.

See also

Session.flush() - main documentation for flush

method sqlalchemy.ext.asyncio.AsyncSession.async get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O | None¶: Return an instance based on the given primary key identifier, or None if not found.

See also

Session.get() - main documentation for get

method sqlalchemy.ext.asyncio.AsyncSession.get_bind(mapper: _EntityBindKey[_O] | None = None, clause: ClauseElement | None = None, bind: _SessionBind | None = None, **kw: Any) → Engine | Connection¶

Return a “bind” to which the synchronous proxied Session is bound.

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

Note

This method proxies directly to the Session.get_bind() method, however is currently not useful as an override target, in contrast to that of the Session.get_bind() method. The example below illustrates how to implement custom Session.get_bind() schemes that work with AsyncSession and AsyncEngine.

The pattern introduced at Custom Vertical Partitioning illustrates how to apply a custom bind-lookup scheme to a Session given a set of Engine objects. To apply a corresponding Session.get_bind() implementation for use with a AsyncSession and AsyncEngine objects, continue to subclass Session and apply it to AsyncSession using AsyncSession.sync_session_class. The inner method must continue to return Engine instances, which can be acquired from a AsyncEngine using the 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.ext.asyncio import async_sessionmaker
from sqlalchemy.orm import Session

# 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 = async_sessionmaker(
    sync_session_class=RoutingSession
)

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

method sqlalchemy.ext.asyncio.AsyncSession.get_nested_transaction() → AsyncSessionTransaction | None¶

Return the current nested transaction in progress, if any.

Returns:: an AsyncSessionTransaction object, or None.

New in version 1.4.18.

method sqlalchemy.ext.asyncio.AsyncSession.async get_one(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O¶

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

Raises sqlalchemy.orm.exc.NoResultFound if the query selects no rows.

..versionadded: 2.0.22

See also

Session.get_one() - main documentation for get_one

method sqlalchemy.ext.asyncio.AsyncSession.get_transaction() → AsyncSessionTransaction | None¶

Return the current root transaction in progress, if any.

Returns:: an AsyncSessionTransaction object, or None.

New in version 1.4.18.

Return an identity key.

Proxied for the Session class on behalf of the AsyncSession class.

This is an alias of identity_key().

attribute sqlalchemy.ext.asyncio.AsyncSession.identity_map¶: Proxy for the Session.identity_map attribute on behalf of the AsyncSession class.

method sqlalchemy.ext.asyncio.AsyncSession.in_nested_transaction() → bool¶: Return True if this Session has begun a nested transaction, e.g. SAVEPOINT.

Proxied for the Session class on behalf of the AsyncSession class.

New in version 1.4.

method sqlalchemy.ext.asyncio.AsyncSession.in_transaction() → bool¶: Return True if this Session has begun a transaction.

Proxied for the Session class on behalf of the AsyncSession class.

New in version 1.4.

See also

Session.is_active

attribute sqlalchemy.ext.asyncio.AsyncSession.info¶

A user-modifiable dictionary.

Proxied for the Session class on behalf of the AsyncSession class.

The initial value of this dictionary can be populated using the info argument to the Session constructor or sessionmaker constructor or factory methods. The dictionary here is always local to this Session and can be modified independently of all other Session objects.

method sqlalchemy.ext.asyncio.AsyncSession.async invalidate() → None¶

Close this Session, using connection invalidation.

For a complete description, see Session.invalidate().

attribute sqlalchemy.ext.asyncio.AsyncSession.is_active¶

True if this Session not in “partial rollback” state.

Proxied for the Session class on behalf of the AsyncSession class.

Changed in version 1.4: The Session no longer begins a new transaction immediately, so this attribute will be False when the Session is first instantiated.

“partial rollback” state typically indicates that the flush process of the Session has failed, and that the Session.rollback() method must be emitted in order to fully roll back the transaction.

If this Session is not in a transaction at all, the Session will autobegin when it is first used, so in this case Session.is_active will return True.

Otherwise, if this Session is within a transaction, and that transaction has not been rolled back internally, the Session.is_active will also return True.

method sqlalchemy.ext.asyncio.AsyncSession.is_modified(instance: object, include_collections: bool = True) → bool¶

Return True if the given instance has locally modified attributes.

Proxied for the Session class on behalf of the AsyncSession class.

This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any.

It is in effect a more expensive and accurate version of checking for the given instance in the Session.dirty collection; a full test for each attribute’s net “dirty” status is performed.

E.g.:

return session.is_modified(someobject)

A few caveats to this method apply:

Instances present in the Session.dirty collection may report False when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in Session.dirty, but ultimately the state is the same as that loaded from the database, resulting in no net change here.
Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the “old” value when a set event occurs, so it skips the expense of a SQL call if the old value isn’t present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn’t, is less expensive on average than issuing a defensive SELECT.

The “old” value is fetched unconditionally upon set only if the attribute container has the active_history flag set to True. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the active_history argument with column_property().

Parameters:

instance¶ – mapped instance to be tested for pending changes.
include_collections¶ – Indicates if multivalued collections should be included in the operation. Setting this to False is a way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush.

method sqlalchemy.ext.asyncio.AsyncSession.async merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O¶: Copy the state of a given instance into a corresponding instance within this AsyncSession.

See also

Session.merge() - main documentation for merge

attribute sqlalchemy.ext.asyncio.AsyncSession.new¶: The set of all instances marked as ‘new’ within this Session.

Proxied for the Session class on behalf of the AsyncSession class.

attribute sqlalchemy.ext.asyncio.AsyncSession.no_autoflush¶

Return a context manager that disables autoflush.

Proxied for the Session class on behalf of the AsyncSession class.

e.g.:

with session.no_autoflush:

    some_object = SomeClass()
    session.add(some_object)
    # won't autoflush
    some_object.related_thing = session.query(SomeRelated).first()

Operations that proceed within the with: block will not be subject to flushes occurring upon query access. This is useful when initializing a series of objects which involve existing database queries, where the uncompleted object should not yet be flushed.

classmethod sqlalchemy.ext.asyncio.AsyncSession.object_session(instance: object) → Session | None¶

Return the Session to which an object belongs.

Proxied for the Session class on behalf of the AsyncSession class.

This is an alias of object_session().

method sqlalchemy.ext.asyncio.AsyncSession.async refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None¶

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 Session.refresh() method. See that method for a complete description of all options.

See also

Session.refresh() - main documentation for refresh

method sqlalchemy.ext.asyncio.AsyncSession.async reset() → None¶: Close out the transactional resources and ORM objects used by this Session, resetting the session to its initial state.

New in version 2.0.22.

See also

Session.reset() - main documentation for “reset”

Closing - detail on the semantics of AsyncSession.close() and AsyncSession.reset().

method sqlalchemy.ext.asyncio.AsyncSession.async rollback() → None¶: Rollback the current transaction in progress.

See also

Session.rollback() - main documentation for “rollback”

method sqlalchemy.ext.asyncio.AsyncSession.async run_sync(fn: ~typing.Callable[[~typing.Concatenate[~sqlalchemy.orm.session.Session, ~_P]], ~sqlalchemy.ext.asyncio.session._T], *arg: ~typing.~_P, **kw: ~typing.~_P) → _T¶

Invoke the given synchronous (i.e. not async) callable, passing a synchronous-style Session as the first argument.

This method allows traditional synchronous SQLAlchemy functions to run within the context of an asyncio application.

E.g.:

def some_business_method(session: Session, param: str) -> str:
    '''A synchronous function that does not require awaiting

    :param session: a SQLAlchemy Session, used synchronously

    :return: an optional return value is supported

    '''
    session.add(MyObject(param=param))
    session.flush()
    return "success"


async def do_something_async(async_engine: AsyncEngine) -> None:
    '''an async function that uses awaiting'''

    with AsyncSession(async_engine) as async_session:
        # run some_business_method() with a sync-style
        # Session, proxied into an awaitable
        return_code = await async_session.run_sync(some_business_method, param="param1")
        print(return_code)

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.

Tip

The provided callable is invoked inline within the asyncio event loop, and will block on traditional IO calls. IO within this callable should only call into SQLAlchemy’s asyncio database APIs which will be properly adapted to the greenlet context.

See also

AsyncAttrs - a mixin for ORM mapped classes that provides a similar feature more succinctly on a per-attribute basis

AsyncConnection.run_sync()

Running Synchronous Methods and Functions under asyncio

method sqlalchemy.ext.asyncio.AsyncSession.async scalar(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any¶: Execute a statement and return a scalar result.

See also

Session.scalar() - main documentation for scalar

method sqlalchemy.ext.asyncio.AsyncSession.async scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]¶

Execute a statement and return scalar results.

Returns:: a ScalarResult object

New in version 1.4.24: Added AsyncSession.scalars()

New in version 1.4.26: Added async_scoped_session.scalars()

See also

Session.scalars() - main documentation for scalars

AsyncSession.stream_scalars() - streaming version

method sqlalchemy.ext.asyncio.AsyncSession.async stream(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncResult[Any]¶: Execute a statement and return a streaming AsyncResult object.

method sqlalchemy.ext.asyncio.AsyncSession.async stream_scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncScalarResult[Any]¶

Execute a statement and return a stream of scalar results.

Returns:: an AsyncScalarResult object

New in version 1.4.24.

See also

Session.scalars() - main documentation for scalars

AsyncSession.scalars() - non streaming version

attribute sqlalchemy.ext.asyncio.AsyncSession.sync_session: Session¶

Reference to the underlying Session this AsyncSession proxies requests towards.

This instance can be used as an event target.

See also