Backends

ADK session/event and memory stores are implemented per adapter. Each backend has different capabilities for transactional state, event fidelity, and memory search. Use the support matrix below to select the right backend for your deployment.

Support Matrix

The table below classifies every backend by its ADK support level.

Adapter	Status	Session/Event	Memory (FTS)	Notes
asyncpg	Recommended	Full	Full	Best async PostgreSQL driver.
psycopg (async)	Recommended	Full	Full	Supports both sync and async modes.
psqlpy	Supported	Full	Full	Rust-backed PostgreSQL driver.
cockroach_asyncpg	Supported	Full	Full	CockroachDB with full FTS support.
cockroach_psycopg	Supported	Full	Full	CockroachDB with full FTS support.
aiomysql	Supported	Full	Full	MySQL/MariaDB async driver.
asyncmy	Supported	Full	Full	MySQL/MariaDB async driver.
mysqlconnector	Supported	Full	Full	MySQL/MariaDB sync driver.
pymysql	Supported	Full	Full	MySQL/MariaDB sync driver.
aiosqlite	Supported	Full	Full	Async local backend; single-writer limits still apply.
sqlite	Supported	Full	Full	SQLite sync with thread-local pools.
oracledb	Supported	Full	Full	Oracle Database driver.
db2	Supported	Full	Basic	IBM Db2 (LUW); POSSTR memory search.
duckdb	Reduced-scope	Full	Limited	Analytics-oriented; no concurrent writes.
adbc	Reduced-scope	Full	Basic	Arrow Database Connectivity across PostgreSQL, SQLite, DuckDB, BigQuery, Snowflake, Oracle, and IBM Db2.
mssql_python	Supported	Full	Basic	SQL Server through Microsoft's mssql-python driver; LIKE memory search.
pymssql	Supported	Full	Basic	SQL Server through FreeTDS; LIKE memory search.
arrow_odbc	Supported	Full	Basic	SQL Server through Microsoft ODBC Driver 18.
spanner	Supported	Full	Full	Google Cloud Spanner (cloud-managed; supports both sync and async modes).
bigquery	Supported (Analytics)	Replay / Search	N/A	Analytical warehouse store for telemetry replay and audit logs.

Status Definitions

Recommended

Production-grade, fully tested, actively optimized. Start here unless you have a specific reason not to.

Supported

Fully implemented and tested for session/event and memory operations.

Reduced-scope

Implemented with known limitations. Specific features may be absent or behave differently. See backend-specific notes.

Current scoped-state boundary

The shared session service strips temp: keys before persistence. app: keys are persisted in the app-scoped state table and user: keys are persisted in the user-scoped state table. Session-local keys remain in the session row. Loaded sessions merge those scopes back into the ADK state view.

Analytics Replica Stores

BigQuery is supported as an analytics-replica store (BigQueryADKStore) in sqlspec.adapters.bigquery.adk.store. BigQuery is an analytical data warehouse with query latency measured in seconds and without multi-statement ACID transactions. It is designed for historical analysis, session telemetry replay, audit logs, and search across recorded interactions. For low-latency live agent state, pair with an OLTP ADK backend such as Spanner, PostgreSQL, MySQL, or SQLite.

Artifact Storage

The ADK artifact service API and base metadata-store contracts are available in sqlspec.extensions.adk.artifact. Google Cloud Spanner provides concrete sync and async artifact metadata stores (SpannerSyncADKArtifactStore and SpannerAsyncADKArtifactStore) in sqlspec.adapters.spanner.adk.

Backend Details

PostgreSQL Family

PostgreSQL backends (asyncpg, psycopg, psqlpy) provide the fullest feature set:

• Native JSONB storage for session state and event JSON.

• Full-text search via tsvector for memory entries.

• UPSERT and RETURNING clauses for atomic operations.

• append_event_and_update_state() executes as a single transaction.

• fillfactor (default 80), autovacuum_vacuum_scale_factor, and autovacuum_analyze_scale_factor tune the generated tables.

Recommended for production deployments.

CockroachDB

CockroachDB backends (cockroach_asyncpg, cockroach_psycopg) provide full ADK support including full-text search. CockroachDB is a distributed SQL database compatible with the PostgreSQL wire protocol.

• Full FTS support for memory search.

• Distributed transactions for session and event atomicity.

• Horizontal scalability for high-throughput agent deployments.

• Optional table locality, hash-sharded indexes, storing indexes, and memory trigram indexes through the CockroachDB ADK configuration keys.

MySQL Family

MySQL backends (aiomysql, asyncmy, mysqlconnector, pymysql) provide full ADK support:

• JSON column storage for session state and event records.

• Full-text search on InnoDB tables for memory entries.

• Transactional writes for append_event_and_update_state().

• Per-table DDL suffixes for session, event, app-state, user-state, and memory tables through the corresponding *_table_options keys.

SQLite

SQLite backends (aiosqlite, sqlite) are the recommended local-file ADK backends for development, tests, and single-process deployments. Both adapters share the same DDL and store contract; they differ only in their connection model.

Supported behavior (both adapters):

• JSON1 extension for state and event storage.

• FTS5 virtual tables for memory full-text search, with optional tokenize='porter' stemming and detail='none' index reduction controlled by the ADK extension config.

• File-based or in-memory operation.

• Empty session state is persisted as JSON {}, not NULL. The store never serializes the empty-state value as None.

• append_event_and_update_state() writes the event row and the durable state snapshot in a single transaction and returns the updated session record without an extra get_session() round trip.

• WAL journaling and synchronous=NORMAL for file-based databases, with configurable busy_timeout, cache_size, mmap_size, and journal_size_limit PRAGMAs for local tuning.

sqlite vs aiosqlite boundary:

• sqlite (sqlspec.adapters.sqlite) is the synchronous adapter. ADK uses a thread-local connection pool and offloads each store call to a worker thread. Best suited for scripts, CLI utilities, test fixtures, and small embedded agents where async overhead is undesirable.

• aiosqlite (sqlspec.adapters.aiosqlite) is the native async adapter. ADK calls run directly on the event loop without thread offload. Best suited for single-process async ADK runners that already operate inside an async framework (Litestar, FastAPI, Starlette, etc.).

Both adapters use identical table schemas, so a SQLite database created by one adapter can be opened and read by the other without migration.

Unsupported lifecycle features:

• No native server-side partitioning, hash sharding, or table compression. The capability profile reports these as unsupported. If you need them, choose a server-backed adapter (PostgreSQL, MySQL, Oracle, Spanner).

• No concurrent writers. SQLite serializes writes at the file level; use a server-backed database for production multi-process or multi-writer deployments.

Note

The shared scoped-state contract for app: and user: keys is defined under the Support Matrix above. SQLite is not uniquely partial here — it follows the same shared behavior as every other ADK session store.

Oracle

Oracle Database (oracledb) provides full ADK support:

• Version-aware JSON storage: native JSON on Oracle 21c+, JSON-checked BLOB on older supported versions, and fallback BLOB storage where native validation is unavailable.

• Oracle Text CTXSYS.CONTEXT indexes with CONTAINS() and SCORE() ranking for memory entries.

• Optional in_memory table creation for deployments licensed and configured for Oracle Database In-Memory.

• Configurable table compression and hash/range partitioning for session, event, and memory tables.

• Capability checks are cached with the Oracle data dictionary. Explicitly requested but unavailable compression, partitioning, or In-Memory options are logged and omitted instead of surfacing a raw Oracle licensing error.

• Full transactional support for atomic operations.

DuckDB

DuckDB provides session and event storage but has limitations:

• Optimized for analytics, not OLTP workloads.

• Single-writer constraint limits concurrent access.

• Memory search capabilities are limited compared to server databases.

Best suited for analytics pipelines and offline agent evaluation.

ADBC

ADBC (Arrow Database Connectivity) provides a portable Arrow-native store (AdbcADKStore and AdbcADKMemoryStore):

• Dialect-aware DDL, parameter binding, and pagination for PostgreSQL, SQLite, DuckDB, BigQuery, Snowflake, Oracle (:1, :2 placeholders and PL/SQL idempotent DDL), and IBM Db2 (SYSCAT catalog guards and POSSTR memory search).

• Arrow-native data transfer for high-throughput event ingestion.

• Portable substring memory search across all supported ADBC dialects; choose a dedicated native adapter when you need backend-specific full-text search indexes or retention policies.

SQL Server (mssql-python and pymssql)

mssql_python and pymssql provide SQL Server-backed ADK storage:

• Session and event storage use SQL Server tables with DATETIME2(6) and NVARCHAR(MAX) JSON payload columns. Pass native_json=True when your SQL Server deployment and driver support native JSON columns.

• append_event_and_update_state() commits the session update, event row, and scoped state in one transaction.

• Memory search is LIKE-based across memory entries.

• Both stores are synchronous and require wrapping with anyio for async ADK runners.

arrow-odbc

arrow_odbc provides SQL Server-backed ADK storage through Microsoft ODBC Driver 18:

• Session and event storage use SQL Server tables with DATETIME2(6) and NVARCHAR(MAX) JSON payload columns.

• append_event_and_update_state() writes the session update, event row, and scoped state in one committed session.

• Memory storage uses the portable text-search path with LIKE matching.

• Row-oriented execute_many() is not available; use native Arrow ingest for bulk database writes outside the ADK store.

Spanner

Google Cloud Spanner provides globally distributed ADK storage in both native async (SpannerAsyncADKStore, SpannerAsyncADKMemoryStore, and SpannerAsyncADKArtifactStore) and sync (SpannerSyncADKStore, SpannerSyncADKMemoryStore, and SpannerSyncADKArtifactStore) modes:

• Cloud-managed, horizontally scalable with strong consistency across regions.

• Optional hash sharding via shard_count to reduce hot spots.

• Atomic batched memory deduplication via WHERE event_id IN UNNEST(@event_ids) inside a single run_in_transaction call backed by idx_{table}_event_id.

• Vector embeddings (embedding ARRAY<FLOAT32>) with optional CREATE VECTOR INDEX ... STORING (...) and 4-mode search_entries retrieval: Hybrid Reciprocal Rank Fusion (RRF, k=60) combining APPROX_COSINE_DISTANCE and SEARCH() / SCORE(), Vector-Only, Full-Text Search (ordered by SCORE(content_tokens, @query) DESC), and Simple LIKE fallback.

• Optional Spanner Property Graph DDL overlay (enable_memory_graph=True) defining CREATE OR REPLACE PROPERTY GRAPH over sessions and memories for GRAPH_TABLE Hybrid GraphRAG traversals.

• Concrete artifact metadata stores (adk_artifact) with composite primary key (app_name, user_id, session_id, filename, version) and automatic user-scoped session_id=None normalization.

• Explicit table/index option passthrough and native ROW DELETION POLICY TTL policies generated from ADK retention settings.

BigQuery (Analytics Replica)

BigQueryADKStore provides an analytics-replica path for ADK workloads:

• Designed for historical analysis, session telemetry replay, and audit logs.

• Queries partitions using configurable session_lookup_window_days (defaults to 30 days).

• Uses BigQueryADKConfig with optional BigQueryADKRetentionConfig for event TTL partitions.

• Ideal when paired with an operational OLTP store (such as Spanner or PostgreSQL) replicating to BigQuery.

Configuration

All backends are configured through extension_config["adk"]:

from sqlspec.adapters.asyncpg import AsyncpgConfig

config = AsyncpgConfig(
    connection_config={"dsn": "postgresql://localhost/mydb"},
    extension_config={
        "adk": {
            "session_table": "adk_session",
            "events_table": "adk_event",
            "memory_table": "adk_memory",
            "memory_use_fts": True,
            "owner_id_column": "tenant_id INTEGER NOT NULL",
        }
    },
)

Adapter-specific storage tuning uses that same adk mapping. SQLSpec validates the keys against the selected adapter and raises ImproperConfigurationError for unknown or unsupported options. This makes configuration mistakes visible at store construction instead of silently falling back to backend defaults.

The backend detail sections above describe the available controls where they matter: PostgreSQL table fillfactor and autovacuum settings; CockroachDB locality, hash-sharded indexes, and storing indexes; MySQL/MariaDB per-table options; SQLite PRAGMA and FTS controls; Oracle compression, partitioning, In-Memory, and per-table options; and Spanner sharding, retention, and table/index options. Oracle's deployment-dependent behavior is documented in Extension Table Storage Options.

See Adapters for adapter-specific configuration patterns.