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: object

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_authorizer(authorizer_callback)

Set an authorizer callback to control database access.

The authorizer callback is invoked for each SQL statement that is prepared, and controls whether specific operations are permitted.

Example:

import sqlite3

def restrict_drops(action_code, arg1, arg2, db_name, trigger_name):
    # Deny all DROP operations
    if action_code == sqlite3.SQLITE_DROP_TABLE:
        return sqlite3.SQLITE_DENY
    # Allow everything else
    return sqlite3.SQLITE_OK

await conn.set_authorizer(restrict_drops)

See sqlite3 documentation for details: https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.set_authorizer

Parameters:

authorizer_callback (Callable[[int, str, str, str, str], int] | None) –

An optional callable that receives five arguments:

• action_code (int): The action to be authorized (e.g., SQLITE_READ)

• arg1 (str): First argument, meaning depends on action_code

• arg2 (str): Second argument, meaning depends on action_code

• db_name (str): Database name (e.g., "main", "temp")

• trigger_name (str): Name of trigger or view that is doing the access, or None

The callback should return:

• SQLITE_OK (0): Allow the operation

• SQLITE_DENY (1): Deny the operation, raise sqlite3.DatabaseError

• SQLITE_IGNORE (2): Treat operation as no-op

Pass None to remove the authorizer.

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

stop()

Stop the background thread. Prefer async with or await close()

Return type:

Future | 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:

• conn (Connection)

• cursor (Cursor)

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.