Crate hydracache_sqlx

Expand description

SQLx-facing integration crate for HydraCache database result caching.

The database-neutral query cache API lives in hydracache-db. This crate keeps SQLx users on a convenient import path while avoiding a hard conceptual dependency between the generic adapter and SQLx itself.

§Example

use hydracache::HydraCache;
use hydracache_sqlx::{DbCache, HydraCacheEntity, PreparedQueryPolicy, SqlxQueryExt};

#[derive(serde::Serialize, serde::Deserialize, HydraCacheEntity)]
#[hydracache(entity = "user", collection = "users")]
struct User {
    #[hydracache(id)]
    id: i64,
    name: String,
}

let local = HydraCache::local().build();

// SQLx users may import DbCache from this crate, but the type itself is
// database-neutral and comes from hydracache-db.
let queries = DbCache::new(local, "db");

let user: User = queries
    .for_entity::<User>(42)
    .fetch_with(move || async move {
        let (id, name): (i64, String) =
            sqlx::query_as("select id, name from users where id = $1")
                .bind(42_i64)
                .fetch_one(&pool)
                .await?;

        Ok::<_, sqlx::Error>(User { id, name })
    })
    .await?;

assert_eq!(user.id, 42);
assert!(!user.name.is_empty());

Prepared policies keep repeated repository methods cheap while still using ordinary SQLx query execution on cache misses:

use hydracache::HydraCache;
use hydracache_sqlx::{DbCache, HydraCacheEntity, PreparedQueryPolicy, SqlxQueryExt};

#[derive(serde::Serialize, serde::Deserialize, HydraCacheEntity)]
#[hydracache(entity = "user", collection = "users")]
struct User {
    #[hydracache(id)]
    id: i64,
    name: String,
}

let queries = DbCache::new(HydraCache::local().build(), "db");
let load_user = queries.prepare::<(i64, String)>(
    PreparedQueryPolicy::for_cache_entity::<User>().with_name("load-user"),
);

let (id, name) = load_user
    .for_id(42)
    .sqlx_one(
        pool.clone(),
        sqlx::query_as("select id, name from users where id = $1").bind(42_i64),
    )
    .await?;

assert_eq!(id, 42);
assert!(!name.is_empty());

Use DbQuery::fetch_with when you need SQLx macros, transactions, or a repository function instead of a pool-like executor.

QueryCachePolicy and PreparedQueryPolicy are also re-exported for SQLx users, but the policy types are database-neutral and live in hydracache-db. query_cache_policy! is re-exported for the same convenience.

Re-exports§

pub use sqlx;

Macros§

prepared_query_policy: Build a reusable PreparedQueryPolicy with less boilerplate.
query_cache_policy: Build a QueryCachePolicy with less boilerplate.

Structs§

CacheKeyBuilder: Builder for cache keys made of escaped :-separated segments.
DbCache: A database-oriented view over a HydraCache instance.
DbOperationContext: Diagnostic context for one database cache operation.
DbQuery: A cacheable database query descriptor.
InvalidationCollector: Mutable invalidation collector passed to transaction companion closures.
InvalidationPlan: A database-neutral list of cache invalidations staged by repository code.
InvalidationReport: Result of executing a staged InvalidationPlan.
PgNotifyIntent: One Postgres LISTEN/NOTIFY wake-up payload.
PgNotifyIntentSource: Thin sqlx PgListener wrapper for invalidation wake-ups.
PreparedDbQuery: A prepared database query descriptor.
PreparedQueryPolicy: Prepared database query cache metadata.
QueryCachePolicy: Reusable cache metadata for one database query result.
SqlxInvalidationOutbox: SQLx-backed invalidation outbox.
SqlxTransactionCompanion: SQLx transaction companion.
SqlxTransactionDiagnostics: Diagnostics for SQLx transaction companion runs.
SqlxTransactionReport: Result of a SQLx transaction companion run.

Enums§

DbAdapterKind: Database adapter kind attached to operation diagnostics.
DbCacheError: Error type returned by database cache adapter helpers.
DbResultShape: Cached database result shape attached to operation diagnostics.
SqlxCacheError: Error type returned by SQLx-facing cache helpers.
SqlxTransactionError: Error returned by SQLx transaction companion helpers.

Constants§

OUTBOX_SCHEMA_VERSION: Current durable schema version for hydracache_invalidation_outbox.

Traits§

CacheEntity: Static cache metadata for a domain entity.
SqlxQueryExt: Convenience SQLx execution methods for DbQuery.
SqlxTransactionExt: Extension trait that creates SQLx transaction companions from DbCache.

Type Aliases§

DbResult: Database cache adapter result type.
RefreshPolicy: Database-facing alias for local cache refresh/stale behavior.
Result: SQLx adapter result type.
SqlxCache: SQLx-specific compatibility name for DbCache.
SqlxQuery: SQLx-specific compatibility name for DbQuery.
SqlxTransactionFuture: Boxed future returned by SQLx transaction companion closures.
TransactionResult: SQLx transaction companion result type.

Derive Macros§

HydraCacheEntity: Derive CacheEntity metadata for database result-cache helpers.