Skip to content

aiosqlite Adapter

from sqlspec.adapters.aiosqlite import (
    AiosqliteConfig,
    AiosqliteConnectionParams,
    AiosqliteConnectionPool,
    AiosqliteDriver,
    AiosqliteDriverFeatures,
    AiosqliteExceptionHandler,
    AiosqlitePoolParams,
)

Asynchronous SQLite adapter built on aiosqlite. Inherited execution methods are documented on AsyncDriverAdapterBase. See the SQLite Setup Guide for async pool and shared-cache in-memory URI configuration.

Configuration & Parameters

AiosqliteConfig

Bases: AsyncDatabaseConfig['AiosqliteConnection', AiosqliteConnectionPool, AiosqliteDriver]

Database configuration for AioSQLite engine.

AiosqliteConnectionParams

Bases: TypedDict

TypedDict for aiosqlite connection parameters.

Attributes:

Name Type Description
database NotRequired[str | PathLike[str]]

Filesystem path, ':memory:', or file:... URI for the SQLite database.
timeout NotRequired[float]

Busy lock wait timeout in seconds passed to aiosqlite.connect.
detect_types NotRequired[int]

Bitmask of sqlite3.PARSE_DECLTYPES and sqlite3.PARSE_COLNAMES flags.
isolation_level NotRequired[SQLiteIsolationLevel]

Implicit transaction begin mode, or None for manual transaction management.
check_same_thread NotRequired[bool]

Restrict underlying sqlite3.Connection access to the aiosqlite worker thread.
factory NotRequired[AiosqliteConnectionFactory | None]

Custom sqlite3.Connection subclass instantiated on the worker thread.
cached_statements NotRequired[int]

Number of compiled SQLite VM statements cached per connection.
uri NotRequired[bool]

Interpret database as a SQLite file: URI supporting query parameters.
iter_chunk_size NotRequired[int]

Row batch size fetched per worker-thread hop when iterating aiosqlite cursors.
autocommit NotRequired[SQLiteAutocommitMode]

PEP 249 / Python 3.12+ autocommit flag or sqlite3.LEGACY_TRANSACTION_CONTROL (-1).

AiosqlitePoolParams

Bases: AiosqliteConnectionParams

TypedDict for aiosqlite pool parameters, inheriting connection parameters.

Attributes:

Name Type Description
pool_size NotRequired[int]

Maximum number of worker-backed SQLite connections managed by AiosqliteConnectionPool.
min_size NotRequired[int]

Minimum number of warm connections pre-opened in the pool.
connect_timeout NotRequired[float]

Maximum wait time in seconds when acquiring a connection from the pool.
idle_timeout NotRequired[float]

Idle duration in seconds before recycling unused pooled connections.
operation_timeout NotRequired[float]

Maximum duration in seconds allowed for pool lifecycle operations.
health_check_interval NotRequired[float]

Interval in seconds between background or checkout connection health checks.
enable_optimizations NotRequired[bool]

Apply WAL journal mode, synchronous=NORMAL, and busy-timeout PRAGMAs on connect.
enable_foreign_keys NotRequired[bool]

Execute PRAGMA foreign_keys = ON on every pooled connection (defaults to True).
extra NotRequired[dict[str, Any]]

Additional keyword arguments forwarded directly to aiosqlite.connect.

AiosqliteDriverFeatures

Bases: TypedDict

Optional aiosqlite driver feature flags, UDF registrations, PRAGMAs, and async hooks.

Attributes:

Name Type Description
enable_custom_adapters NotRequired[bool]

Register global sqlite3 module type adapters/converters (defaults to False).
json_serializer NotRequired[Callable[[Any], str]]

Custom JSON serializer used for bound parameters (defaults to to_json).
json_deserializer NotRequired[Callable[[str], Any]]

Custom JSON deserializer used for JSON column decoding (defaults to from_json).
on_connection_create NotRequired[Callable[[AiosqliteConnection], Awaitable[None]]]

Async hook invoked with each aiosqlite.Connection after PRAGMA initialization.
enable_events NotRequired[bool]

Enable durable table-backed SQLSpec event queue support.
events_backend NotRequired[Literal['poll_queue']]

Event channel backend (poll_queue is the sole SQLite backend).
custom_functions NotRequired[Sequence[AiosqliteFunctionConfig]]

Scalar SQL functions registered on the aiosqlite worker thread.
custom_collations NotRequired[Sequence[AiosqliteCollationConfig]]

Custom SQL collations registered on the aiosqlite worker thread.
custom_aggregates NotRequired[Sequence[AiosqliteAggregateConfig]]

Custom SQL aggregate classes registered on each connection.
custom_window_functions NotRequired[Sequence[AiosqliteWindowFunctionConfig]]

Custom SQL window function classes registered on each connection.
default_transaction_mode NotRequired[Literal['DEFERRED', 'IMMEDIATE', 'EXCLUSIVE']]

Default BEGIN locking mode used by begin() (DEFERRED, IMMEDIATE, or EXCLUSIVE).
authorizer_callback NotRequired[Callable[[int, str | None, str | None, str | None, str | None], int]]

SQLite compile-time authorizer callback executed on the worker thread.
trace_callback NotRequired[Callable[[str], None]]

Statement trace callback executed on the worker thread.
progress_handler NotRequired[Callable[[], int | None]]

SQLite VM progress hook invoked every progress_handler_interval opcodes.
progress_handler_interval NotRequired[int]

Positive VM opcode count between progress_handler invocations.
row_factory NotRequired[Literal['row', 'dict', 'tuple'] | Callable[..., Any]]

Raw connection row factory selector ('row', 'dict', 'tuple') or custom callable.
text_factory NotRequired[Callable[[bytes], Any]]

Decoder callable assigned to conn.text_factory for TEXT columns.
pragmas NotRequired[Mapping[str, str | int | bool]]

Additional PRAGMA key/value overrides applied after built-in optimizations.
extensions NotRequired[Sequence[str]]

Shared-library SQLite extension paths loaded on each connection.

Driver & Pool

AiosqliteDriver

Bases: AsyncDriverAdapterBase

AIOSQLite driver for async SQLite database operations.

AiosqliteExceptionHandler

Bases: BaseAsyncExceptionHandler

Async context manager for handling aiosqlite database exceptions.

Maps SQLite extended result codes to SQLSpec exceptions stored on pending_exception.

AiosqliteConnectionPool

Multi-connection pool for aiosqlite.

acquire 

acquire()

Acquire a connection from the pool.

Returns:

Type Description
AiosqlitePoolConnection

Available connection

Raises:

Type Description
AiosqliteConnectTimeoutError

If acquisition times out

release 

release(connection)

Release a connection back to the pool.

Parameters:

Name Type Description Default
connection AiosqlitePoolConnection

Connection to release

 required

size 

size()

Get total number of connections in pool.

Returns:

Type Description
int

Total connection count

Extension Stores

AiosqliteStore

Bases: BaseSQLSpecStore['AiosqliteConfig']

SQLite session store using AioSQLite driver.

Implements server-side session storage for Litestar using SQLite via the AioSQLite driver. Provides efficient session management with: - Native async SQLite operations - INSERT OR REPLACE for UPSERT functionality - Automatic expiration handling - Efficient cleanup of expired sessions

Parameters:

Name Type Description Default
config AiosqliteConfig

AiosqliteConfig instance.

 required

AiosqliteADKStore

Bases: BaseAsyncADKStore['AiosqliteConfig']

Aiosqlite ADK store using asynchronous SQLite driver.

Implements session and event storage for Google Agent Development Kit using SQLite via the asynchronous aiosqlite driver.

Provides
  • Session state management with JSON storage (as TEXT)
  • Event history tracking with full-event JSON storage
  • Julian Day timestamps (REAL) for efficient date operations
  • Foreign key constraints with cascade delete
  • Atomic event+state writes via append_event_and_update_state
  • PRAGMA optimization profile for file-based databases

Parameters:

Name Type Description Default
config AiosqliteConfig

AiosqliteConfig with extension_config["adk"] settings.

 required

AiosqliteADKMemoryStore

Bases: BaseAsyncADKMemoryStore['AiosqliteConfig']

Aiosqlite ADK memory store using asynchronous SQLite driver.

Implements memory entry storage for Google Agent Development Kit using SQLite via the asynchronous aiosqlite driver. Provides: - Session memory storage with JSON as TEXT - Simple LIKE search (simple strategy) - Optional FTS5 full-text search (sqlite_fts5 strategy) - Julian Day timestamps (REAL) for efficient date operations - Deduplication via event_id unique constraint - Efficient upserts using INSERT OR IGNORE

Parameters:

Name Type Description Default
config AiosqliteConfig

AiosqliteConfig with extension_config["adk"] settings.

 required

AiosqliteEventQueueStore

Bases: BaseEventQueueStore[AiosqliteConfig]

Provide column definitions for the async SQLite adapter.

SQLite stores JSON as TEXT since it lacks a native JSON column type. JSON functions can still operate on TEXT columns containing valid JSON.