sqlite Adapter¶

from sqlspec.adapters.sqlite import (
    SqliteConfig,
    SqliteConnectionParams,
    SqliteConnectionPool,
    SqliteDriver,
    SqliteDriverFeatures,
    SqliteExceptionHandler,
)

Synchronous SQLite adapter built on Python's standard library sqlite3 with thread-local connection pooling and WAL pragma helpers. Inherited execution methods are documented on SyncDriverAdapterBase. See the SQLite Setup Guide for in-memory URI and WAL configuration.

Configuration & Parameters¶

SqliteConfig ¶

Bases: SyncDatabaseConfig[SqliteConnection, SqliteConnectionPool, SqliteDriver]

SQLite configuration with thread-local connections.

`SqliteConnectionParams` ¶

Bases: TypedDict

SQLite 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 `sqlite3.connect`.
`detect_types`	`NotRequired[int]`	Bitmask of `sqlite3.PARSE_DECLTYPES` and `sqlite3.PARSE_COLNAMES` flags.
`isolation_level`	`NotRequired[Literal['DEFERRED', 'IMMEDIATE', 'EXCLUSIVE'] \| None]`	Implicit transaction begin mode, or `None` for manual/autocommit control.
`check_same_thread`	`NotRequired[bool]`	Restrict raw `sqlite3.Connection` usage to the creating OS thread.
`factory`	`NotRequired[SqliteConnectionFactory \| None]`	Custom `sqlite3.Connection` subclass passed to `sqlite3.connect`.
`cached_statements`	`NotRequired[int]`	Number of compiled SQLite VM statements cached per connection by `sqlite3`.
`uri`	`NotRequired[bool]`	Interpret `database` as a SQLite `file:` URI supporting query parameters.
`autocommit`	`NotRequired[SQLiteAutocommitMode]`	PEP 249 / Python 3.12+ autocommit control flag or `sqlite3.LEGACY_TRANSACTION_CONTROL` (`-1`).
`pool_recycle_seconds`	`NotRequired[int]`	Maximum connection age in seconds before recycling pooled SQLite connections.
`health_check_interval`	`NotRequired[float]`	Minimum interval in seconds between connection liveness probes in `SqliteConnectionPool`.
`enable_optimizations`	`NotRequired[bool]`	Apply recommended SQLite `PRAGMA` settings (WAL journal mode, synchronous=NORMAL, busy_timeout) on connect.
`enable_foreign_keys`	`NotRequired[bool]`	Execute `PRAGMA foreign_keys = ON` when initializing each connection (defaults to `True`).
`extra`	`NotRequired[dict[str, Any]]`	Additional keyword arguments forwarded to `sqlite3.connect`.

`SqliteDriverFeatures` ¶

Bases: TypedDict

Optional SQLite driver feature flags, UDF registrations, PRAGMAs, and connection 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[[SqliteConnection], None]]`	Synchronous hook called with each raw `sqlite3.Connection` after PRAGMA setup.
`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[SqliteFunctionConfig]]`	Scalar SQL functions registered via `conn.create_function` on each connection.
`custom_collations`	`NotRequired[Sequence[SqliteCollationConfig]]`	Custom string collations registered via `conn.create_collation` on each connection.
`custom_aggregates`	`NotRequired[Sequence[SqliteAggregateConfig]]`	Custom SQL aggregate classes registered via `conn.create_aggregate`.
`custom_window_functions`	`NotRequired[Sequence[SqliteWindowFunctionConfig]]`	Custom SQL window function classes registered via `conn.create_window_function`.
`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 access control hook registered via `conn.set_authorizer`.
`trace_callback`	`NotRequired[Callable[[str], None]]`	Statement trace callback registered via `conn.set_trace_callback`.
`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 connection optimizations.
`extensions`	`NotRequired[Sequence[str]]`	Shared-library SQLite extension paths loaded via `conn.load_extension`.

Driver & Pool¶

SqliteDriver ¶

Bases: SyncDriverAdapterBase

SQLite driver implementation.

Provides SQL statement execution, transaction management, and result handling for SQLite databases using the standard sqlite3 module.

SqliteExceptionHandler ¶

Bases: BaseSyncExceptionHandler

Context manager for handling SQLite database exceptions.

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

SqliteConnectionPool ¶

Thread-local connection manager for SQLite.

SQLite connections aren't thread-safe, so we use thread-local storage to ensure each thread has its own connection. This is simpler and more efficient than a traditional pool for SQLite's constraints.

acquire ¶

acquire()

Acquire a thread-local connection.

Returns:

Name	Type	Description
`SqliteConnection`	`SqliteConnection`	A thread-local connection

release ¶

release(connection)

Release a connection and roll back any uncommitted transaction.

Parameters:

Name	Type	Description	Default
`connection`	`SqliteConnection`	The connection to release	required

size ¶

size()

Get total number of active thread-local connections in pool.

Extension Stores¶

SQLiteStore ¶

Bases: BaseSQLSpecStore['SqliteConfig']

SQLite session store using synchronous SQLite driver.

Implements server-side session storage for Litestar using SQLite via the synchronous sqlite3 driver. Uses Litestar's sync_to_thread utility to provide an async interface compatible with the Store protocol.

Provides efficient session management with

Sync operations wrapped for async compatibility
INSERT OR REPLACE for UPSERT functionality
Automatic expiration handling
Efficient cleanup of expired sessions

Parameters:

Name	Type	Description	Default
`config`	`SqliteConfig`	SqliteConfig instance.	required

SqliteADKStore ¶

Bases: BaseSyncADKStore['SqliteConfig']

SQLite ADK store using synchronous SQLite driver.

Implements session and event storage for Google Agent Development Kit using SQLite via the synchronous sqlite3 driver. Uses Litestar's sync_to_thread utility to provide an async interface compatible with the Store protocol.

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`	`SqliteConfig`	SqliteConfig instance with extension_config["adk"] settings.	required

SqliteADKMemoryStore ¶

Bases: BaseSyncADKMemoryStore['SqliteConfig']

SQLite ADK memory store using synchronous SQLite driver.

Implements memory entry storage for Google Agent Development Kit using SQLite via the synchronous sqlite3 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`	`SqliteConfig`	SqliteConfig with extension_config["adk"] settings.	required

SqliteEventQueueStore ¶

Bases: BaseEventQueueStore[SqliteConfig]

Provide SQLite-specific column types for the events queue.

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

sqlite Adapter¶

Configuration & Parameters¶

SqliteConfig ¶

SqliteConnectionParams ¶

SqliteDriverFeatures ¶

Driver & Pool¶

SqliteDriver ¶

SqliteExceptionHandler ¶

SqliteConnectionPool ¶

acquire ¶

release ¶

size ¶

Extension Stores¶

SQLiteStore ¶

SqliteADKStore ¶

SqliteADKMemoryStore ¶

SqliteEventQueueStore ¶

`SqliteConnectionParams` ¶

`SqliteDriverFeatures` ¶