SQL implementation of the key-value store client.
This client persists key-value data to a SQL database with transaction support and concurrent access safety. Keys are mapped to rows in database tables with proper indexing for efficient retrieval.
The key-value store data is stored in SQL database tables following the pattern:
key_value_storestable: Contains store metadata (id, name, timestamps)key_value_store_recordstable: Contains individual key-value pairs with binary value storage, content type, and size informationkey_value_store_metadata_buffertable: Buffers metadata updates for performance optimization
Values are serialized based on their type: JSON objects are stored as formatted JSON,
text values as UTF-8 encoded strings, and binary data as-is in the LargeBinary column.
The implementation automatically handles content type detection and maintains metadata
about each record including size and MIME type information.
All database operations are wrapped in transactions with proper error handling and rollback mechanisms. The client supports atomic upsert operations and handles race conditions when multiple clients access the same store using composite primary keys (key_value_store_id, key).
Hierarchy
- SqlClientMixin
- KeyValueStoreClient
- SqlKeyValueStoreClient
Index
Methods
__init__
- __init__(*, storage_client, id): None
Initialize a new instance.
Preferably use the
SqlKeyValueStoreClient.openclass method to create a new instance.Parameters
keyword-onlystorage_client: SqlStorageClient
keyword-onlyid: str
Returns None
delete_value
- async delete_value(*, key): None
Delete a value from the key-value store by its key.
The backend method for the
KeyValueStore.delete_valuecall.Parameters
keyword-onlykey: str
Returns None
drop
- async drop(): None
Delete this key-value store and all its records from the database.
This operation is irreversible. Uses CASCADE deletion to remove all related records.
Returns None
get_metadata
- async get_metadata(): KeyValueStoreMetadata
Get the metadata of the key-value store.
Returns KeyValueStoreMetadata
get_public_url
- async get_public_url(*, key): str
Get the public URL for the given key.
The backend method for the
KeyValueStore.get_public_urlcall.Parameters
keyword-onlykey: str
Returns str
get_session
- async get_session(*, with_simple_commit): AsyncGenerator[AsyncSession]
Create a new SQLAlchemy session for this storage.
Parameters
optionalkeyword-onlywith_simple_commit: bool = False
Returns AsyncGenerator[AsyncSession]
get_value
- async get_value(*, key): KeyValueStoreRecord | None
Retrieve the given record from the key-value store.
The backend method for the
KeyValueStore.get_valuecall.Parameters
keyword-onlykey: str
Returns KeyValueStoreRecord | None
iterate_entries
- async iterate_entries(*, exclusive_start_key, limit): AsyncIterator[KeyValueStoreRecord]
Iterate over all the existing records in the key-value store, including their values.
The records are read in keyset-paginated pages of metadata, and the values of each page are then fetched with a single query per batch, instead of one query per record as the default implementation does. The batches are bounded by the record sizes, so a store with large values does not load too many of them at once. Every query runs in its own short session, so no transaction stays open while the consumer processes the records.
Parameters
optionalkeyword-onlyexclusive_start_key: str | None = None
optionalkeyword-onlylimit: int | None = None
Returns AsyncIterator[KeyValueStoreRecord]
iterate_keys
- async iterate_keys(*, exclusive_start_key, limit): AsyncIterator[KeyValueStoreRecordMetadata]
Iterate over all the existing keys in the key-value store.
The backend method for the
KeyValueStore.iterate_keyscall.Parameters
optionalkeyword-onlyexclusive_start_key: str | None = None
optionalkeyword-onlylimit: int | None = None
Returns AsyncIterator[KeyValueStoreRecordMetadata]
open
- async open(*, id, name, alias, storage_client): Self
Open or create a SQL key-value store client.
This method attempts to open an existing key-value store from the SQL database. If a KVS with the specified ID or name exists, it loads the metadata from the database. If no existing store is found, a new one is created.
Parameters
keyword-onlyid: str | None
The ID of the key-value store to open. If provided, searches for existing store by ID.
keyword-onlyname: str | None
The name of the key-value store for named (global scope) storages.
keyword-onlyalias: str | None
The alias of the key-value store for unnamed (run scope) storages.
keyword-onlystorage_client: SqlStorageClient
The SQL storage client used to access the database.
Returns Self
An instance for the opened or created storage client.
purge
- async purge(): None
Remove all items from this key-value store while keeping the key-value store structure.
Remove all records from key_value_store_records table.
Returns None
record_exists
- async record_exists(*, key): bool
Check if a record with the given key exists in the key-value store.
The backend method for the
KeyValueStore.record_existscall.Parameters
keyword-onlykey: str
The key to check for existence.
Returns bool
True if a record with the given key exists, False otherwise.
set_value
- async set_value(*, key, value, content_type): None
Set a value in the key-value store by its key.
The backend method for the
KeyValueStore.set_valuecall.Parameters
keyword-onlykey: str
keyword-onlyvalue: Any
optionalkeyword-onlycontent_type: str | None = None
Returns None