sqlite Adapter¶
from sqlspec.adapters.sqlite import (
SqliteAggregateConfig,
SqliteCollationConfig,
SqliteConfig,
SqliteConnectionParams,
SqliteConnectionPool,
SqliteDriver,
SqliteDriverFeatures,
SqliteExceptionHandler,
SqliteFunctionConfig,
SqliteWindowFunctionConfig,
)
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, and the SQLite Data Dictionary & SQL Catalog.
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, |
timeout |
NotRequired[float]
|
Busy lock wait timeout in seconds passed to |
detect_types |
NotRequired[int]
|
Bitmask of |
isolation_level |
NotRequired[Literal['DEFERRED', 'IMMEDIATE', 'EXCLUSIVE'] | None]
|
Implicit transaction begin mode, or |
check_same_thread |
NotRequired[bool]
|
Restrict raw |
factory |
NotRequired[SqliteConnectionFactory | None]
|
Custom |
cached_statements |
NotRequired[int]
|
Number of compiled SQLite VM statements cached per connection by |
query_only |
NotRequired[bool]
|
Enforce read-only queries on every physical connection. |
uri |
NotRequired[bool]
|
Interpret |
autocommit |
NotRequired[SQLiteAutocommitMode]
|
PEP 249 / Python 3.12+ autocommit control flag or |
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 |
enable_optimizations |
NotRequired[bool]
|
Apply recommended SQLite |
enable_foreign_keys |
NotRequired[bool]
|
Execute |
extra |
NotRequired[dict[str, Any]]
|
Additional keyword arguments forwarded to |
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 |
json_serializer |
NotRequired[Callable[[Any], str]]
|
Custom JSON serializer used for bound parameters (defaults to |
json_deserializer |
NotRequired[Callable[[str], Any]]
|
Custom JSON deserializer used for JSON column decoding (defaults to |
on_connection_create |
NotRequired[Callable[[SqliteConnection], None]]
|
Synchronous hook called with each raw |
reset_session_on_release |
NotRequired[bool]
|
Drop temp objects, detach databases, and restore baseline PRAGMAs when a connection is released (defaults to |
enable_events |
NotRequired[bool]
|
Enable durable table-backed SQLSpec event queue support. |
events_backend |
NotRequired[Literal['poll_queue']]
|
Event channel backend ( |
custom_functions |
NotRequired[Sequence[SqliteFunctionConfig]]
|
Scalar SQL functions registered via |
custom_collations |
NotRequired[Sequence[SqliteCollationConfig]]
|
Custom string collations registered via |
custom_aggregates |
NotRequired[Sequence[SqliteAggregateConfig]]
|
Custom SQL aggregate classes registered via |
custom_window_functions |
NotRequired[Sequence[SqliteWindowFunctionConfig]]
|
Custom SQL window function classes registered via |
default_transaction_mode |
NotRequired[Literal['DEFERRED', 'IMMEDIATE', 'EXCLUSIVE']]
|
Default |
authorizer_callback |
NotRequired[Callable[[int, str | None, str | None, str | None, str | None], int]]
|
SQLite compile-time access control hook registered via |
trace_callback |
NotRequired[Callable[[str], None]]
|
Statement trace callback registered via |
progress_handler |
NotRequired[Callable[[], int | None]]
|
SQLite VM progress hook invoked every |
progress_handler_interval |
NotRequired[int]
|
Positive VM opcode count between |
row_factory |
NotRequired[Literal['row', 'dict', 'tuple'] | Callable[..., Any]]
|
Raw connection row factory selector ( |
text_factory |
NotRequired[Callable[[bytes], Any]]
|
Decoder callable assigned to |
pragmas |
NotRequired[Mapping[str, str | int | bool]]
|
Additional |
extensions |
NotRequired[Sequence[str]]
|
Shared-library SQLite extension paths loaded via |
SqliteFunctionConfig
¶
Bases: TypedDict
User-defined SQLite function registration.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
SQL function name registered on each SQLite connection. |
narg |
int
|
Expected positional argument count (use |
func |
Callable[..., Any]
|
Python callable invoked synchronously when the SQL function executes. |
deterministic |
NotRequired[bool]
|
Mark the function deterministic so SQLite can inline it in indexes and generated columns. |
SqliteCollationConfig
¶
Bases: TypedDict
User-defined SQLite collation registration.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
SQL collation name usable in |
func |
Callable[[str, str], int]
|
Comparator callable returning a negative, zero, or positive integer for two strings. |
SqliteAggregateConfig
¶
Bases: TypedDict
User-defined SQLite aggregate registration.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
SQL aggregate function name registered on each connection. |
narg |
int
|
Expected argument count passed to |
aggregate_class |
type[Any]
|
Class implementing |
SqliteWindowFunctionConfig
¶
Bases: TypedDict
User-defined SQLite window function registration.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
SQL window function name registered on each connection. |
narg |
int
|
Expected argument count passed to |
window_class |
type[Any]
|
Class implementing |
Driver, Pool & Data Dictionary¶
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.
SqliteDataDictionary
¶
Extension Stores & Configs¶
SqliteLitestarConfig
¶
Bases: LitestarConfig
Sqlite-specific Litestar settings.
Use inside extension_config["litestar"] with this adapter's session store.
Attributes:
| Name | Type | Description |
|---|---|---|
pragma_profile |
NotRequired[bool]
|
Apply the extension-store PRAGMA profile. Default: False. |
pragma_overrides |
NotRequired[dict[str, str | int | bool]]
|
Validated PRAGMA overrides applied during schema preparation. |
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 |
SqliteADKConfig
¶
Bases: ADKConfig
SQLite-specific ADK extension settings.
Use these keys inside extension_config["adk"] with SQLite ADK stores.
Attributes:
| Name | Type | Description |
|---|---|---|
pragma_overrides |
NotRequired[Mapping[str, str | int | bool]]
|
Additional validated PRAGMA settings applied after the built-in ADK profile. |
fts_tokenize |
NotRequired[str]
|
Optional FTS5 tokenizer spec used when |
fts_detail |
NotRequired[Literal['full', 'column', 'none']]
|
Optional FTS5 detail mode used when |
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 (app_name, user_id, event_id) unique constraint - Efficient upserts using INSERT OR IGNORE
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
SqliteConfig
|
SqliteConfig with extension_config["adk"] settings. |
required |
SqliteEventsConfig
¶
Bases: EventsConfig
Sqlite events settings for queue storage and supported native transports.
Attributes:
| Name | Type | Description |
|---|---|---|
pragma_profile |
NotRequired[bool]
|
Apply the SQLite extension-store PRAGMA profile. Default: False. |
pragma_overrides |
NotRequired[dict[str, str | int | bool]]
|
Validated SQLite PRAGMA overrides applied after the optional profile. |
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.