sqlalchemy.ext.asyncio.engine.AsyncConnection

class documentation

class AsyncConnection(ProxyComparable, StartableContext, AsyncConnectable):

An asyncio proxy for a _engine.Connection.

_asyncio.AsyncConnection is acquired using the _asyncio.AsyncEngine.connect method of _asyncio.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 Method	`_regenerate_proxy_for_target`	Undocumented
Async Method	`__aexit__`	Undocumented
Method	`__await__`	Undocumented
Method	`__init__`	Undocumented
Method	`_sync_connection`	Undocumented
Method	`begin`	Begin a transaction prior to autobegin occurring.
Method	`begin_nested`	Begin a nested transaction and return a transaction handle.
Async Method	`close`	Close this `_asyncio.AsyncConnection`.
Async Method	`commit`	Commit the transaction that is currently in progress.
Async Method	`exec_driver_sql`	Executes a driver-level SQL string and return buffered `_engine.Result`.
Async Method	`execute`	Executes a SQL statement construct and return a buffered `_engine.Result`.
Async Method	`execution_options`	Set non-SQL options for the connection which take effect during execution.
Async Method	`get_isolation_level`	Undocumented
Method	`get_nested_transaction`	Return an `.AsyncTransaction` representing the current nested (savepoint) transaction, if any.
Async Method	`get_raw_connection`	Return the pooled DBAPI-level connection in use by this `_asyncio.AsyncConnection`.
Method	`get_transaction`	Return an `.AsyncTransaction` representing the current transaction, if any.
Method	`in_nested_transaction`	Return True if a transaction is in progress.
Method	`in_transaction`	Return True if a transaction is in progress.
Async Method	`invalidate`	Invalidate the underlying DBAPI connection associated with this `_engine.Connection`.
Async Method	`rollback`	Roll back the transaction that is currently in progress.
Async Method	`run_sync`	Invoke the given sync callable passing self as the first argument.
Async Method	`scalar`	Executes a SQL statement construct and returns a scalar object.
Async Method	`scalars`	Executes a SQL statement construct and returns a scalar objects.
Async Method	`set_isolation_level`	Undocumented
Async Method	`start`	Start this `_asyncio.AsyncConnection` object's context outside of using a Python `with:` block.
Async Method	`stream`	Execute a statement and return a streaming `_asyncio.AsyncResult` object.
Async Method	`stream_scalars`	Executes a SQL statement and returns a streaming scalar result object.
Class Variable	`__slots__`	Undocumented
Instance Variable	`engine`	Undocumented
Instance Variable	`sync_connection`	Reference to the sync-style `_engine.Connection` this `_asyncio.AsyncConnection` proxies requests towards.
Instance Variable	`sync_engine`	Reference to the sync-style `_engine.Engine` this `_asyncio.AsyncConnection` is associated with via its underlying `_engine.Connection`.
Property	`_proxied`	Undocumented
Property	`connection`	Not implemented for async; call `_asyncio.AsyncConnection.get_raw_connection`.
Property	`info`	Return the `_engine.Connection.info` dictionary of the underlying `_engine.Connection`.

Inherited from ProxyComparable:

Method	`__eq__`	Undocumented
Method	`__hash__`	Undocumented
Method	`__ne__`	Undocumented

Inherited from ReversibleProxy (via ProxyComparable):

Class Method	`_retrieve_proxy_for_target`	Undocumented
Class Method	`_target_gced`	Undocumented
Method	`_assign_proxied`	Undocumented
Class Variable	`_proxy_objects`	Undocumented

Inherited from StartableContext:

Async Method	`__aenter__`	Undocumented
Method	`_raise_for_not_started`	Undocumented

@classmethod
def _regenerate_proxy_for_target(cls, target):

overrides sqlalchemy.ext.asyncio.base.ReversibleProxy._regenerate_proxy_for_target

Undocumented

async def __aexit__(self, type_, value, traceback):

overrides sqlalchemy.ext.asyncio.base.StartableContext.__aexit__

Undocumented

def __await__(self):

overrides sqlalchemy.ext.asyncio.base.StartableContext.__await__

Undocumented

def __init__(self, async_engine, sync_connection=None):

Undocumented

def _sync_connection(self):

Undocumented

def begin(self):

Begin a transaction prior to autobegin occurring.

def begin_nested(self):

Begin a nested transaction and return a transaction handle.

async def close(self):

Close this _asyncio.AsyncConnection.

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

async def commit(self):

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 _future.Connection automatically whenever a statement is first executed, or when the _future.Connection.begin method is called.

async def exec_driver_sql(self, statement, parameters=None, execution_options=util.EMPTY_DICT):

Executes a driver-level SQL string and return buffered _engine.Result.

async def execute(self, statement, parameters=None, execution_options=util.EMPTY_DICT):

Executes a SQL statement construct and return a buffered _engine.Result.

Parameters
statement	Undocumented
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 `_future.Connection.execution_options`.
object	The statement to be executed. This is always an object that is in both the `_expression.ClauseElement` and `_expression.Executable` hierarchies, including: `_expression.Select` `_expression.Insert`, `_expression.Update`, `_expression.Delete` `_expression.TextClause` and `_expression.TextualSelect` `_schema.DDL` and objects which inherit from `_schema.DDLElement`
Returns
a `_engine.Result` object.

async def execution_options(self, **opt):

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

This returns this _asyncio.AsyncConnection object with the new options added.

See _future.Connection.execution_options for full details on this method.

async def get_isolation_level(self):

Undocumented

def get_nested_transaction(self):

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

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

New in version 1.4.0b2.

async def get_raw_connection(self):

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

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

def get_transaction(self):

Return an .AsyncTransaction representing the current transaction, if any.

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

New in version 1.4.0b2.

def in_nested_transaction(self):

Return True if a transaction is in progress.

New in version 1.4.0b2.

def in_transaction(self):

Return True if a transaction is in progress.

New in version 1.4.0b2.

async def invalidate(self, exception=None):

Invalidate the underlying DBAPI connection associated with this _engine.Connection.

See the method _engine.Connection.invalidate for full detail on this method.

async def rollback(self):

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 _future.Connection automatically whenever a statement is first executed, or when the _future.Connection.begin method is called.

async def run_sync(self, 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.

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