aiosqlite

Async SQLite adapter using aiosqlite. Supports URI-based in-memory databases with per-config instance isolation.

Configuration

class sqlspec.adapters.aiosqlite.AiosqliteConfig

Bases: AsyncDatabaseConfig[AiosqliteConnection, AiosqliteConnectionPool, AiosqliteDriver]

Database configuration for AioSQLite engine.

driver_type

alias of AiosqliteDriver

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)

Initialize AioSQLite configuration.

Parameters:

• connection_config (AiosqlitePoolParams | dict[str, typing.Any] | None) – Connection and pool configuration parameters (TypedDict or dict)

• connection_instance (AiosqliteConnectionPool | None) – Optional pre-configured connection pool instance.

• migration_config (dict[str, typing.Any] | None) – Optional migration configuration.

• statement_config (StatementConfig | None) – Optional statement configuration.

• driver_features (AiosqliteDriverFeatures | dict[str, typing.Any] | None) – Optional driver feature configuration.

• bind_key (str | None) – Optional unique identifier for this configuration.

• extension_config (dict[str, dict[str, Any] | LitestarConfig | FastAPIConfig | StarletteConfig | FlaskConfig | ADKConfig | EventsConfig | OpenTelemetryConfig | PrometheusConfig] | None) – Extension-specific configuration (e.g., Litestar plugin settings)

• observability_config (ObservabilityConfig | None) – Adapter-level observability overrides for lifecycle hooks and observers

• **kwargs (Any) – Additional keyword arguments passed to the base configuration.

provide_connection(*args, **kwargs)

Provide an async connection context manager.

Parameters:

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Return type:

AiosqliteConnectionContext

Returns:

An aiosqlite connection context manager.

provide_session(*_args, statement_config=None, **_kwargs)

Provide an async driver session context manager.

Parameters:

• *_args (Any) – Additional arguments.

• statement_config (StatementConfig | None) – Optional statement configuration override.

• **_kwargs (Any) – Additional keyword arguments.

Return type:

AiosqliteSessionContext

Returns:

An AiosqliteDriver session context manager.

get_signature_namespace()

Get the signature namespace for AiosqliteConfig types.

Return type:

dict[str, typing.Any]

Returns:

Dictionary mapping type names to types.

async close_pool()

Close the connection pool.

Return type:

None

async create_connection()

Create a single async connection from the pool.

Return type:

Connection

Returns:

An aiosqlite connection instance.

async provide_pool()

Provide async pool instance.

Return type:

AiosqliteConnectionPool

Returns:

The async connection pool.

Driver

class sqlspec.adapters.aiosqlite.AiosqliteDriver

Bases: AsyncDriverAdapterBase

AIOSQLite driver for async SQLite database operations.

__init__(connection, statement_config=None, driver_features=None)

Initialize driver adapter with connection and configuration.

Parameters:

• connection (Connection) – Database connection instance

• statement_config (StatementConfig | None) – Statement configuration for the driver

• driver_features (dict[str, typing.Any] | None) – Driver-specific features like extensions, secrets, and connection callbacks

• observability – Optional runtime handling lifecycle hooks, observers, and spans

async dispatch_execute(cursor, statement)

Execute single SQL statement.

Return type:

ExecutionResult

async dispatch_execute_many(cursor, statement)

Execute SQL with multiple parameter sets.

Return type:

ExecutionResult

async dispatch_execute_script(cursor, statement)

Execute SQL script.

Return type:

ExecutionResult

async begin()

Begin a database transaction.

Return type:

None

async commit()

Commit the current transaction.

Return type:

None

async rollback()

Rollback the current transaction.

Return type:

None

with_cursor(connection)

Create async context manager for AIOSQLite cursor.

Return type:

AiosqliteCursor

handle_database_exceptions()

Handle AIOSQLite-specific exceptions.

Return type:

AiosqliteExceptionHandler

async select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)

Execute a query and stream Arrow results into storage.

Return type:

StorageBridgeJob

async load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)

Load Arrow data into SQLite using batched inserts.

async load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)

Load staged artifacts from storage into SQLite.

Return type:

StorageBridgeJob

property data_dictionary: AiosqliteDataDictionary

Get the data dictionary for this driver.

Returns:

Data dictionary instance for metadata queries

collect_rows(cursor, fetched)

Collect aiosqlite rows for the direct execution path.

Return type:

tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)

Resolve rowcount from aiosqlite cursor for the direct execution path.

Return type:

int

Connection Pool

class sqlspec.adapters.aiosqlite.pool.AiosqliteConnectionPool

Bases: object

Multi-connection pool for aiosqlite.

__init__(connection_parameters, pool_size=5, min_size=0, connect_timeout=30.0, idle_timeout=86400, operation_timeout=10.0, health_check_interval=30.0, on_connection_create=None)

Initialize connection pool.

Parameters:

• connection_parameters – SQLite connection parameters

• pool_size – Maximum number of connections in the pool

• min_size – Minimum connections to pre-create (pool warming)

• connect_timeout – Maximum time to wait for connection acquisition

• idle_timeout – Maximum time a connection can remain idle

• operation_timeout – Maximum time for connection operations

• health_check_interval – Seconds of idle time before running health check

• on_connection_create – Async callback executed when connection is created

property is_closed: bool

Check if pool is closed.

Returns:

True if pool is closed

size()

Get total number of connections in pool.

Return type:

int

Returns:

Total connection count

checked_out()

Get number of checked out connections.

Return type:

int

Returns:

Number of connections currently in use

async acquire()

Acquire a connection from the pool.

Return type:

AiosqlitePoolConnection

Returns:

Available connection

Raises:

AiosqliteConnectTimeoutError – If acquisition times out

async release(connection)

Release a connection back to the pool.

Parameters:

connection (AiosqlitePoolConnection) – Connection to release

Return type:

None

get_connection()

Get a connection with automatic release.

Return type:

AiosqlitePoolConnectionContext

async close()

Close the connection pool.

Return type:

None