Skip to content
hikari-risa hikari-risa

risa.store.postgres

PostgresStore, a store on PostgreSQL. Install it with the [postgres] extra.

DEFAULT_LEASE module-attribute 

DEFAULT_LEASE: Final[float] = leases.DEFAULT_LEASE

Seconds a lock's lease lasts before it needs renewing.

DEFAULT_MAX_HOLD module-attribute 

DEFAULT_MAX_HOLD: Final[float] = leases.DEFAULT_MAX_HOLD

Seconds after which a held lock is no longer renewed; its last lease then runs out.

DEFAULT_TABLE module-attribute 

DEFAULT_TABLE: Final[str] = 'risa_state'

The name of the state table when none is given.

PostgresStore 

PostgresStore(
    pool: Pool,
    *,
    table: str = DEFAULT_TABLE,
    lease: float = DEFAULT_LEASE,
    max_hold: float = DEFAULT_MAX_HOLD,
)

Bases: Store

A store on PostgreSQL, through an asyncpg pool.

An entry is a row of table. lock() takes a lease on a row of {table}_lease and renews it while held, so clicks on one view queue up across every process that shares the database. The store creates both tables on first use if they are missing, and deletes expired rows itself: on its first write, then on every hundredth.

Parameters:

  • pool (Pool) –

    The pool the bot owns. The store borrows a connection for each statement and never opens or closes the pool.

  • table (str, default: DEFAULT_TABLE ) –

    The name of the state table: a lowercase identifier of at most 52 characters. The lease table is named after it.

  • lease (float, default: DEFAULT_LEASE ) –

    Seconds a lock's lease lasts. It is renewed every third of that while held, and a crashed holder blocks its view for at most this long.

  • max_hold (float, default: DEFAULT_MAX_HOLD ) –

    Seconds after which a held lock is no longer renewed, so a stuck handler cannot block its view for good.

Raises:

  • ValueError –

    If table is not a plain lowercase identifier, lease is not positive, or max_hold is shorter than lease.

delete async 

delete(key: str) -> None

Remove the entry under key, if there is one.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

get_versioned async 

get_versioned(key: str) -> VersionedEntry | None

Return the data and version under key, or None if there is none or it has expired.

Parameters:

  • key (str) –

    The entry's key, an opaque string. risa's are {prefix}:1:{hex}, and it passes the one key of a view's record to every method, lock included.

Returns:

  • VersionedEntry | None –

    The bytes last written with their version, or None.

lock 

lock(
    key: str, *, timeout: float = DEFAULT_LOCK_TIMEOUT
) -> AbstractAsyncContextManager[None]

Hold key exclusively while the returned context manager is entered.

risa holds it for the length of a click, so clicks on one view run one after another. A store that several processes share should exclude all of them; when such a lock lapses, the version check of put_if_version still decides whose write lands.

Parameters:

  • key (str) –

    The key to hold; risa passes the key of the record it is about to read and write. Holding one key does not make another wait, and the key needs no entry.

  • timeout (float, default: DEFAULT_LOCK_TIMEOUT ) –

    Seconds to wait for the lock, fractions included, before raising LockTimeoutError.

Raises:

put async 

put(key: str, value: bytes, *, ttl: float | None) -> None

Write value under key, whether or not an entry exists.

The entry's version changes. ttl is the entry's lifetime in seconds from now, and None clears any expiry, so the entry lives until it is deleted.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

  • value (bytes) –

    The bytes to keep. get_versioned returns them unchanged, whatever they hold, empty included.

  • ttl (float | None) –

    Seconds the entry lives, counted from this write and fractions included. None gives it no expiry, which also clears the expiry an earlier write set.

put_if_version async 

put_if_version(
    key: str, value: bytes, *, expected: int, ttl: float | None
) -> int | None

Write value under key only if the entry is still at version expected.

The compare and the write are one atomic step: of several writers expecting the same version, exactly one succeeds. ttl works as in put.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

  • value (bytes) –

    The bytes to keep if the write goes through.

  • expected (int) –

    A version from get_versioned, or returned by an earlier put_if_version. The write goes through only while the entry is still at exactly that version. Versions compare only within one entry's life: a store may restart them once the entry is deleted or has expired.

  • ttl (float | None) –

    Seconds the entry lives from this write, as in put. None gives it no expiry.

Returns:

  • int | None –

    The entry's new version, or None if the entry is missing, expired, or at a different version, in which case nothing was written.

touch async 

touch(key: str, *, ttl: float) -> None

Restart the lifetime of the entry under key, which now expires ttl seconds from now.

The data and version stay as they are, and a missing key stays missing.

Parameters:

  • key (str) –

    The entry's key, as for get_versioned.

  • ttl (float) –

    Seconds the entry now lives, counted from this call and replacing the expiry it had.