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.
class DatabaseCacheBackend: (source)
Constructor: DatabaseCacheBackend(connection, table, lock_table)
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 | __current |
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 | __insert |
Insert a new cache row, falling back to an update on conflict. |
| Async Method | _ensure |
Create the cache and lock tables on first use, if missing. |
| Async Method | acquire |
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 | migrate |
Create the framework cache and lock tables without removing existing data. |
| Async Method | multi |
Return a list of values for keys in the same order. |
| Async Method | multi |
Store multiple key/value pairs with an optional shared TTL. |
| Async Method | release |
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__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | _connection |
Database connection used to store cache entries and locks. |
| Instance Variable | _entry |
Entry definition produced by _build_entries_table. |
| Instance Variable | _lock |
Lock definition produced by _build_locks_table. |
| Instance Variable | _lock |
Table name used to store atomic locks. Defaults to 'cache_locks' when not provided. |
| Instance Variable | _ready |
Ready flag used by DatabaseCacheBackend. |
| Instance Variable | _ready |
Synchronization primitive controlling access to ready lock. |
| Instance Variable | _table |
Table name used to store cache entries. |
Deserialize a stored JSON payload back into a Python object.
| Parameters | |
raw:str | bytes | None | Raw payload read from the cache_value column. |
| Returns | |
typing.Any | Decoded value, or None when raw is missing or invalid. |
Serialize value to a JSON string suitable for storage.
| Parameters | |
value:typing.Any | JSON-serializable value to encode. |
| Returns | |
str | UTF-8 decoded JSON payload. |
Initialize the backend bound to a connection and table names.
| Parameters | |
connection:orionis.database.contracts.IConnection | Database connection used to store cache entries and locks. |
table:str | Table name used to store cache entries. |
lockstr | None, optional | Table name used to store atomic locks. Defaults to 'cache_locks' when not provided. |
| Returns | |
None | No return value. |
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. |
| Raises | |
orionis.database.exceptions.QueryException | If insertion fails without an existing competing lock row. |
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:typing.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. |
orionis.database.QueryException | If the insert fails for any reason other than the key being already taken. |
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:typing.Any | Value returned when the key is not found or has expired. |
| Returns | |
typing.Any | Stored value or default. |
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 | |
orionis.database.QueryException | If contention prevents the update from landing after _INCREMENT_ATTEMPTS rounds. |
Create the framework cache and lock tables without removing existing data.
| Returns | |
None | No return value. |
| Raises | |
orionis.database.QueryException | If the connection cannot create either table. |
Return a list of values for keys in the same order.
| Parameters | |
keys:list[str] | Cache keys. |
default:typing.Any | Returned for each missing/expired key. |
| Returns | |
list[typing.Any] | Cached values in key order, using the supplied default for misses. |
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, typing.Any]] | Sequence of (key, value) pairs. |
ttl:float | None | Shared TTL applied to every pair. |
| Returns | |
bool | Always True. |
Replace a live cache row with a single conditional update.
| Parameters | |
key:str | Existing cache key. |
value:typing.Any | Replacement value. |
ttl:float | None | Replacement lifetime in seconds. |
| Returns | |
bool | False when the entry is missing or has expired. |
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:typing.Any | JSON-serializable value to cache. |
ttl:float | None | Time-to-live in seconds. None means no expiry. |
| Returns | |
bool | Always True. |
| Raises | |
orionis.database.exceptions.QueryException | If the row cannot be inserted or updated. |