Cache Mechanism

Current Status

The current github.com/go-juicedev/juice main branch does not expose a built-in query cache API. Older documentation mentioned APIs such as engine.CacheTx(), engine.SetCacheFactory(...) and a transaction-level cache interface, but those APIs are not present in the current codebase.

Do not use examples based on those removed APIs in new code.

Available Alternatives

For current Juice applications, use one of these approaches instead:

1. Application-level cache

   Cache service or repository results in your own code. This keeps cache key design, invalidation, TTL, and serialization explicit.

2. Middleware-based observation

   Use middleware for logging, tracing, metrics, and slow-query detection. Middleware can observe SQL execution, but Juice does not currently provide a public built-in cache store for middleware to reuse.

3. Database-side optimization

   Use database indexes, materialized views, read replicas, or database-native query cache features where appropriate.

4. External cache

   Use Redis, Memcached, or another external cache in your service layer. Keep cache invalidation close to the business operation that changes the underlying data.

Statement Attributes

The XML DTD may still include attributes such as useCache or flushCache for compatibility with older mapper formats. In the current implementation, these attributes should not be treated as enabling a built-in query cache.

Recommended Pattern

Example repository-level cache shape:

func (r *UserRepository) GetUser(ctx context.Context, id int64) (*User, error) {
    key := fmt.Sprintf("user:%d", id)

    if user, ok := r.cache.Get(ctx, key); ok {
        return user, nil
    }

    user, err := juice.QueryContext[*User](ctx, "user.UserRepository.GetUser", juice.H{"id": id})
    if err != nil {
        return nil, err
    }

    r.cache.Set(ctx, key, user, time.Minute)
    return user, nil
}

Keep cache invalidation explicit in write operations.