play-redis

The module provides native serialization for basic types (e.g., String, Int). For all other objects and collections, it uses JavaSerializer by default.

Warning: JavaSerializer is considered inefficient for production use.

Recommendation: Use the kryo serializer for better performance and smaller output. You can connect any serialization library through Pekko configuration.

The RecoveryPolicy determines how the application behaves when a cache request fails. This is useful because cache failures should typically not break the main application flow.

Available default policies:

• log-and-default: Logs the error and returns a neutral value (simulating no cache in use). This is the default.
• log-and-fail: Logs the error and re-throws the RedisException.
• log-condensed-and-default: Same as log-and-default but with reduced logging.
• log-condensed-and-fail: Same as log-and-fail but with reduced logging.
• custom: Allows you to provide your own implementation of the RecoveryPolicy trait.

Policies can be defined globally under play.cache.redis.recovery or overridden per instance under play.cache.redis.instances.instance-name.recovery.

All operations in this module throw an exception if they fail. To check for errors, use the following patterns based on the API type:

• Synchronous APIs: Use standard try-catch blocks as they throw exceptions directly.
• Asynchronous APIs: They return a Future wrapping the result. Use .onFailure or .onComplete to handle potential exceptions.

The library does not enable the Redis module by default to avoid conflicts with Play's default EhCache. This allows you to use EhCache in development and Redis in production, or to use both simultaneously by using named caches for Redis.

For advanced configurations involving multiple caches, refer to the Named Caches sample.

Upgrading from 2.0.x to 2.1.x involves changes to the invocation policy, annotations, and configuration keys:

Invocation Policy

In 2.0.x, the invocation policy was passed as an implicit parameter. In 2.1.x, it is now a static configurable property within the instance configuration.

Named Cache Annotations

The @Named annotation used for binding named caches in 2.0.x is deprecated. Use @NamedCache instead to align with the Play framework implementation. Note that @Named will be removed in version 2.2.0.

Configuration Key Renaming

The timeout property has been renamed to sync-timeout to avoid ambiguity. The original timeout property is deprecated and will be removed in version 2.2.0.

If you are running in an environment where the connection details are provided via an environment variable (like Heroku), set the source to connection-string. This allows you to pass a full Redis URL instead of defining individual host/port/password settings.

Example for Heroku using the REDIS_URL environment variable:

play.cache.redis {
  # enable connection-string mode
  source: connection-string

  # HOCON automatically injects the environmental variable
  connection-string: '${REDIS_URL}'
}

When upgrading to version 3.0.x, note the following environment and dependency requirements:

• Play Framework: Requires Play 2.9.0 or higher.
• JDK: Minimum version is JDK 11.
• Scala: Support for Scala 2.12 has been dropped. The project is compiled against Scala 2.13.12 to ensure compatibility with Scala 3.

To use the library, add the Play cache API dependency (matching your Play version) and the play-redis dependency to your build.sbt file.

// enable Play cache API (based on your Play version)
libraryDependencies += play.sbt.PlayImport.cacheApi
// include play-redis library
libraryDependencies += "com.github.karelcemus" %% "play-redis" % "5.4.0"

To add play-redis to your Play Framework project, add the following dependencies to your build.sbt file. Ensure you include the appropriate cacheApi based on your Play version.

Note: This version (5.4.0) supports Play framework 3.0.x with JDK 11 and Scala 2.13 or Scala 3.

// enable Play cache API (based on your Play version)
libraryDependencies += play.sbt.PlayImport.cacheApi

// include play-redis library
libraryDependencies += "com.github.karelcemus" %% "play-redis" % "5.4.0"

For compile-time DI, mix play.api.cache.redis.RedisCacheComponents into your BuiltInComponentsFromContext subclass.

This provides a cacheApi method that accepts a cache name (a string) and returns a RedisCaches instance. The RedisCaches instance encapsulates the available APIs for that specific cache. You can then expose these APIs (such as async) as needed in your application components.

// 'play' is the name of the named cache
// (play is default name of the default cache)
//
// the 'play' literal is implicitly converted into
// the instance but has to be configured in 'application.conf'
val playCache: RedisCaches = cacheApi( "play" )

// expose `play.api.cache.redis.CacheAsyncApi`
val asynchronousRedis = playCache.async