redis4cats

The redis4cats library provides an experimental API for interacting with Redis at the stream level using Stream[F[_], A] built on top of fs2. This API is divided into two main functional areas:

1. PubSub: A simple, safe, and pure functional streaming client for interacting with Redis PubSub.
2. Streams: A high-level, safe, and pure functional API for interacting with Redis Streams.

The Effects API in redis4cats allows you to perform Redis operations within a functional effect type F[_]. This API is built on top of cats-effect, meaning all operations are asynchronous and non-blocking, returning values wrapped in your chosen effect type (typically IO).

Instead of working with raw commands, you use specialized APIs organized by Redis data types and features. Common API groups include:

• Data Types: Hashes, Lists, Sets, Sorted Sets, Strings, Bitmaps, and HyperLogLog.
• Specialized Features: Geo (geospatial), JSON, and Scripting (Lua).
• Management: Keys, Connection, ACL (Access Control Lists), and Server management.

Pipelining allows you to speed up queries by disabling Redis's default autoflush mode. Instead of waiting for a response for every command, you can send a batch of commands to the server and flush them all at once.

In redis4cats, pipelining is modeled as a Resource with the following lifecycle:

• Acquire: Disables autoflush and sends a List[F[Unit]] of commands.
• Release: Flushes the commands on success, or logs an error if the operation fails or is cancelled.
• Guarantee: Re-enables autoflush.

⚠️ Important Constraint: Pipelining shares the same asynchronous implementation as transactions. This means you can only run sequential pipelines from a single RedisCommands instance; you cannot run them concurrently on the same instance.

The RedisJSON API provides two variants for most methods:

1. JsonValue variants: These work with Lettuce's JsonValue type (e.g., jSet, jGet, arrAppend).
2. String variants: These accept or return raw JSON strings and are identified by the Str or Raw suffix (e.g., jSetStr, jGetRaw, arrAppendStr).

Recommendation: For most use cases, use the String variants. They allow you to work directly with JSON text without requiring the client to perform JSON parsing.

Authentication can be handled via the URI string, by attaching credentials to a RedisURI using .withCredentials, or via RedisUriConfig.

RedisCredentials supports two modes:

• RedisCredentials.Password(token): For AUTH <token> (no username).
• RedisCredentials.UsernameAndPassword(username, token): For Redis 6+ ACL-style AUTH <username> <token>.

import dev.profunktor.redis4cats.connection._

// Token without a username
RedisURI.make[IO]("redis://localhost:6379").map(_.withCredentials(RedisCredentials.Password(token)))

// Username + token (Redis 6 ACL style)
RedisURI
  .make[IO]("redis://localhost:6379")
  .map(_.withCredentials(RedisCredentials.UsernameAndPassword(username, token)))

Redis is a key-value store that typically stores values in a string-like format. Redis4Cats uses the RedisCodec[K, V] type to parameterize the types of keys (K) and values (V) used in commands.

Commonly used built-in codecs include:

• RedisCodec.Utf8 (most common)
• RedisCodec.Ascii
• RedisCodec.Bytes

Master/Replica connections use RedisMasterReplica. This abstraction manages connections to both master and replica nodes. You can specify how to read from the cluster using ReadFrom (e.g., ReadFrom.UpstreamPreferred).

import cats.effect.{IO, Resource}
import cats.implicits._
import dev.profunktor.redis4cats.Redis
import dev.profunktor.redis4cats.algebra.StringCommands
import dev.profunktor.redis4cats.connection.RedisMasterReplica
import dev.profunktor.redis4cats.data.ReadFrom

val commands: Resource[IO, StringCommands[IO, String, String]] =
  for {
    uri <- Resource.eval(RedisURI.make[IO]("redis://localhost"))
    conn <- RedisMasterReplica[IO].make(RedisCodec.Utf8, uri)(ReadFrom.UpstreamPreferred.some)
    redis <- Redis[IO].masterReplica(conn)
  } yield redis

commands.use { redis =>
  redis.set("foo", "123") >> IO.unit
}

To use RedisJSON commands, you need to acquire a connection that is widened to the JsonCommands trait. You can do this by using Redis[IO].fromClient and applying .widen[JsonCommands[IO, K, V]] to the resulting client.

In the example below, K and V represent the key and value types (e.g., String).

import cats.effect.{IO, Resource}
import cats.implicits._
import dev.profunktor.redis4cats.Redis
import dev.profunktor.redis4cats.algebra.JsonCommands
import dev.profunktor.redis4cats.data._

// Example: Initializing a JsonCommands API for String keys and String values
val commandsApi: Resource[IO, JsonCommands[IO, String, String]] = {
  Redis[IO].fromClient[String, String](null, null.asInstanceOf[RedisCodec[String, String]])
    .widen[JsonCommands[IO, String, String]]
}