orionis.session.stores.database.DatabaseSessionStore

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 DatabaseSessionStore(ISessionStore): (source)

Constructor: DatabaseSessionStore(connection, table)

View In Hierarchy

Session store that persists each session as a row in a database table.

Mirrors orionis.cache.stores.database.DatabaseCacheBackend: records live in a dedicated table (id / payload / expires_at) resolved through the session.connection configuration, using upsert-by-retry semantics so no dialect-specific ON CONFLICT syntax is required.

Unlike the cache backend, a plain SQL table has no native TTL, so expired rows are evicted lazily on read and can be swept in bulk via gc.

Parameters
connection	Database connection used to persist session records.
table	Table name used to store session records. Defaults to `'sessions'`.

Method	`__decode`	Deserialize a stored JSON payload back into a Python dict.
Method	`__encode`	Serialize data to a JSON string suitable for storage.
Method	`__init__`	Bind the store to connection and the target table.
Async Method	`__insertOrRetryUpdate`	Insert a new session row, falling back to an update on conflict.
Async Method	`_ensureSchema`	Create the sessions table on first use, if missing.
Async Method	`delete`	Remove the record for session_id (no-op when absent).
Async Method	`gc`	Remove all rows whose `expires_at` is in the past.
Async Method	`read`	Return the stored record for session_id, or `None`.
Async Method	`update`	Update only a live session row with a single SQL statement.
Async Method	`write`	Insert or replace the record keyed by its identifier.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_connection`	Undocumented
Instance Variable	`_definition`	Undocumented
Instance Variable	`_ready`	Undocumented
Instance Variable	`_ready_lock`	Undocumented
Instance Variable	`_table`	Undocumented

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

Deserialize a stored JSON payload back into a Python dict.

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

Returns
`dict[str, Any] \| None`	Decoded data, or `None` when raw is missing or invalid.

def __encode(self, data: dict[str, Any]) -> str: (source) ¶

Serialize data to a JSON string suitable for storage.

Parameters
data:`dict[str, Any]`	Session data payload to encode.

Returns
`str`	UTF-8 decoded JSON payload.

def __init__(self, connection: IConnection, table: str = _DEFAULT_TABLE): (source) ¶

Bind the store to connection and the target table.

Parameters
connection:`IConnection`	Database connection used to persist session records.
table:`str, optional`	Table name used to store session records.

Returns
`None`	Undocumented

async def __insertOrRetryUpdate(self, session_id: str, payload: str, expiration: int): (source) ¶

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

Parameters
session_id:`str`	Unique session identifier.
payload:`str`	JSON-encoded session data already serialized by `write`.
expiration:`int`	Absolute expiration timestamp (whole epoch seconds).

Returns
`None`	Undocumented

async def _ensureSchema(self): (source) ¶

Create the sessions table on first use, if missing.

Returns
`None`	Undocumented

async def delete(self, session_id: str) -> bool: (source) ¶

overrides orionis.session.contracts.ISessionStore.delete

Remove the record for session_id (no-op when absent).

Parameters
session_id:`str`	Unique session identifier to remove.

Returns
`bool`	True only when a row was deleted.

async def gc(self): (source) ¶

overrides orionis.session.contracts.ISessionStore.gc

Remove all rows whose expires_at is in the past.

Unlike a native TTL-backed cache, a SQL table never evicts stale rows on its own, so this performs a single bulk DELETE.

Returns
`None`	Undocumented

async def read(self, session_id: str) -> SessionRecord | None: (source) ¶

overrides orionis.session.contracts.ISessionStore.read

Return the stored record for session_id, or None.

Parameters
session_id:`str`	Unique session identifier to look up.

Returns
`SessionRecord \| None`	The stored record, or `None` when absent, expired or corrupted.

async def update(self, record: SessionRecord) -> bool: (source) ¶

overrides orionis.session.contracts.ISessionStore.update

Update only a live session row with a single SQL statement.

Parameters
record:`SessionRecord`	Replacement payload and expiration.

Returns
`bool`	False when the session was deleted or expired.

async def write(self, record: SessionRecord): (source) ¶

overrides orionis.session.contracts.ISessionStore.write

Insert or replace the record keyed by its identifier.

A record that has already expired is deleted instead of written.

Parameters
record:`SessionRecord`	The record to persist.

Returns
`None`	Undocumented

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

overrides orionis.session.contracts.ISessionStore.__slots__

Undocumented

_connection = (source) ¶

Undocumented

_definition = (source) ¶

Undocumented

_ready: bool = (source) ¶

Undocumented

_ready_lock = (source) ¶

Undocumented

_table = (source) ¶

Undocumented