API Reference

class sqlalchemy_aio.base.AsyncEngine(pool, dialect, url, logging_name=None, echo=None, execution_options=None, **kwargs)

begin(close_with_result=False)

Like Engine.begin, but returns an asynchronous context manager.

Example

async with engine.begin():
    await engine.execute(...)

connect()

Like Engine.connect, but returns an awaitable that can also be used as an asynchronous context manager.

Examples

conn = await engine.connect()
await conn.execute(...)
await conn.close()

async with engine.connect() as conn:
    await conn.execute(...)

execute(*args, **kwargs)

Like Engine.execute, but is a coroutine that returns an AsyncioResultProxy.

Example

result = await engine.execute(...)
data = await result.fetchall()

Warning

Make sure to explicitly call AsyncioResultProxy.close() if the ResultProxy has pending rows remaining otherwise it will be closed during garbage collection. With SQLite, this will raise an exception since the DBAPI connection was created in a different thread.

has_table(table_name, schema=None)

Like Engine.has_table, but is a coroutine.

run_callable(callable_, *args, **kwargs)

Like Engine.run_callable.

Warning

This method blocks. It exists so that we can warn the user if they try to use an async engine for table reflection:

Table(..., autoload_with=engine)

run_in_thread(func, *args)

Run a synchronous function in the engine’s worker thread.

Example

The following blocking function:

some_fn(engine.sync_engine)

can be called like this instead:

await engine.run_in_thread(some_fn, engine.sync_engine)

Parameters:

• func – A synchronous function.
• args – Positional arguments to be passed to func. If you need to pass keyword arguments, then use functools.partial().

scalar(*args, **kwargs)

Like Connection.scalar, but is a coroutine.

sync_engine

Public property of the underlying SQLAlchemy engine.

table_names(schema=None, connection: Optional[sqlalchemy_aio.base.AsyncConnection] = None)

Like Engine.table_names, but is a coroutine.

class sqlalchemy_aio.base.AsyncConnection(connection, worker, engine)

Mostly like sqlalchemy.engine.Connection except some of the methods are coroutines.

begin()

Like Connection.begin, but returns an awaitable that can also be used as an asynchronous context manager.

Examples

async with conn.begin() as trans:
    await conn.execute(...)
    await conn.execute(...)

trans = await conn.begin():
await conn.execute(...)
await conn.execute(...)
await trans.commit()

begin_nested()

Like Connection.begin_nested, but returns an awaitable that can also be used as an asynchronous context manager.

See also

begin() for examples.

close(*args, **kwargs)

Like Connection.close, but is a coroutine.

closed

Like the Connection.closed attribute.

connect()

Like Connection.connect, but is a coroutine.

execute(*args, **kwargs)

Like Connection.execute, but is a coroutine that returns an AsyncioResultProxy.

Example

result = await conn.execute(...)
data = await result.fetchall()

Warning

Make sure to explicitly call AsyncioResultProxy.close() if the ResultProxy has pending rows remaining otherwise it will be closed during garbage collection. With SQLite, this will raise an exception since the DBAPI connection was created in a different thread.

in_transaction()

Like Connection.in_transaction.

run_callable(callable_, *args, **kwargs)

Like Connection.run_callable.

Warning

This method blocks. It exists so that we can warn the user if they try to use an async connection for table reflection:

Table(..., autoload_with=connection)

run_in_thread(func, *args)

Run a synchronous function in the connection’s worker thread.

Example

The following blocking function:

some_fn(conn.sync_connection)

can be called like this instead:

await engine.run_in_thread(some_fn, conn.sync_connection)

Parameters:

• func – A synchronous function.
• args – Positional arguments to be passed to func. If you need to pass keyword arguments, then use functools.partial().

scalar(*args, **kwargs)

Like Connection.scalar, but is a coroutine.

sync_connection

Public property of the underlying SQLAlchemy connection.

class sqlalchemy_aio.base.AsyncResultProxy(result_proxy, run_in_thread)

Mostly like sqlalchemy.engine.ResultProxy except some of the methods are coroutines.

close()

Like ResultProxy.close, but is a coroutine.

fetchall()

Like ResultProxy.fetchall, but is a coroutine.

fetchmany(size=None)

Like ResultProxy.fetchmany, but is a coroutine.

fetchone()

Like ResultProxy.fetchone, but is a coroutine.

first()

Like ResultProxy.first, but is a coroutine.

inserted_primary_key

Like the ResultProxy.inserted_primary_key attribute.

keys()

Like ResultProxy.keys, but is a coroutine.

returns_rows

Like the ResultProxy.returns_rows attribute.

rowcount

Like the ResultProxy.rowcount attribute.

scalar()

Like ResultProxy.scalar, but is a coroutine.

class sqlalchemy_aio.base.AsyncTransaction(transaction, run_in_thread)

Mostly like sqlalchemy.engine.Transaction except some of the methods are coroutines.

close()

Like Transaction.close, but is a coroutine.

commit()

Like Transaction.commit, but is a coroutine.

rollback()

Like Transaction.rollback, but is a coroutine.

class sqlalchemy_aio.asyncio.AsyncioEngine(pool, dialect, url, logging_name=None, echo=None, execution_options=None, **kwargs)

Mostly like sqlalchemy.engine.Engine except some of the methods are coroutines.

class sqlalchemy_aio.exc.AlreadyQuit

Raised by ThreadWorker if an attempt is made to use it after its thread has quit.

class sqlalchemy_aio.exc.BlockingWarning

Emitted when an AsyncEngine or AsyncConnection is used in a blocking fashion accidentally.

For example, it is emitted in this case:

engine = create_engine(..., strategy=TRIO_STRATEGY)
Table(..., autoload_with=engine)

class sqlalchemy_aio.exc.SQLAlchemyAioDeprecationWarning

Emitted for deprecated functionality.