API Reference

Connection

aiosqlite.connect(database, *, iter_chunk_size=64, loop=None, **kwargs)

Create and return a connection proxy to the sqlite database.

Parameters:

  • database (str | Path)

  • loop (AbstractEventLoop | None)

  • kwargs (Any)

Return type:

Connection

class aiosqlite.Connection(connector, iter_chunk_size, loop=None)

Bases: Thread

Parameters:

  • connector (Callable[[], Connection])

  • iter_chunk_size (int)

  • loop (AbstractEventLoop | None)

async __aenter__()
Return type:

Connection

async __aexit__(exc_type, exc_val, exc_tb)
Return type:

None

__await__()
Return type:

Generator[Any, None, Connection]

async backup(target, *, pages=0, progress=None, name='main', sleep=0.25)

Make a backup of the current database to the target database.

Takes either a standard sqlite3 or aiosqlite Connection object as the target.

Parameters:

  • target (Connection | Connection)

  • pages (int)

  • progress (Callable[[int, int, int], None] | None)

  • name (str)

  • sleep (float)

Return type:

None

async close()

Complete queued queries/cursors and close the connection.

Return type:

None

async commit()

Commit the current transaction.

Return type:

None

async create_function(name, num_params, func, deterministic=False)

Create user-defined function that can be later used within SQL statements. Must be run within the same thread that query executions take place so instead of executing directly against the connection, we defer this to run function.

If deterministic is true, the created function is marked as deterministic, which allows SQLite to perform additional optimizations. This flag is supported by SQLite 3.8.3 or higher, NotSupportedError will be raised if used with older versions.

Parameters:

  • name (str)

  • num_params (int)

  • func (Callable)

  • deterministic (bool)

Return type:

None

cursor()

Create an aiosqlite cursor wrapping a sqlite3 cursor object.

Return type:

Cursor

async enable_load_extension(value)
Parameters:

value (bool)

Return type:

None

execute(sql, parameters=None)

Helper to create a cursor and execute the given query.

Parameters:

  • sql (str)

  • parameters (Iterable[Any] | None)

Return type:

Cursor

execute_fetchall(sql, parameters=None)

Helper to execute a query and return all the data.

Parameters:

  • sql (str)

  • parameters (Iterable[Any] | None)

Return type:

Iterable[Row]

execute_insert(sql, parameters=None)

Helper to insert and get the last_insert_rowid.

Parameters:

  • sql (str)

  • parameters (Iterable[Any] | None)

Return type:

Row | None

executemany(sql, parameters)

Helper to create a cursor and execute the given multiquery.

Parameters:

  • sql (str)

  • parameters (Iterable[Iterable[Any]])

Return type:

Cursor

executescript(sql_script)

Helper to create a cursor and execute a user script.

Parameters:

sql_script (str)

Return type:

Cursor

async interrupt()

Interrupt pending queries.

Return type:

None

async iterdump()

Return an async iterator to dump the database in SQL text format.

Example:

async for line in db.iterdump():
    ...
Return type:

AsyncIterator[str]

async load_extension(path)
Parameters:

path (str)

async rollback()

Roll back the current transaction.

Return type:

None

async set_progress_handler(handler, n)
Parameters:

  • handler (Callable[[], int | None])

  • n (int)

Return type:

None

async set_trace_callback(handler)
Parameters:

handler (Callable)

Return type:

None

property in_transaction: bool
property isolation_level: str | None
property row_factory: type | None
property text_factory: Callable[[bytes], Any]
property total_changes: int

Cursors

class aiosqlite.cursor.Cursor(conn, cursor)

Bases: object

Parameters:
async __aenter__()
async __aexit__(exc_type, exc_val, exc_tb)
__aiter__()

The cursor proxy is also an async iterator.

Return type:

AsyncIterator[Row]

async close()

Close the cursor.

Return type:

None

async execute(sql, parameters=None)

Execute the given query.

Parameters:

  • sql (str)

  • parameters (Iterable[Any] | None)

Return type:

Cursor

async executemany(sql, parameters)

Execute the given multiquery.

Parameters:

  • sql (str)

  • parameters (Iterable[Iterable[Any]])

Return type:

Cursor

async executescript(sql_script)

Execute a user script.

Parameters:

sql_script (str)

Return type:

Cursor

async fetchall()

Fetch all remaining rows.

Return type:

Iterable[Row]

async fetchmany(size=None)

Fetch up to cursor.arraysize number of rows.

Parameters:

size (int | None)

Return type:

Iterable[Row]

async fetchone()

Fetch a single row.

Return type:

Row | None

property arraysize: int
property connection: Connection
property description: tuple[tuple[str, None, None, None, None, None, None], ...]
property lastrowid: int | None
property row_factory: Callable[[Cursor, Row], object] | None
property rowcount: int

Errors

exception aiosqlite.Warning

Bases: Exception

exception aiosqlite.Error

Bases: Exception

exception aiosqlite.DatabaseError

Bases: Error

exception aiosqlite.IntegrityError

Bases: DatabaseError

exception aiosqlite.ProgrammingError

Bases: DatabaseError

exception aiosqlite.OperationalError

Bases: DatabaseError

exception aiosqlite.NotSupportedError

Bases: DatabaseError

Advanced

aiosqlite.register_adapter(type, adapter, /)

Register a function to adapt Python objects to SQLite values.

aiosqlite.register_converter(typename, converter, /)

Register a function to convert SQLite values to Python objects.