Struct PostgresSessionStore 

pub struct PostgresSessionStore { /* private fields */ }

Available on crate feature postgres only.

PostgreSQL-backed session store with AES-256-GCM encryption at rest.

Wrap an existing PgPool and call init_schema once at startup. Production deployments must also schedule cleanup of expired session rows: either by calling spawn_cleanup_task at startup, configuring pg_cron on the database side, or running an external job that invokes cleanup_expired. Without one of these, the sessions table grows unbounded.

Encryption

The primary constructor new requires a SessionCrypto key; session data is encrypted before storage and decrypted on load.

For local development or testing where encryption is not needed, use plaintext instead.

use axess::session::SessionCrypto;

// Production: encrypted (required).
let store = PostgresSessionStore::new(pool, SessionCrypto::new(key));

// Development only: plaintext (explicit opt-out).
let store = PostgresSessionStore::plaintext(pool);

Implementations

impl PostgresSessionStore

pub fn new(pool: PgPool, crypto: SessionCrypto) -> Self

Create an encrypted store (recommended for production).

pub fn plaintext(pool: PgPool) -> Self

Create a plaintext store (development/testing only).

pub fn with_clock(self, clock: Arc<dyn Clock>) -> Self

Inject a Clock for deterministic-simulation testing.

pub async fn init_schema(&self) -> Result<(), Error>

Create the sessions table and index if they don’t already exist.

pub async fn cleanup_expired(&self) -> Result<u64, Error>

Delete all sessions whose expires_at is in the past.

pub fn spawn_cleanup_task(&self, interval: Duration) -> JoinHandle<()>

Spawn a background task that calls cleanup_expired on a fixed interval.

SQL stores accumulate expired session rows forever unless something removes them. Production deployments must either call this helper once at startup, run an external scheduled job (e.g. pg_cron on the database side), or accept unbounded table growth. The returned tokio::task::JoinHandle aborts the loop when dropped, so store it for the lifetime of the application.

Errors from cleanup_expired are logged at warn and swallowed; the loop keeps running so a single transient DB blip does not silently halt cleanup forever.

let store = PostgresSessionStore::new(pool, crypto);
store.init_schema().await?;
let _cleanup = store.spawn_cleanup_task(std::time::Duration::from_secs(3600));

Trait Implementations

impl Clone for PostgresSessionStore

fn clone(&self) -> PostgresSessionStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl HealthCheck for PostgresSessionStore

fn check(&self) -> Pin<Box<dyn Future<Output = HealthStatus> + Send + '_>>

Probe the component and return its current health.

impl SessionStore for PostgresSessionStore

type Error = SqlStoreError

The error type returned by storage operations.

async fn load(&self, id: &SessionId) -> Result<Option<SessionData>, Self::Error>

Load the session data for the given ID. Returns None if the session does not exist or has expired.

async fn save( &self, id: &SessionId, data: &SessionData, ttl: Duration, ) -> Result<(), Self::Error>

Persist session data with a time-to-live.

async fn delete(&self, id: &SessionId) -> Result<(), Self::Error>

Delete the session. Idempotent; does not error if the session is absent.

async fn cycle( &self, old_id: &SessionId, new_id: &SessionId, data: &SessionData, ttl: Duration, ) -> Result<(), Self::Error>

Atomically delete the old session row and store the data under the caller-supplied new id.

async fn prune_expired(&self) -> Result<u64, Self::Error>

Bulk-delete every session row whose TTL has elapsed. Returns the number of rows reclaimed.

fn find_sessions_for_user( &self, user_id: &UserId, limit: usize, ) -> impl Future<Output = Result<Vec<(SessionId, SessionData)>, Self::Error>> + Send

Return active (non-expired) sessions for the given user, newest first.

impl Store<SessionId, SessionData> for PostgresSessionStore

type Error = SqlStoreError

Backend-specific error. Use the shared StoreError enum for new backends; legacy wrappers may continue to surface SqlStoreError / ValkeyStoreError / PostgresStoreError until each is consolidated.

fn get( &self, key: &SessionId, ) -> impl Future<Output = Result<Option<SessionData>, Self::Error>> + Send

Fetch the value for key. Ok(None) when the key is absent (including TTL-expired); Err only on backend failure.

fn put( &self, key: &SessionId, value: &SessionData, ttl: Duration, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Insert or replace the value at key with the given TTL.

fn delete( &self, key: &SessionId, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Remove the entry at key. Idempotent; does not error if absent.

fn prune_expired(&self) -> impl Future<Output = Result<u64, Self::Error>> + Send

Bulk-evict every TTL-expired entry. Returns the number reclaimed. Backends with native TTL eviction (Valkey/Redis) may implement this as a no-op returning Ok(0); backends owning their own row table (SQLite, Postgres, in-memory) actually delete.