orionis.cache.stores.database.DatabaseCacheBackend

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class DatabaseCacheBackend: (source)

Constructor: DatabaseCacheBackend(connection, table, lock_table)

View In Hierarchy

Cache backend that stores entries in a relational database table.

Mirrors database cache store: entries live in a dedicated table (cache_key / cache_value / expiration) resolved through the cache.stores.database configuration, and atomic locks used by Cache::lock() are kept in a separate cache_locks-like table so the database driver does not require Redis or Memcached to support locking.

Async Method	`__currentCounter`	Return the raw payload and integer value stored at key.
Method	`__decode`	Deserialize a stored JSON payload back into a Python object.
Method	`__encode`	Serialize value to a JSON string suitable for storage.
Method	`__init__`	Initialize the backend bound to a connection and table names.
Async Method	`__insertOrRetryUpdate`	Insert a new cache row, falling back to an update on conflict.
Async Method	`_ensureSchema`	Create the cache and lock tables on first use, if missing.
Async Method	`acquireLock`	Attempt to acquire the row-based lock for key in a single try.
Async Method	`add`	Store value under key only if the key does not already exist.
Async Method	`clear`	Remove all cache entries from the store table.
Async Method	`delete`	Remove key from the store.
Async Method	`exists`	Return True if key exists and has not expired.
Async Method	`get`	Return the cached value for key, or default when absent/expired.
Async Method	`increment`	Increment the integer stored at key by delta.
Async Method	`multiGet`	Return a list of values for keys in the same order.
Async Method	`multiSet`	Store multiple key/value pairs with an optional shared TTL.
Async Method	`releaseLock`	Release the row-based lock for key when still owned by owner.
Async Method	`replace`	Replace a live cache row with a single conditional update.
Async Method	`set`	Store value under key with an optional TTL in seconds.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_connection`	Undocumented
Instance Variable	`_lock_table`	Undocumented
Instance Variable	`_ready`	Undocumented
Instance Variable	`_ready_lock`	Undocumented
Instance Variable	`_table`	Undocumented

async def __currentCounter(self, key: str) -> tuple[str, int] | None: (source) ¶

Return the raw payload and integer value stored at key.

Parameters
key:`str`	Cache key.

Returns
`tuple[str, int] \| None`	The stored payload exactly as persisted, used later as the compare-and-swap witness, together with its integer value. `None` when the row is missing or already expired.

def __decode(self, raw: str | bytes | None) -> Any: (source) ¶

Deserialize a stored JSON payload back into a Python object.

Parameters
raw:`str \| bytes \| None`	Raw payload read from the `cache_value` column.

Returns
`Any`	Decoded value, or `None` when raw is missing or invalid.

def __encode(self, value: Any) -> str: (source) ¶

Serialize value to a JSON string suitable for storage.

Parameters
value:`Any`	JSON-serializable value to encode.

Returns
`str`	UTF-8 decoded JSON payload.

def __init__(self, connection: IConnection, table: str, lock_table: str | None = None): (source) ¶

Initialize the backend bound to a connection and table names.

Parameters
connection:`IConnection`	Database connection used to store cache entries and locks.
table:`str`	Table name used to store cache entries.
lock_table:`str \| None, optional`	Table name used to store atomic locks. Defaults to `'cache_locks'` when not provided.

Returns
`None`	Complete the documented operation without returning a value.

async def __insertOrRetryUpdate(self, key: str, encoded: str, expiration: float | None): (source) ¶

Insert a new cache row, falling back to an update on conflict.

Parameters
key:`str`	Cache key.
encoded:`str`	JSON-encoded value already serialized by `set`.
expiration:`float \| None`	Absolute expiration timestamp, or `None` for no expiry.

Returns
`None`	This method does not return a value.

async def _ensureSchema(self): (source) ¶

Create the cache and lock tables on first use, if missing.

Returns
`None`	This method does not return a value.

async def acquireLock(self, key: str, owner: str, lease: float) -> bool: (source) ¶

Attempt to acquire the row-based lock for key in a single try.

Inserts a fresh row for the lock, or steals an expired or self-owned row when the insert conflicts, mirroring DatabaseLock::acquire().

Parameters
key:`str`	Resource key to lock.
owner:`str`	Unique token identifying the caller attempting to acquire.
lease:`float`	Number of seconds the lock remains valid once acquired.

Returns
`bool`	True when the lock was acquired.

async def add(self, key: str, value: Any, ttl: float | None = None) -> bool: (source) ¶

Store value under key only if the key does not already exist.

The primary key decides the winner, so concurrent callers never both succeed and the operation is safe as a mutual-exclusion primitive.

Parameters
key:`str`	Cache key.
value:`Any`	Value to store.
ttl:`float \| None`	Optional TTL in seconds.

Returns
`bool`	True on success.

Raises
`ValueError`	If the key already exists and has not expired.
`QueryException`	If the insert fails for any reason other than the key being already taken.

async def clear(self) -> bool: (source) ¶

Remove all cache entries from the store table.

Returns
`bool`	Always True.

async def delete(self, key: str) -> int: (source) ¶

Remove key from the store.

Parameters
key:`str`	Cache key.

Returns
`int`	1 if the key existed, 0 otherwise.

async def exists(self, key: str) -> bool: (source) ¶

Return True if key exists and has not expired.

Parameters
key:`str`	Cache key.

Returns
`bool`	Undocumented

async def get(self, key: str, default: Any = None) -> Any: (source) ¶

Return the cached value for key, or default when absent/expired.

Expired entries are deleted on first read (lazy eviction), mirroring DatabaseStore::get().

Parameters
key:`str`	Cache key.
default:`Any`	Value returned when the key is not found or has expired.

Returns
`Any`	Stored value or default.

async def increment(self, key: str, delta: int = 1) -> int: (source) ¶

Increment the integer stored at key by delta.

Creates the key with value delta if it does not exist. The update is applied with a compare-and-swap so concurrent writers never lose an increment, without relying on row-locking syntax that not every dialect supports.

Parameters
key:`str`	Cache key.
delta:`int`	Amount to add (use negative values to decrement).

Returns
`int`	New value after increment.

Raises
`QueryException`	If contention prevents the update from landing after `_INCREMENT_ATTEMPTS` rounds.

async def multiGet(self, keys: list[str], default: Any = None) -> list[Any]: (source) ¶

Return a list of values for keys in the same order.

Parameters
keys:`list[str]`	Cache keys.
default:`Any`	Returned for each missing/expired key.

Returns
`list[Any]`	Undocumented

async def multiSet(self, pairs: list[tuple[str, Any]], ttl: float | None = None) -> bool: (source) ¶

Store multiple key/value pairs with an optional shared TTL.

Parameters
pairs:`list[tuple[str, Any]]`	Sequence of (key, value) pairs.
ttl:`float \| None`	Shared TTL applied to every pair.

Returns
`bool`	Always True.

async def releaseLock(self, key: str, owner: str): (source) ¶

Release the row-based lock for key when still owned by owner.

Parameters
key:`str`	Resource key to release.
owner:`str`	Token that must match the current row owner.

Returns
`None`	This method does not return a value.

async def replace(self, key: str, value: Any, ttl: float | None = None) -> bool: (source) ¶

Replace a live cache row with a single conditional update.

Parameters
key:`str`	Existing cache key.
value:`Any`	Replacement value.
ttl:`float \| None`	Replacement lifetime in seconds.

Returns
`bool`	False when the entry is missing or has expired.

async def set(self, key: str, value: Any, ttl: float | None = None) -> bool: (source) ¶

Store value under key with an optional TTL in seconds.

Updates the row when it already exists, otherwise inserts a new one, providing upsert semantics across every supported dialect without relying on driver-specific ON CONFLICT syntax.

Parameters
key:`str`	Cache key.
value:`Any`	JSON-serializable value to cache.
ttl:`float \| None`	Time-to-live in seconds. `None` means no expiry.

Returns
`bool`	Always True.

__slots__: tuple[str, ...] = (source) ¶

Undocumented

_connection = (source) ¶

Undocumented

_lock_table = (source) ¶

Undocumented

_ready: bool = (source) ¶

Undocumented

_ready_lock = (source) ¶

Undocumented

_table = (source) ¶

Undocumented