HydraCache 0.32.0

HydraCache 0.32.0

Status: release candidate.

0.32.0 focuses on database adapter parity. SQLx, Diesel, and SeaORM now use
the same result-shape vocabulary for query-cache helpers:

one       -> exactly one cached value
optional  -> zero-or-one cached value
all       -> cached collection

This release intentionally breaks the fresh 0.31.x adapter helper names
instead of carrying compatibility aliases too early in the 0.x line.

Highlights

• Rename SQLx helpers to sqlx_one, sqlx_optional, and sqlx_all.
• Rename Diesel's exactly-one helper to diesel_one.
• Align SeaORM helpers as sea_one, sea_optional, and sea_all.
• Keep DbQuery::fetch_with as the database-neutral escape hatch for custom
  repositories, transactions, SQLx macros, and unusual call sites.
• Expand adapter parity coverage with TTL reload, empty collection caching,
  loader error retry, optional miss caching, collection invalidation, and
  concurrent same-key single-flight scenarios.
• Expand the sandbox ORM comparison response with helper/API path, shape, TTL,
  cache key, tags, source transitions, loader-call delta, pass/fail state, and
  explicit invalidation report.

Current API Shape

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

# async fn sqlx_example(pool: sqlx::PgPool) -> hydracache_sqlx::Result<()> {
let queries = DbCache::new(HydraCache::local().build(), "db");

let user: (i64, String) = queries
    .entity::<(i64, String)>("user", 42)
    .collection_tag("users")
    .sqlx_one(
        pool.clone(),
        sqlx::query_as("select id, name from users where id = $1").bind(42_i64),
    )
    .await?;

assert_eq!(user.0, 42);
# Ok(())
# }

use hydracache::HydraCache;
use hydracache_diesel::{DieselCache, DieselQueryExt};

# async fn diesel_example() -> hydracache_diesel::Result<()> {
let queries = DieselCache::new(HydraCache::local().build(), "diesel");

let name = queries
    .entity::<String>("user", 42)
    .collection_tag("users")
    .diesel_one(move || Ok::<_, hydracache_diesel::diesel::result::Error>("Ada".to_owned()))
    .await?;

assert_eq!(name, "Ada");
# Ok(())
# }

use hydracache::HydraCache;
use hydracache_seaorm::{SeaOrmCache, SeaOrmQueryExt};

# async fn seaorm_example() -> hydracache_seaorm::Result<()> {
let queries = SeaOrmCache::new(HydraCache::local().build(), "seaorm");

let name = queries
    .entity::<String>("user", 42)
    .collection_tag("users")
    .sea_one(|| async { Ok::<_, hydracache_seaorm::sea_orm::DbErr>("Ada".to_owned()) })
    .await?;

assert_eq!(name, "Ada");
# Ok(())
# }

Migration From 0.31.x

• Replace SQLx .fetch_one(...) with .sqlx_one(...).
• Replace SQLx .fetch_optional(...) with .sqlx_optional(...).
• Replace SQLx .fetch_all(...) with .sqlx_all(...).
• Replace Diesel .diesel_first(...) with .diesel_one(...).
• Replace SeaORM optional lookups that return Option<T> with
  .sea_optional(...).
• Replace SeaORM exactly-one/value loaders with .sea_one(...).
• Remove .sea_value(...); it is now represented by .sea_one(...).

Verification

cargo test -p hydracache-sqlx --locked
cargo test -p hydracache-diesel --locked
cargo test -p hydracache-seaorm --locked
cargo test -p hydracache-sandbox --lib --locked orm_comparison_route_is_repeatable_and_deduplicates_tags
cargo test -p hydracache-sandbox --lib --locked openapi_document_describes_demo_and_actuator_routes
cargo test --doc -p hydracache-sqlx --locked
cargo test --doc -p hydracache-diesel --locked
cargo test --doc -p hydracache-seaorm --locked

Full release gate:

cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo test --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --doc --workspace --locked
Set-Item -Path Env:RUSTDOCFLAGS -Value '-D warnings'; cargo doc --workspace --no-deps --locked