kape-postgres 0.1.2

PostgreSQL backend adapter for Kape.
Documentation

kape-postgres

PostgreSQL adapter for Kape.

[dependencies]
kape = "0.1.0"
kape-postgres = "0.1.0"
sqlx = { version = "0.9", default-features = false, features = ["postgres", "runtime-tokio"] }
use kape_postgres::PostgresBackend;

fn example(pool: sqlx::PgPool) {
    // Retain a pool clone if the application needs lifecycle control.
    let backend = PostgresBackend::<String, String>::new(pool).namespace("my-service");
    let _ = backend;
}

The application must create and migrate the table. The minimum default schema is:

CREATE TABLE kape_entries (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    expires_at_ms BIGINT NULL
);

The adapter performs no DDL or startup table check. with_table("schema.table") fallibly selects a validated identifier. Applications keep their own PgPool clone for direct use and shutdown.

PostgresBackend defaults to String keys, String values, and StringCodec. StringCodec maps to TEXT columns, so default keys and values remain readable in PostgreSQL tools. BytesCodec maps Vec<u8> keys and values to BYTEA columns without text conversion. Custom PostgresCodec<K, V> implementations select String or Vec<u8> associated storage types, and the application must create matching column types. clear and purge_expired affect only the configured namespace. Applications decide when to schedule purging and remain responsible for table-wide maintenance.

An existing provisional BYTEA table does not match the default StringCodec. Because Kape is unreleased and cache rows are disposable, applications should recreate that cache table with the default TEXT schema or explicitly select BytesCodec and continue using a BYTEA schema.

For a bytes-only table, use BytesCodec with this schema instead:

CREATE TABLE kape_entries (
    key BYTEA PRIMARY KEY,
    value BYTEA NOT NULL,
    expires_at_ms BIGINT NULL
);
use kape_postgres::{BytesCodec, PostgresBackend};

fn bytes_example(pool: sqlx::PgPool) {
    let backend = PostgresBackend::<Vec<u8>, Vec<u8>>::new(pool)
        .with_codec(BytesCodec);
    let _ = backend;
}

Finite expiry timestamps are calculated from the application host's Unix clock; remaining TTL and expired-row cleanup use the PostgreSQL server clock. Keep the application and database hosts time-synchronized. Batch reads use ordinality to retain misses and duplicate positions. Batch writes reject duplicate keys, use one bulk UPSERT statement, and use a local transaction only when the same batch also contains deletions. This does not create a transaction across a Kape chain.

TLS is opt-in through the native-tls and rustls features.