Support for Python asyncio. Support for Core and ORM usage is included, using asyncio-compatible dialects.
New in version 1.4.
Note
The asyncio extension as of SQLAlchemy 1.4.3 can now be considered to be beta level software. API details are subject to change however at this point it is unlikely for there to be significant backwards-incompatible changes.
See also
Asynchronous IO Support for Core and ORM - initial feature announcement
Asyncio Integration - example scripts illustrating working examples of Core and ORM use within the asyncio extension.
The asyncio extension requires at least Python version 3.6. It also depends upon the greenlet library. This dependency is installed by default on common machine platforms including:
x86_64 aarch64 ppc64le amd64 win32
For the above platforms, greenlet
is known to supply pre-built wheel files.
To ensure the greenlet
dependency is present on other platforms, the
[asyncio]
extra may be installed as follows, which will include an attempt
to build and install greenlet
:
pip install sqlalchemy[asyncio]
For Core use, the create_async_engine()
function creates an
instance of AsyncEngine
which then offers an async version of
the traditional Engine
API. The
AsyncEngine
delivers an AsyncConnection
via
its AsyncEngine.connect()
and AsyncEngine.begin()
methods which both deliver asynchronous context managers. The
AsyncConnection
can then invoke statements using either the
AsyncConnection.execute()
method to deliver a buffered
Result
, or the AsyncConnection.stream()
method
to deliver a streaming server-side AsyncResult
:
import asyncio
from sqlalchemy.ext.asyncio import create_async_engine
async def async_main():
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test", echo=True,
)
async with engine.begin() as conn:
await conn.run_sync(meta.drop_all)
await conn.run_sync(meta.create_all)
await conn.execute(
t1.insert(), [{"name": "some name 1"}, {"name": "some name 2"}]
)
async with engine.connect() as conn:
# select a Result, which will be delivered with buffered
# results
result = await conn.execute(select(t1).where(t1.c.name == "some name 1"))
print(result.fetchall())
# for AsyncEngine created in function scope, close and
# clean-up pooled connections
await engine.dispose()
asyncio.run(async_main())
Above, the AsyncConnection.run_sync()
method may be used to
invoke special DDL functions such as MetaData.create_all()
that
don’t include an awaitable hook.
Tip
It’s advisable to invoke the AsyncEngine.dispose()
method
using await
when using the AsyncEngine
object in a
scope that will go out of context and be garbage collected, as illustrated in the
async_main
function in the above example. This ensures that any
connections held open by the connection pool will be properly disposed
within an awaitable context. Unlike when using blocking IO, SQLAlchemy
cannot properly dispose of these connections within methods like __del__
or weakref finalizers as there is no opportunity to invoke await
.
Failing to explicitly dispose of the engine when it falls out of scope
may result in warnings emitted to standard out resembling the form
RuntimeError: Event loop is closed
within garbage collection.
The AsyncConnection
also features a “streaming” API via
the AsyncConnection.stream()
method that returns an
AsyncResult
object. This result object uses a server-side
cursor and provides an async/await API, such as an async iterator:
async with engine.connect() as conn:
async_result = await conn.stream(select(t1))
async for row in async_result:
print("row: %s" % (row, ))
Using 2.0 style querying, the AsyncSession
class
provides full ORM functionality. Within the default mode of use, special care
must be taken to avoid lazy loading or other expired-attribute access
involving ORM relationships and column attributes; the next
section Preventing Implicit IO when Using AsyncSession details this. The example below
illustrates a complete example including mapper and session configuration:
import asyncio
from sqlalchemy import Column
from sqlalchemy import DateTime
from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.future import select
from sqlalchemy.orm import declarative_base
from sqlalchemy.orm import relationship
from sqlalchemy.orm import selectinload
from sqlalchemy.orm import sessionmaker
Base = declarative_base()
class A(Base):
__tablename__ = "a"
id = Column(Integer, primary_key=True)
data = Column(String)
create_date = Column(DateTime, server_default=func.now())
bs = relationship("B")
# required in order to access columns with server defaults
# or SQL expression defaults, subsequent to a flush, without
# triggering an expired load
__mapper_args__ = {"eager_defaults": True}
class B(Base):
__tablename__ = "b"
id = Column(Integer, primary_key=True)
a_id = Column(ForeignKey("a.id"))
data = Column(String)
async def async_main():
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test",
echo=True,
)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
await conn.run_sync(Base.metadata.create_all)
# expire_on_commit=False will prevent attributes from being expired
# after commit.
async_session = sessionmaker(
engine, expire_on_commit=False, class_=AsyncSession
)
async with async_session() as session:
async with session.begin():
session.add_all(
[
A(bs=[B(), B()], data="a1"),
A(bs=[B()], data="a2"),
A(bs=[B(), B()], data="a3"),
]
)
stmt = select(A).options(selectinload(A.bs))
result = await session.execute(stmt)
for a1 in result.scalars():
print(a1)
print(f"created at: {a1.create_date}")
for b1 in a1.bs:
print(b1)
result = await session.execute(select(A).order_by(A.id))
a1 = result.scalars().first()
a1.data = "new data"
await session.commit()
# access attribute subsequent to commit; this is what
# expire_on_commit=False allows
print(a1.data)
# for AsyncEngine created in function scope, close and
# clean-up pooled connections
await engine.dispose()
asyncio.run(async_main())
In the example above, the AsyncSession
is instantiated using
the optional sessionmaker
helper, and associated with an
AsyncEngine
against particular database URL. It is
then used in a Python asynchronous context manager (i.e. async with:
statement) so that it is automatically closed at the end of the block; this is
equivalent to calling the AsyncSession.close()
method.
Note
AsyncSession
uses SQLAlchemy’s future mode, which
has several potentially breaking changes. One such change is the new
default behavior of cascade_backrefs
is False
, which may affect
how related objects are saved to the database.
Using traditional asyncio, the application needs to avoid any points at which IO-on-attribute access may occur. Above, the following measures are taken to prevent this:
The selectinload()
eager loader is employed in order to eagerly
load the A.bs
collection within the scope of the
await session.execute()
call:
stmt = select(A).options(selectinload(A.bs))
If the default loader strategy of “lazyload” were left in place, the access
of the A.bs
attribute would raise an asyncio exception.
There are a variety of ORM loader options available, which may be configured
at the default mapping level or used on a per-query basis, documented at
Relationship Loading Techniques.
The AsyncSession
is configured using
Session.expire_on_commit
set to False, so that we may access
attributes on an object subsequent to a call to
AsyncSession.commit()
, as in the line at the end where we
access an attribute:
# create AsyncSession with expire_on_commit=False
async_session = AsyncSession(engine, expire_on_commit=False)
# sessionmaker version
async_session = sessionmaker(
engine, expire_on_commit=False, class_=AsyncSession
)
async with async_session() as session:
result = await session.execute(select(A).order_by(A.id))
a1 = result.scalars().first()
# commit would normally expire all attributes
await session.commit()
# access attribute subsequent to commit; this is what
# expire_on_commit=False allows
print(a1.data)
The Column.server_default
value on the created_at
column will not be refreshed by default after an INSERT; instead, it is
normally
expired so that it can be loaded when needed.
Similar behavior applies to a column where the
Column.default
parameter is assigned to a SQL expression
object. To access this value with asyncio, it has to be refreshed within the
flush process, which is achieved by setting the
mapper.eager_defaults
parameter on the mapping:
class A(Base):
# ...
# column with a server_default, or SQL expression default
create_date = Column(DateTime, server_default=func.now())
# add this so that it can be accessed
__mapper_args__ = {"eager_defaults": True}
Other guidelines include:
Methods like AsyncSession.expire()
should be avoided in favor of
AsyncSession.refresh()
Avoid using the all
cascade option documented at Cascades
in favor of listing out the desired cascade features explicitly. The
all
cascade option implies among others the refresh-expire
setting, which means that the AsyncSession.refresh()
method will
expire the attributes on related objects, but not necessarily refresh those
related objects assuming eager loading is not configured within the
relationship()
, leaving them in an expired state. A future
release may introduce the ability to indicate eager loader options when
invoking Session.refresh()
and/or AsyncSession.refresh()
.
Appropriate loader options should be employed for deferred()
columns, if used at all, in addition to that of relationship()
constructs as noted above. See Deferred Column Loading for background on
deferred column loading.
The “dynamic” relationship loader strategy described at
Dynamic Relationship Loaders is not compatible by default with the asyncio approach.
It can be used directly only if invoked within the
AsyncSession.run_sync()
method described at
Running Synchronous Methods and Functions under asyncio, or by using its .statement
attribute
to obtain a normal select:
user = await session.get(User, 42)
addresses = (await session.scalars(user.addresses.statement)).all()
stmt = user.addresses.statement.where(
Address.email_address.startswith("patrick")
)
addresses_filter = (await session.scalars(stmt)).all()
See also
Making use of “dynamic” relationship loads without using Query - notes on migration to 2.0 style
Deep Alchemy
This approach is essentially exposing publicly the
mechanism by which SQLAlchemy is able to provide the asyncio interface
in the first place. While there is no technical issue with doing so, overall
the approach can probably be considered “controversial” as it works against
some of the central philosophies of the asyncio programming model, which
is essentially that any programming statement that can potentially result
in IO being invoked must have an await
call, lest the program
does not make it explicitly clear every line at which IO may occur.
This approach does not change that general idea, except that it allows
a series of synchronous IO instructions to be exempted from this rule
within the scope of a function call, essentially bundled up into a single
awaitable.
As an alternative means of integrating traditional SQLAlchemy “lazy loading”
within an asyncio event loop, an optional method known as
AsyncSession.run_sync()
is provided which will run any
Python function inside of a greenlet, where traditional synchronous
programming concepts will be translated to use await
when they reach the
database driver. A hypothetical approach here is an asyncio-oriented
application can package up database-related methods into functions that are
invoked using AsyncSession.run_sync()
.
Altering the above example, if we didn’t use selectinload()
for the A.bs
collection, we could accomplish our treatment of these
attribute accesses within a separate function:
import asyncio
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import AsyncSession
def fetch_and_update_objects(session):
"""run traditional sync-style ORM code in a function that will be
invoked within an awaitable.
"""
# the session object here is a traditional ORM Session.
# all features are available here including legacy Query use.
stmt = select(A)
result = session.execute(stmt)
for a1 in result.scalars():
print(a1)
# lazy loads
for b1 in a1.bs:
print(b1)
# legacy Query use
a1 = session.query(A).order_by(A.id).first()
a1.data = "new data"
async def async_main():
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test", echo=True,
)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
await conn.run_sync(Base.metadata.create_all)
async with AsyncSession(engine) as session:
async with session.begin():
session.add_all(
[
A(bs=[B(), B()], data="a1"),
A(bs=[B()], data="a2"),
A(bs=[B(), B()], data="a3"),
]
)
await session.run_sync(fetch_and_update_objects)
await session.commit()
# for AsyncEngine created in function scope, close and
# clean-up pooled connections
await engine.dispose()
asyncio.run(async_main())
The above approach of running certain functions within a “sync” runner
has some parallels to an application that runs a SQLAlchemy application
on top of an event-based programming library such as gevent
. The
differences are as follows:
unlike when using gevent
, we can continue to use the standard Python
asyncio event loop, or any custom event loop, without the need to integrate
into the gevent
event loop.
There is no “monkeypatching” whatsoever. The above example makes use of
a real asyncio driver and the underlying SQLAlchemy connection pool is also
using the Python built-in asyncio.Queue
for pooling connections.
The program can freely switch between async/await code and contained functions that use sync code with virtually no performance penalty. There is no “thread executor” or any additional waiters or synchronization in use.
The underlying network drivers are also using pure Python asyncio
concepts, no third party networking libraries as gevent
and eventlet
provides are in use.
The SQLAlchemy event system is not directly exposed by the asyncio extension, meaning there is not yet an “async” version of a SQLAlchemy event handler.
However, as the asyncio extension surrounds the usual synchronous SQLAlchemy API, regular “synchronous” style event handlers are freely available as they would be if asyncio were not used.
As detailed below, there are two current strategies to register events given asyncio-facing APIs:
Events can be registered at the instance level (e.g. a specific
AsyncEngine
instance) by associating the event with the
sync
attribute that refers to the proxied object. For example to register
the PoolEvents.connect()
event against an
AsyncEngine
instance, use its
AsyncEngine.sync_engine
attribute as target. Targets
include:
To register an event at the class level, targeting all instances of the same type (e.g.
all AsyncSession
instances), use the corresponding
sync-style class. For example to register the
SessionEvents.before_commit()
event against the
AsyncSession
class, use the Session
class as
the target.
When working within an event handler that is within an asyncio context, objects
like the Connection
continue to work in their usual
“synchronous” way without requiring await
or async
usage; when messages
are ultimately received by the asyncio database adapter, the calling style is
transparently adapted back into the asyncio calling style. For events that
are passed a DBAPI level connection, such as PoolEvents.connect()
,
the object is a pep-249 compliant “connection” object which will adapt
sync-style calls into the asyncio driver.
Some examples of sync style event handlers associated with async-facing API constructs are illustrated below:
import asyncio
from sqlalchemy import text
from sqlalchemy.engine import Engine
from sqlalchemy import event
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.orm import Session
## Core events ##
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost:5432/test"
)
# connect event on instance of Engine
@event.listens_for(engine.sync_engine, "connect")
def my_on_connect(dbapi_con, connection_record):
print("New DBAPI connection:", dbapi_con)
cursor = dbapi_con.cursor()
# sync style API use for adapted DBAPI connection / cursor
cursor.execute("select 'execute from event'")
print(cursor.fetchone()[0])
# before_execute event on all Engine instances
@event.listens_for(Engine, "before_execute")
def my_before_execute(
conn, clauseelement, multiparams, params, execution_options
):
print("before execute!")
## ORM events ##
session = AsyncSession(engine)
# before_commit event on instance of Session
@event.listens_for(session.sync_session, "before_commit")
def my_before_commit(session):
print("before commit!")
# sync style API use on Session
connection = session.connection()
# sync style API use on Connection
result = connection.execute(text("select 'execute from event'"))
print(result.first())
# after_commit event on all Session instances
@event.listens_for(Session, "after_commit")
def my_after_commit(session):
print("after commit!")
async def go():
await session.execute(text("select 1"))
await session.commit()
await session.close()
await engine.dispose()
asyncio.run(go())
The above example prints something along the lines of:
New DBAPI connection: <AdaptedConnection <asyncpg.connection.Connection ...>>
execute from event
before execute!
before commit!
execute from event
after commit!
asyncio and events, two opposites
SQLAlchemy events by their nature take place within the interior of a particular SQLAlchemy process; that is, an event always occurs after some particular SQLAlchemy API has been invoked by end-user code, and before some other internal aspect of that API occurs.
Constrast this to the architecture of the asyncio extension, which takes place on the exterior of SQLAlchemy’s usual flow from end-user API to DBAPI function.
The flow of messaging may be visualized as follows:
SQLAlchemy SQLAlchemy SQLAlchemy SQLAlchemy plain
asyncio asyncio ORM/Core asyncio asyncio
(public (internal) (internal)
facing)
-------------|------------|------------------------|-----------|------------
asyncio API | | | |
call -> | | | |
| -> -> | | -> -> |
|~~~~~~~~~~~~| sync API call -> |~~~~~~~~~~~|
| asyncio | event hooks -> | sync |
| to | invoke action -> | to |
| sync | event hooks -> | asyncio |
| (greenlet) | dialect -> | (leave |
|~~~~~~~~~~~~| event hooks -> | greenlet) |
| -> -> | sync adapted |~~~~~~~~~~~|
| | DBAPI -> | -> -> | asyncio
| | | | driver -> database
Where above, an API call always starts as asyncio, flows through the synchronous API, and ends as asyncio, before results are propagated through this same chain in the opposite direction. In between, the message is adapted first into sync-style API use, and then back out to async style. Event hooks then by their nature occur in the middle of the “sync-style API use”. From this it follows that the API presented within event hooks occurs inside the process by which asyncio API requests have been adapted to sync, and outgoing messages to the database API will be converted to asyncio transparently.
As discussed in the above section, event handlers such as those oriented
around the PoolEvents
event handlers receive a sync-style “DBAPI” connection,
which is a wrapper object supplied by SQLAlchemy asyncio dialects to adapt
the underlying asyncio “driver” connection into one that can be used by
SQLAlchemy’s internals. A special use case arises when the user-defined
implementation for such an event handler needs to make use of the
ultimate “driver” connection directly, using awaitable only methods on that
driver connection. One such example is the .set_type_codec()
method
supplied by the asyncpg driver.
To accommodate this use case, SQLAlchemy’s AdaptedConnection
class provides a method AdaptedConnection.run_async()
that allows
an awaitable function to be invoked within the “synchronous” context of
an event handler or other SQLAlchemy internal. This method is directly
analogous to the AsyncConnection.run_sync()
method that
allows a sync-style method to run under async.
AdaptedConnection.run_async()
should be passed a function that will
accept the innermost “driver” connection as a single argument, and return
an awaitable that will be invoked by the AdaptedConnection.run_async()
method. The given function itself does not need to be declared as async
;
it’s perfectly fine for it to be a Python lambda:
, as the return awaitable
value will be invoked after being returned:
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy import event
engine = create_async_engine(...)
@event.listens_for(engine.sync_engine, "connect")
def register_custom_types(dbapi_connection, ...):
dbapi_connection.run_async(
lambda connection: connection.set_type_codec('MyCustomType', encoder, decoder, ...)
)
Above, the object passed to the register_custom_types
event handler
is an instance of AdaptedConnection
, which provides a DBAPI-like
interface to an underlying async-only driver-level connection object.
The AdaptedConnection.run_async()
method then provides access to an
awaitable environment where the underlying driver level connection may be
acted upon.
New in version 1.4.30.
An application that makes use of multiple event loops, for example in the
uncommon case of combining asyncio with multithreading, should not share the
same AsyncEngine
with different event loops when using the
default pool implementation.
If an AsyncEngine
is be passed from one event loop to another,
the method AsyncEngine.dispose()
should be called before it’s
re-used on a new event loop. Failing to do so may lead to a RuntimeError
along the lines of
Task <Task pending ...> got Future attached to a different loop
If the same engine must be shared between different loop, it should be configured
to disable pooling using NullPool
, preventing the Engine
from using any connection more than once:
from sqlalchemy.pool import NullPool
engine = create_async_engine(
"postgresql+asyncpg://user:pass@host/dbname", poolclass=NullPool
)
The usage of async_scoped_session
is mostly similar to
scoped_session
. However, since there’s no “thread-local” concept in
the asyncio context, the “scopefunc” parameter must be provided to the
constructor:
from asyncio import current_task
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.asyncio import async_scoped_session
from sqlalchemy.ext.asyncio import AsyncSession
async_session_factory = sessionmaker(some_async_engine, class_=_AsyncSession)
AsyncSession = async_scoped_session(async_session_factory, scopefunc=current_task)
some_async_session = AsyncSession()
async_scoped_session
also includes proxy
behavior similar to that of scoped_session
, which means it can be
treated as a AsyncSession
directly, keeping in mind that
the usual await
keywords are necessary, including for the
async_scoped_session.remove()
method:
async def some_function(some_async_session, some_object):
# use the AsyncSession directly
some_async_session.add(some_object)
# use the AsyncSession via the context-local proxy
await AsyncSession.commit()
# "remove" the current proxied AsyncSession for the local context
await AsyncSession.remove()
New in version 1.4.19.
SQLAlchemy does not yet offer an asyncio version of the
Inspector
(introduced at Fine Grained Reflection with Inspector),
however the existing interface may be used in an asyncio context by
leveraging the AsyncConnection.run_sync()
method of
AsyncConnection
:
import asyncio
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import inspect
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test"
)
def use_inspector(conn):
inspector = inspect(conn)
# use the inspector
print(inspector.get_view_names())
# return any value to the caller
return inspector.get_table_names()
async def async_main():
async with engine.connect() as conn:
tables = await conn.run_sync(use_inspector)
asyncio.run(async_main())
Object Name | Description |
---|---|
async_engine_from_config(configuration[, prefix], **kwargs) |
Create a new AsyncEngine instance using a configuration dictionary. |
An asyncio proxy for a |
|
An asyncio proxy for a |
|
An asyncio proxy for a |
|
create_async_engine(*arg, **kw) |
Create a new async engine instance. |
Create a new async engine instance.
Arguments passed to create_async_engine()
are mostly
identical to those passed to the create_engine()
function.
The specified dialect must be an asyncio-compatible dialect
such as asyncpg.
New in version 1.4.
Create a new AsyncEngine instance using a configuration dictionary.
This function is analogous to the engine_from_config()
function
in SQLAlchemy Core, except that the requested dialect must be an
asyncio-compatible dialect such as asyncpg.
The argument signature of the function is identical to that
of engine_from_config()
.
New in version 1.4.29.
An asyncio proxy for a Engine
.
AsyncEngine
is acquired using the
create_async_engine()
function:
from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")
New in version 1.4.
Class signature
class sqlalchemy.ext.asyncio.AsyncEngine
(sqlalchemy.ext.asyncio.base.ProxyComparable
, sqlalchemy.ext.asyncio.AsyncConnectable
)
sqlalchemy.ext.asyncio.AsyncEngine.
begin()¶Return a context manager which when entered will deliver an
AsyncConnection
with an
AsyncTransaction
established.
E.g.:
async with async_engine.begin() as conn:
await conn.execute(
text("insert into table (x, y, z) values (1, 2, 3)")
)
await conn.execute(text("my_special_procedure(5)"))
sqlalchemy.ext.asyncio.AsyncEngine.
clear_compiled_cache()¶Clear the compiled cache associated with the dialect.
Proxied for the Engine
class on behalf of the AsyncEngine
class.
This applies only to the built-in cache that is established
via the create_engine.query_cache_size
parameter.
It will not impact any dictionary caches that were passed via the
Connection.execution_options.query_cache
parameter.
New in version 1.4.
sqlalchemy.ext.asyncio.AsyncEngine.
connect()¶Return an AsyncConnection
object.
The AsyncConnection
will procure a database
connection from the underlying connection pool when it is entered
as an async context manager:
async with async_engine.connect() as conn:
result = await conn.execute(select(user_table))
The AsyncConnection
may also be started outside of a
context manager by invoking its AsyncConnection.start()
method.
sqlalchemy.ext.asyncio.AsyncEngine.
async dispose()¶Dispose of the connection pool used by this
AsyncEngine
.
This will close all connection pool connections that are
currently checked in. See the documentation for the underlying
Engine.dispose()
method for further notes.
See also
Engine.dispose()
sqlalchemy.ext.asyncio.AsyncEngine.
execution_options(**opt)¶Return a new AsyncEngine
that will provide
AsyncConnection
objects with the given execution
options.
Proxied from Engine.execution_options()
. See that
method for details.
sqlalchemy.ext.asyncio.AsyncEngine.
get_execution_options()¶Get the non-SQL options which will take effect during execution.
Proxied for the Engine
class on behalf of the AsyncEngine
class.
See also
sqlalchemy.ext.asyncio.AsyncEngine.
async raw_connection()¶Return a “raw” DBAPI connection from the connection pool.
sqlalchemy.ext.asyncio.AsyncEngine.
sync_engine: sqlalchemy.future.engine.Engine¶Reference to the sync-style Engine
this
AsyncEngine
proxies requests towards.
This instance can be used as an event target.
sqlalchemy.ext.asyncio.AsyncEngine.
update_execution_options(**opt)¶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()
.
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
)
sqlalchemy.ext.asyncio.AsyncConnection.
begin()¶Begin a transaction prior to autobegin occurring.
sqlalchemy.ext.asyncio.AsyncConnection.
begin_nested()¶Begin a nested transaction and return a transaction handle.
sqlalchemy.ext.asyncio.AsyncConnection.
async close()¶Close this AsyncConnection
.
This has the effect of also rolling back the transaction if one is in place.
sqlalchemy.ext.asyncio.AsyncConnection.
async commit()¶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.
sqlalchemy.ext.asyncio.AsyncConnection.
connection¶Not implemented for async; call
AsyncConnection.get_raw_connection()
.
sqlalchemy.ext.asyncio.AsyncConnection.
async exec_driver_sql(statement, parameters=None, execution_options={})¶Executes a driver-level SQL string and return buffered
Result
.
sqlalchemy.ext.asyncio.AsyncConnection.
async execute(statement, parameters=None, execution_options={})¶Executes a SQL statement construct and return a buffered
Result
.
object¶ –
The statement to be executed. This is always
an object that is in both the ClauseElement
and
Executable
hierarchies, including:
DDL
and objects which inherit from
DDLElement
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()
.
a Result
object.
sqlalchemy.ext.asyncio.AsyncConnection.
async execution_options(**opt)¶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.
sqlalchemy.ext.asyncio.AsyncConnection.
get_nested_transaction()¶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.
sqlalchemy.ext.asyncio.AsyncConnection.
async get_raw_connection()¶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.
sqlalchemy.ext.asyncio.AsyncConnection.
get_transaction()¶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.
sqlalchemy.ext.asyncio.AsyncConnection.
in_nested_transaction()¶Return True if a transaction is in progress.
New in version 1.4.0b2.
sqlalchemy.ext.asyncio.AsyncConnection.
in_transaction()¶Return True if a transaction is in progress.
New in version 1.4.0b2.
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.
sqlalchemy.ext.asyncio.AsyncConnection.
async invalidate(exception=None)¶Invalidate the underlying DBAPI connection associated with
this Connection
.
See the method Connection.invalidate()
for full
detail on this method.
sqlalchemy.ext.asyncio.AsyncConnection.
async rollback()¶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.
sqlalchemy.ext.asyncio.AsyncConnection.
async run_sync(fn, *arg, **kw)¶Invoke the given sync callable passing self as the first argument.
This method maintains the asyncio event loop all the way through to the database connection by running the given callable in a specially instrumented greenlet.
E.g.:
with 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.
sqlalchemy.ext.asyncio.AsyncConnection.
async scalar(statement, parameters=None, execution_options={})¶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.
a scalar Python value representing the first column of the first row returned.
sqlalchemy.ext.asyncio.AsyncConnection.
async scalars(statement, parameters=None, execution_options={})¶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.
a ScalarResult
object.
New in version 1.4.24.
sqlalchemy.ext.asyncio.AsyncConnection.
async start(is_ctxmanager=False)¶Start this AsyncConnection
object’s context
outside of using a Python with:
block.
sqlalchemy.ext.asyncio.AsyncConnection.
async stream(statement, parameters=None, execution_options={})¶Execute a statement and return a streaming
AsyncResult
object.
sqlalchemy.ext.asyncio.AsyncConnection.
async stream_scalars(statement, parameters=None, execution_options={})¶Executes a SQL statement and returns a streaming scalar result object.
This method is shorthand for invoking the
AsyncResult.scalars()
method after invoking the
Connection.stream()
method. Parameters are equivalent.
an AsyncScalarResult
object.
New in version 1.4.24.
sqlalchemy.ext.asyncio.AsyncConnection.
sync_connection: sqlalchemy.future.engine.Connection¶Reference to the sync-style Connection
this
AsyncConnection
proxies requests towards.
This instance can be used as an event target.
sqlalchemy.ext.asyncio.AsyncConnection.
sync_engine: sqlalchemy.future.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.
An asyncio proxy for a Transaction
.
Class signature
class sqlalchemy.ext.asyncio.AsyncTransaction
(sqlalchemy.ext.asyncio.base.ProxyComparable
, sqlalchemy.ext.asyncio.base.StartableContext
)
sqlalchemy.ext.asyncio.AsyncTransaction.
async close()¶Close this Transaction
.
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.
sqlalchemy.ext.asyncio.AsyncTransaction.
async commit()¶Commit this Transaction
.
sqlalchemy.ext.asyncio.AsyncTransaction.
async rollback()¶Roll back this Transaction
.
sqlalchemy.ext.asyncio.AsyncTransaction.
async start(is_ctxmanager=False)¶Start this AsyncTransaction
object’s context
outside of using a Python with:
block.
The AsyncResult
object is an async-adapted version of the
Result
object. It is only returned when using the
AsyncConnection.stream()
or AsyncSession.stream()
methods, which return a result object that is on top of an active database
cursor.
Object Name | Description |
---|---|
A wrapper for a |
|
An asyncio wrapper around a |
|
A wrapper for a |
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.
Class signature
class sqlalchemy.ext.asyncio.AsyncResult
(sqlalchemy.ext.asyncio.AsyncCommon
)
sqlalchemy.ext.asyncio.AsyncResult.
async all()¶Return all rows in a list.
Closes the result set after invocation. Subsequent invocations will return an empty list.
a list of Row
objects.
sqlalchemy.ext.asyncio.AsyncResult.
columns(*col_expressions)¶Establish the columns that should be returned in each row.
Refer to Result.columns()
in the synchronous
SQLAlchemy API for a complete behavioral description.
sqlalchemy.ext.asyncio.AsyncResult.
async fetchmany(size=None)¶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.
a list of Row
objects.
See also
sqlalchemy.ext.asyncio.AsyncResult.
async fetchone()¶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
Result.first()
method. To iterate through all
rows, iterate the Result
object directly.
a Row
object if no filters are applied, or None
if no rows remain.
sqlalchemy.ext.asyncio.AsyncResult.
async first()¶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()
.
a Row
object, or None
if no rows remain.
sqlalchemy.ext.asyncio.AsyncResult.
async freeze()¶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.
sqlalchemy.ext.asyncio.AsyncResult.
keys()¶Return the Result.keys()
collection from the
underlying Result
.
sqlalchemy.ext.asyncio.AsyncResult.
mappings()¶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.
Refer to Result.mappings()
in the synchronous
SQLAlchemy API for a complete behavioral description.
a new AsyncMappingResult
filtering object
referring to the underlying Result
object.
sqlalchemy.ext.asyncio.AsyncResult.
merge(*others)¶Merge this AsyncResult
with other compatible result
objects.
The object returned is an instance of MergedResult
,
which will be composed of iterators from the given result
objects.
The new result will use the metadata from this result object. The subsequent result objects must be against an identical set of result / cursor metadata, otherwise the behavior is undefined.
sqlalchemy.ext.asyncio.AsyncResult.
async one()¶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.
The first Row
.
sqlalchemy.ext.asyncio.AsyncResult.
async one_or_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.
The first Row
or None if no row is available.
sqlalchemy.ext.asyncio.AsyncResult.
async partitions(size=None)¶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)
See also
sqlalchemy.ext.asyncio.AsyncResult.
async scalar()¶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.
a Python scalar value , or None if no rows remain.
sqlalchemy.ext.asyncio.AsyncResult.
async scalar_one()¶Return exactly one scalar result or raise an exception.
This is equivalent to calling AsyncResult.scalars()
and
then AsyncResult.one()
.
sqlalchemy.ext.asyncio.AsyncResult.
async scalar_one_or_none()¶Return exactly one or no scalar result.
This is equivalent to calling AsyncResult.scalars()
and
then AsyncResult.one_or_none()
.
sqlalchemy.ext.asyncio.AsyncResult.
scalars(index=0)¶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.
index¶ – integer or row key indicating the column to be fetched
from each row, defaults to 0
indicating the first column.
a new AsyncScalarResult
filtering object
referring to this AsyncResult
object.
sqlalchemy.ext.asyncio.AsyncResult.
unique(strategy=None)¶Apply unique filtering to the objects returned by this
AsyncResult
.
Refer to Result.unique()
in the synchronous
SQLAlchemy API for a complete behavioral description.
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.
Class signature
class sqlalchemy.ext.asyncio.AsyncScalarResult
(sqlalchemy.ext.asyncio.AsyncCommon
)
sqlalchemy.ext.asyncio.AsyncScalarResult.
async all()¶Return all scalar values in a list.
Equivalent to AsyncResult.all()
except that
scalar values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncScalarResult.
async fetchall()¶A synonym for the AsyncScalarResult.all()
method.
sqlalchemy.ext.asyncio.AsyncScalarResult.
async fetchmany(size=None)¶Fetch many objects.
Equivalent to AsyncResult.fetchmany()
except that
scalar values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncScalarResult.
async first()¶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.
sqlalchemy.ext.asyncio.AsyncScalarResult.
async one()¶Return exactly one object or raise an exception.
Equivalent to AsyncResult.one()
except that
scalar values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncScalarResult.
async one_or_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.
sqlalchemy.ext.asyncio.AsyncScalarResult.
async partitions(size=None)¶Iterate through sub-lists of elements of the size given.
Equivalent to AsyncResult.partitions()
except that
scalar values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncScalarResult.
unique(strategy=None)¶Apply unique filtering to the objects returned by this
AsyncScalarResult
.
See AsyncResult.unique()
for usage details.
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.
Class signature
class sqlalchemy.ext.asyncio.AsyncMappingResult
(sqlalchemy.ext.asyncio.AsyncCommon
)
sqlalchemy.ext.asyncio.AsyncMappingResult.
async all()¶Return all scalar values in a list.
Equivalent to AsyncResult.all()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
columns(*col_expressions)¶Establish the columns that should be returned in each row.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async fetchall()¶A synonym for the AsyncMappingResult.all()
method.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async fetchmany(size=None)¶Fetch many objects.
Equivalent to AsyncResult.fetchmany()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async fetchone()¶Fetch one object.
Equivalent to AsyncResult.fetchone()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async first()¶Fetch the first object or None if no object is present.
Equivalent to AsyncResult.first()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
keys()¶Return an iterable view which yields the string keys that would
be represented by each Row
.
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.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async one()¶Return exactly one object or raise an exception.
Equivalent to AsyncResult.one()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async one_or_none()¶Return at most one object or raise an exception.
Equivalent to AsyncResult.one_or_none()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
async partitions(size=None)¶Iterate through sub-lists of elements of the size given.
Equivalent to AsyncResult.partitions()
except that
mapping values, rather than Row
objects,
are returned.
sqlalchemy.ext.asyncio.AsyncMappingResult.
unique(strategy=None)¶Apply unique filtering to the objects returned by this
AsyncMappingResult
.
See AsyncResult.unique()
for usage details.
Object Name | Description |
---|---|
async_object_session(instance) |
Return the |
Provides scoped management of |
|
async_session(session) |
Return the |
Asyncio version of |
|
A wrapper for the ORM |
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.
instance¶ – an ORM mapped instance
an AsyncSession
object, or None
.
New in version 1.4.18.
Return the AsyncSession
which is proxying the given
Session
object, if any.
a AsyncSession
instance, or None
.
New in version 1.4.18.
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
(sqlalchemy.orm.scoping.ScopedSessionMixin
)
sqlalchemy.ext.asyncio.async_scoped_session.
__call__(**kw)¶inherited from the sqlalchemy.orm.scoping.ScopedSessionMixin.__call__
method of ScopedSessionMixin
Return the current Session
, creating it
using the scoped_session.session_factory
if not present.
**kw¶ – Keyword arguments will be passed to the
scoped_session.session_factory
callable, if an existing
Session
is not present. If the Session
is present
and keyword arguments have been passed,
InvalidRequestError
is raised.
sqlalchemy.ext.asyncio.async_scoped_session.
__init__(session_factory, scopefunc)¶Construct a new async_scoped_session
.
session_factory¶ –
a factory to create new AsyncSession
instances. This is usually, but not necessarily, an instance
of sessionmaker
which itself was passed the
AsyncSession
to its sessionmaker.class_
parameter:
async_session_factory = sessionmaker(some_async_engine, class_= AsyncSession)
AsyncSession = async_scoped_session(async_session_factory, scopefunc=current_task)
scopefunc¶ – function which defines
the current scope. A function such as asyncio.current_task
may be useful here.
sqlalchemy.ext.asyncio.async_scoped_session.
add(instance, _warn=True)¶Place an object in the 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.
Its state will be persisted to the database on the next flush operation.
Repeated calls to add()
will be ignored. The opposite of add()
is expunge()
.
sqlalchemy.ext.asyncio.async_scoped_session.
add_all(instances)¶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.
sqlalchemy.ext.asyncio.async_scoped_session.
autoflush¶Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
sqlalchemy.ext.asyncio.async_scoped_session.
begin(**kw)¶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()
.
sqlalchemy.ext.asyncio.async_scoped_session.
begin_nested(**kw)¶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()
.
sqlalchemy.ext.asyncio.async_scoped_session.
close()¶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.
This expunges all ORM objects associated with this
AsyncSession
, ends any transaction in progress and
releases any AsyncConnection
objects which
this AsyncSession
itself has checked out from
associated AsyncEngine
objects. The operation then
leaves the AsyncSession
in a state which it may be
used again.
Tip
The AsyncSession.close()
method does not prevent
the Session from being used again. The
AsyncSession
itself does not actually have a
distinct “closed” state; it merely means the
AsyncSession
will release all database
connections and ORM objects.
See also
Closing - detail on the semantics of
AsyncSession.close()
sqlalchemy.ext.asyncio.async_scoped_session.
classmethod close_all()¶Close all AsyncSession
sessions.
Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
sqlalchemy.ext.asyncio.async_scoped_session.
commit()¶Commit the current transaction in progress.
Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
sqlalchemy.ext.asyncio.async_scoped_session.
configure(**kwargs)¶inherited from the ScopedSessionMixin.configure()
method of ScopedSessionMixin
reconfigure the sessionmaker
used by this
scoped_session
.
sqlalchemy.ext.asyncio.async_scoped_session.
connection(**kw)¶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”
sqlalchemy.ext.asyncio.async_scoped_session.
delete(instance)¶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
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.
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.
sqlalchemy.ext.asyncio.async_scoped_session.
execute(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶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
sqlalchemy.ext.asyncio.async_scoped_session.
expire(instance, attribute_names=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.
See also
Refreshing / Expiring - introductory material
sqlalchemy.ext.asyncio.async_scoped_session.
expire_all()¶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()
should not be needed when
autocommit is False
, assuming the transaction is isolated.
See also
Refreshing / Expiring - introductory material
sqlalchemy.ext.asyncio.async_scoped_session.
expunge(instance)¶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.
sqlalchemy.ext.asyncio.async_scoped_session.
expunge_all()¶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
.
sqlalchemy.ext.asyncio.async_scoped_session.
flush(objects=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
sqlalchemy.ext.asyncio.async_scoped_session.
get(entity, ident, options=None, populate_existing=False, with_for_update=None, identity_token=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
sqlalchemy.ext.asyncio.async_scoped_session.
get_bind(mapper=None, clause=None, bind=None, **kw)¶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.orm import Session, sessionmaker
# construct async engines w/ async drivers
engines = {
'leader':create_async_engine("sqlite+aiosqlite:///leader.db"),
'other':create_async_engine("sqlite+aiosqlite:///other.db"),
'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"),
'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"),
}
class RoutingSession(Session):
def get_bind(self, mapper=None, clause=None, **kw):
# within get_bind(), return sync engines
if mapper and issubclass(mapper.class_, MyOtherClass):
return engines['other'].sync_engine
elif self._flushing or isinstance(clause, (Update, Delete)):
return engines['leader'].sync_engine
else:
return engines[
random.choice(['follower1','follower2'])
].sync_engine
# apply to AsyncSession using sync_session_class
AsyncSessionMaker = sessionmaker(
class_=AsyncSession,
sync_session_class=RoutingSession
)
The 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.
sqlalchemy.ext.asyncio.async_scoped_session.
classmethod identity_key(*args, **kwargs)¶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()
.
sqlalchemy.ext.asyncio.async_scoped_session.
identity_map¶Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
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.
sqlalchemy.ext.asyncio.async_scoped_session.
invalidate()¶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()
.
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.
sqlalchemy.ext.asyncio.async_scoped_session.
is_modified(instance, include_collections=True)¶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 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()
.
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.
sqlalchemy.ext.asyncio.async_scoped_session.
merge(instance, load=True, options=None)¶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
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.
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.
sqlalchemy.ext.asyncio.async_scoped_session.
classmethod object_session(instance)¶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()
.
sqlalchemy.ext.asyncio.async_scoped_session.
refresh(instance, attribute_names=None, with_for_update=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
sqlalchemy.ext.asyncio.async_scoped_session.
async remove()¶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.
sqlalchemy.ext.asyncio.async_scoped_session.
rollback()¶Rollback the current transaction in progress.
Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
sqlalchemy.ext.asyncio.async_scoped_session.
scalar(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶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
sqlalchemy.ext.asyncio.async_scoped_session.
scalars(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return scalar results.
Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
a ScalarResult
object
New in version 1.4.24.
See also
Session.scalars()
- main documentation for scalars
AsyncSession.stream_scalars()
- streaming version
sqlalchemy.ext.asyncio.async_scoped_session.
stream(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
Execute a statement and return a streaming
AsyncResult
object.
sqlalchemy.ext.asyncio.async_scoped_session.
stream_scalars(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return a stream of scalar results.
Proxied for the AsyncSession
class on behalf of the async_scoped_session
class.
an AsyncScalarResult
object
New in version 1.4.24.
See also
Session.scalars()
- main documentation for scalars
AsyncSession.scalars()
- non streaming version
Asyncio version of Session
.
The AsyncSession
is a proxy for a traditional
Session
instance.
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
)
sqlalchemy.ext.asyncio.AsyncSession.
sync_session_class = <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.
sqlalchemy.ext.asyncio.AsyncSession.
__init__(bind=None, binds=None, sync_session_class=None, **kw)¶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.
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.
sqlalchemy.ext.asyncio.AsyncSession.
add(instance, _warn=True)¶Place an object in the Session
.
Proxied for the Session
class on behalf of the AsyncSession
class.
Its state will be persisted to the database on the next flush operation.
Repeated calls to add()
will be ignored. The opposite of add()
is expunge()
.
sqlalchemy.ext.asyncio.AsyncSession.
add_all(instances)¶Add the given collection of instances to this Session
.
Proxied for the Session
class on behalf of the AsyncSession
class.
sqlalchemy.ext.asyncio.AsyncSession.
begin(**kw)¶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()
.
sqlalchemy.ext.asyncio.AsyncSession.
begin_nested(**kw)¶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()
.
sqlalchemy.ext.asyncio.AsyncSession.
async close()¶Close out the transactional resources and ORM objects used by this
AsyncSession
.
This expunges all ORM objects associated with this
AsyncSession
, ends any transaction in progress and
releases any AsyncConnection
objects which
this AsyncSession
itself has checked out from
associated AsyncEngine
objects. The operation then
leaves the AsyncSession
in a state which it may be
used again.
Tip
The AsyncSession.close()
method does not prevent
the Session from being used again. The
AsyncSession
itself does not actually have a
distinct “closed” state; it merely means the
AsyncSession
will release all database
connections and ORM objects.
See also
Closing - detail on the semantics of
AsyncSession.close()
sqlalchemy.ext.asyncio.AsyncSession.
async classmethod close_all()¶Close all AsyncSession
sessions.
sqlalchemy.ext.asyncio.AsyncSession.
async commit()¶Commit the current transaction in progress.
sqlalchemy.ext.asyncio.AsyncSession.
async connection(**kw)¶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”
sqlalchemy.ext.asyncio.AsyncSession.
async delete(instance)¶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
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.
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.
sqlalchemy.ext.asyncio.AsyncSession.
async execute(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return a buffered
Result
object.
See also
Session.execute()
- main documentation for execute
sqlalchemy.ext.asyncio.AsyncSession.
expire(instance, attribute_names=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.
See also
Refreshing / Expiring - introductory material
sqlalchemy.ext.asyncio.AsyncSession.
expire_all()¶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()
should not be needed when
autocommit is False
, assuming the transaction is isolated.
See also
Refreshing / Expiring - introductory material
sqlalchemy.ext.asyncio.AsyncSession.
expunge(instance)¶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.
sqlalchemy.ext.asyncio.AsyncSession.
expunge_all()¶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
.
sqlalchemy.ext.asyncio.AsyncSession.
async flush(objects=None)¶Flush all the object changes to the database.
See also
Session.flush()
- main documentation for flush
sqlalchemy.ext.asyncio.AsyncSession.
async get(entity, ident, options=None, populate_existing=False, with_for_update=None, identity_token=None)¶Return an instance based on the given primary key identifier,
or None
if not found.
See also
Session.get()
- main documentation for get
sqlalchemy.ext.asyncio.AsyncSession.
get_bind(mapper=None, clause=None, bind=None, **kw)¶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.orm import Session, sessionmaker
# construct async engines w/ async drivers
engines = {
'leader':create_async_engine("sqlite+aiosqlite:///leader.db"),
'other':create_async_engine("sqlite+aiosqlite:///other.db"),
'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"),
'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"),
}
class RoutingSession(Session):
def get_bind(self, mapper=None, clause=None, **kw):
# within get_bind(), return sync engines
if mapper and issubclass(mapper.class_, MyOtherClass):
return engines['other'].sync_engine
elif self._flushing or isinstance(clause, (Update, Delete)):
return engines['leader'].sync_engine
else:
return engines[
random.choice(['follower1','follower2'])
].sync_engine
# apply to AsyncSession using sync_session_class
AsyncSessionMaker = sessionmaker(
class_=AsyncSession,
sync_session_class=RoutingSession
)
The 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.
sqlalchemy.ext.asyncio.AsyncSession.
get_nested_transaction()¶Return the current nested transaction in progress, if any.
an AsyncSessionTransaction
object, or
None
.
New in version 1.4.18.
sqlalchemy.ext.asyncio.AsyncSession.
get_transaction()¶Return the current root transaction in progress, if any.
an AsyncSessionTransaction
object, or
None
.
New in version 1.4.18.
sqlalchemy.ext.asyncio.AsyncSession.
classmethod identity_key(*args, **kwargs)¶Return an identity key.
Proxied for the Session
class on behalf of the AsyncSession
class.
This is an alias of identity_key()
.
sqlalchemy.ext.asyncio.AsyncSession.
in_nested_transaction()¶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.
sqlalchemy.ext.asyncio.AsyncSession.
in_transaction()¶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
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.
sqlalchemy.ext.asyncio.AsyncSession.
async invalidate()¶Close this Session, using connection invalidation.
For a complete description, see Session.invalidate()
.
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.
sqlalchemy.ext.asyncio.AsyncSession.
is_modified(instance, include_collections=True)¶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 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()
.
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.
sqlalchemy.ext.asyncio.AsyncSession.
async merge(instance, load=True, options=None)¶Copy the state of a given instance into a corresponding instance
within this AsyncSession
.
See also
Session.merge()
- main documentation for merge
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.
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.
sqlalchemy.ext.asyncio.AsyncSession.
classmethod object_session(instance)¶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()
.
sqlalchemy.ext.asyncio.AsyncSession.
async refresh(instance, attribute_names=None, with_for_update=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
sqlalchemy.ext.asyncio.AsyncSession.
async rollback()¶Rollback the current transaction in progress.
sqlalchemy.ext.asyncio.AsyncSession.
async run_sync(fn, *arg, **kw)¶Invoke the given sync callable passing sync self as the first argument.
This method maintains the asyncio event loop all the way through to the database connection by running the given callable in a specially instrumented greenlet.
E.g.:
with AsyncSession(async_engine) as session:
await session.run_sync(some_business_method)
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.
sqlalchemy.ext.asyncio.AsyncSession.
async scalar(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return a scalar result.
See also
Session.scalar()
- main documentation for scalar
sqlalchemy.ext.asyncio.AsyncSession.
async scalars(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return scalar results.
a ScalarResult
object
New in version 1.4.24.
See also
Session.scalars()
- main documentation for scalars
AsyncSession.stream_scalars()
- streaming version
sqlalchemy.ext.asyncio.AsyncSession.
async stream(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return a streaming
AsyncResult
object.
sqlalchemy.ext.asyncio.AsyncSession.
async stream_scalars(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶Execute a statement and return a stream of scalar results.
an AsyncScalarResult
object
New in version 1.4.24.
See also
Session.scalars()
- main documentation for scalars
AsyncSession.scalars()
- non streaming version
sqlalchemy.ext.asyncio.AsyncSession.
sync_session: sqlalchemy.orm.session.Session¶inherited from the builtins.object.sync_session
attribute of builtins.object
Reference to the underlying Session
this
AsyncSession
proxies requests towards.
This instance can be used as an event target.
A wrapper for the ORM SessionTransaction
object.
This object is provided so that a transaction-holding object
for the AsyncSession.begin()
may be returned.
The object supports both explicit calls to
AsyncSessionTransaction.commit()
and
AsyncSessionTransaction.rollback()
, as well as use as an
async context manager.
New in version 1.4.
Class signature
class sqlalchemy.ext.asyncio.AsyncSessionTransaction
(sqlalchemy.ext.asyncio.base.ReversibleProxy
, sqlalchemy.ext.asyncio.base.StartableContext
)
sqlalchemy.ext.asyncio.AsyncSessionTransaction.
async commit()¶Commit this AsyncTransaction
.
sqlalchemy.ext.asyncio.AsyncSessionTransaction.
async rollback()¶Roll back this AsyncTransaction
.
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 4.3.2.