SqlKeyValueStoreClient

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_stores table: Contains store metadata (id, name, timestamps)
• key_value_store_records table: Contains individual key-value pairs with binary value storage, content type, and size information

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

• KeyValueStoreClient
• SqlClientMixin
  • SqlKeyValueStoreClient

Index

Methods

• __init__
• delete_value
• drop
• get_metadata
• get_public_url
• get_session
• get_value
• iterate_keys
• open
• purge
• record_exists
• set_value

Methods

__init__

• __init__(*, storage_client, id): None

• Overrides SqlClientMixin.__init__

  Initialize a new instance.

  Preferably use the SqlKeyValueStoreClient.open class method to create a new instance.

  ---

  Parameters

  • keyword-onlystorage_client: SqlStorageClient

  • keyword-onlyid: str

  Returns None

delete_value

• async delete_value(*, key): None

• Overrides KeyValueStoreClient.delete_value

  Delete a value from the key-value store by its key.

  The backend method for the KeyValueStore.delete_value call.

  ---

  Parameters

  • keyword-onlykey: str

  Returns None

drop

• async drop(): None

• Overrides KeyValueStoreClient.drop

  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

• Overrides KeyValueStoreClient.get_metadata

  Get the metadata of the key-value store.

  ---

  Returns KeyValueStoreMetadata

get_public_url

• async get_public_url(*, key): str

• Overrides KeyValueStoreClient.get_public_url

  Get the public URL for the given key.

  The backend method for the KeyValueStore.get_public_url call.

  ---

  Parameters

  • keyword-onlykey: str

  Returns str

get_session

• async get_session(*, with_simple_commit): AsyncIterator[AsyncSession]

• Inherited from SqlClientMixin.get_session

  Create a new SQLAlchemy session for this storage.

  ---

  Parameters

  • optionalkeyword-onlywith_simple_commit: bool = False

  Returns AsyncIterator[AsyncSession]

get_value

• async get_value(*, key): KeyValueStoreRecord | None

• Overrides KeyValueStoreClient.get_value

  Retrieve the given record from the key-value store.

  The backend method for the KeyValueStore.get_value call.

  ---

  Parameters

  • keyword-onlykey: str

  Returns KeyValueStoreRecord | None

iterate_keys

• async iterate_keys(*, exclusive_start_key, limit): AsyncIterator[KeyValueStoreRecordMetadata]

• Overrides KeyValueStoreClient.iterate_keys

  Iterate over all the existing keys in the key-value store.

  The backend method for the KeyValueStore.iterate_keys call.

  ---

  Parameters

  • optionalkeyword-onlyexclusive_start_key: str | None = None

  • optionalkeyword-onlylimit: int | None = None

  Returns AsyncIterator[KeyValueStoreRecordMetadata]

open

• async open(*, id, name, alias, storage_client): SqlKeyValueStoreClient

• 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 SqlKeyValueStoreClient

purge

• async purge(): None

• Overrides KeyValueStoreClient.purge

  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

• Overrides KeyValueStoreClient.record_exists

  Check if a record with the given key exists in the key-value store.

  The backend method for the KeyValueStore.record_exists call.

  ---

  Parameters

  • keyword-onlykey: str

    The key to check for existence.

  Returns bool

set_value

• async set_value(*, key, value, content_type): None

• Overrides KeyValueStoreClient.set_value

  Set a value in the key-value store by its key.

  The backend method for the KeyValueStore.set_value call.

  ---

  Parameters

  • keyword-onlykey: str

  • keyword-onlyvalue: Any

  • optionalkeyword-onlycontent_type: str | None = None

  Returns None