Accessing Data Reactively with Redis

This guide walks you through the process of creating a functional reactive application that uses Spring Data to interact with Redis using the non-blocking Lettuce driver.

What You Will Build

You’ll build a Spring application that uses Spring Data Redis and Project Reactor to interact with a Redis data store reactively, storing and retrieving Coffee objects without blocking. This application uses Reactor’s Publisher implementations based upon the Reactive Streams specification, namely Mono (for a Publisher returning 0 or 1 value) and Flux (for a Publisher returning 0 to n values).

What You Need

About 15 minutes
A favorite text editor or IDE
Java 17 or later

How to Complete This Guide

Like most Spring Getting Started guides you can start from scratch and complete each step, or you can jump straight to the solution, by viewing the code in this repository.

To see the end result in your local environment, you can do one of the following:

Download and unzip the source repository for this guide
Clone the repository using Git: git clone https://github.com/spring-guides/gs-spring-data-reactive-redis.git
Fork the repository which lets you request changes to this guide through submission of a pull request

Setting up the Redis Server

Before you can build a messaging application, you need to set up the server to handle receiving and sending messages. This guide assumes that you use Spring Boot Docker Compose support. A prerequisite of this approach is that your development machine has a Docker environment, such as Docker Desktop, available. Add a dependency spring-boot-docker-compose that does the following:

Search for a compose.yml and other common compose filenames in your working directory
Call docker compose up with the discovered compose.yml
Create service connection beans for each supported container
Call docker compose stop when the application is shutdown

To use Docker Compose support, you need only follow this guide. Based on the dependencies you pull in, Spring Boot finds the correct compose.yml file and start your Docker container when you run your application.

If you choose to run the Redis server yourself instead of using Spring Boot Docker Compose support, you have a few options: - Download the server and manually run it - Install with Homebrew, if you use a Mac - Manually run the compose.yaml file with docker compose up

If you go with any of these alternate approaches, you should remove the spring-boot-docker-compose dependency from the Maven or Gradle build file. You also need to add configuration to an application.properties file, as described in greater detail in the Preparing to Build the Application section. As mentioned earlier, this guide assumes that you use Docker Compose support in Spring Boot, so additional changes to application.properties are not required at this point.

Starting with Spring Initializr

You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To manually initialize the project:

Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.
Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.
Click Dependencies and select Spring Reactive Web, Spring Data Reactive Redis, and Docker Compose Support.
Click Generate.
Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

If your IDE has the Spring Initializr integration, you can complete this process from your IDE.

Create a Domain Class

Create a record representing a type of coffee we wish to stock in our coffee catalog:

src/main/java/com/example/demo/Coffee.java

package com.example.demo;

public record Coffee(String id, String name) {
}

Create a Configuration Class

Create a class that includes Spring Beans that support reactive Redis operations:

src/main/java/com/example/demo/CoffeeConfiguration.java

package com.example.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.connection.ReactiveRedisConnectionFactory;
import org.springframework.data.redis.core.ReactiveRedisOperations;
import org.springframework.data.redis.core.ReactiveRedisTemplate;
import org.springframework.data.redis.serializer.Jackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.RedisSerializationContext;
import org.springframework.data.redis.serializer.StringRedisSerializer;

@Configuration
public class CoffeeConfiguration {
  @Bean
  ReactiveRedisOperations<String, Coffee> redisOperations(ReactiveRedisConnectionFactory factory) {
    Jackson2JsonRedisSerializer<Coffee> serializer = new Jackson2JsonRedisSerializer<>(Coffee.class);

    RedisSerializationContext.RedisSerializationContextBuilder<String, Coffee> builder =
        RedisSerializationContext.newSerializationContext(new StringRedisSerializer());

    RedisSerializationContext<String, Coffee> context = builder.value(serializer).build();

    return new ReactiveRedisTemplate<>(factory, context);
  }

}

Create a Spring Bean to Load Data

Create a Spring Bean to load sample data for our application when we start it:

Since we may (re)start our application multiple times, we should first remove any data that may still exist from previous executions. We do this with a flushAll() (Redis) server command. Once we’ve flushed any existing data, we create a small Flux, map each coffee name to a Coffee object, and save it to the reactive Redis repository. We then query the repo for all values and display them.

src/main/java/com/example/demo/CoffeeLoader.java

package com.example.demo;

import org.springframework.data.redis.connection.ReactiveRedisConnectionFactory;
import org.springframework.data.redis.core.ReactiveRedisOperations;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Flux;

import jakarta.annotation.PostConstruct;
import java.util.UUID;

@Component
public class CoffeeLoader {
  private final ReactiveRedisConnectionFactory factory;
  private final ReactiveRedisOperations<String, Coffee> coffeeOps;

  public CoffeeLoader(ReactiveRedisConnectionFactory factory, ReactiveRedisOperations<String, Coffee> coffeeOps) {
    this.factory = factory;
    this.coffeeOps = coffeeOps;
  }

  @PostConstruct
  public void loadData() {
    factory.getReactiveConnection().serverCommands().flushAll().thenMany(
        Flux.just("Jet Black Redis", "Darth Redis", "Black Alert Redis")
            .map(name -> new Coffee(UUID.randomUUID().toString(), name))
            .flatMap(coffee -> coffeeOps.opsForValue().set(coffee.id(), coffee)))
        .thenMany(coffeeOps.keys("*")
            .flatMap(coffeeOps.opsForValue()::get))
        .subscribe(System.out::println);
  }
}

Create a RestController

Create a RestController to provide an external interface for our application:

src/main/java/com/example/demo/CoffeeController.java

package com.example.demo;

import org.springframework.data.redis.core.ReactiveRedisOperations;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
public class CoffeeController {
  private final ReactiveRedisOperations<String, Coffee> coffeeOps;

  CoffeeController(ReactiveRedisOperations<String, Coffee> coffeeOps) {
    this.coffeeOps = coffeeOps;
  }

  @GetMapping("/coffees")
  public Flux<Coffee> all() {
    return coffeeOps.keys("*")
        .flatMap(coffeeOps.opsForValue()::get);
  }
}

Run the Application

You can run the main method through your IDE. Note that, if you have cloned the project from the solution repository, your IDE may look in the wrong place for the compose.yaml file. You can configure your IDE to look in the correct place or you could use the command line to run the application. The ./gradlew bootRun and ./mvnw spring-boot:run commands will launch the application and automatically find the compose.yaml file.

Test the Application

With the application running, run the following command from a new terminal:

curl http://localhost:8080/coffees

You should see the following output:

[
  {
    "id": "04ce0843-c9f8-40f6-942f-1ff643c1d426",
    "name": "Jet Black Redis"
  },
  {
    "id": "e2a0d798-5fa4-48a2-a45c-7770d8bb82bf",
    "name": "Black Alert Redis"
  },
  {
    "id": "13f13e3a-0798-44b7-8ae4-b319b227bb19",
    "name": "Darth Redis"
  }
]

Preparing to Build the Application

To run the code without Spring Boot Docker Compose support, you need a version of Redis running locally to connect to. To do this, you can use Docker Compose, but you must first make two changes to the compose.yaml file. First, modify the ports entry in compose.yaml to be '6379:6379'. Second, add a container_name.

The compose.yaml should now be:

services:
  redis:
    container_name: 'guide-redis'
    image: 'redis:latest'
    ports:
      - '6379:6379'

You can now run docker compose up to start the Redis server. Now you should have an external Redis server that is ready to accept requests. You can rerun the application and see the same output using your external Redis server.

No configuration is required in the application.properties file because the default values match the Redis server configuration in compose.yaml. Specifically, the properties spring.data.redis.host and spring.data.redis.port default to localhost and 6379 respectively.

Building the Application

This section describes different ways to run this guide:

Regardless of how you choose to run the application, the output should be the same.

To run the application, you can package the application as an executable jar. The ./mvnw clean package command compiles the application to an executable jar. You can then run the jar with the java -jar target/demo-0.0.1-SNAPSHOT.jar command.

Alternatively, if you have a Docker environment available, you could create a Docker image directly from your Maven or Gradle plugin, using buildpacks. With Cloud Native Buildpacks, you can create Docker compatible images that you can run anywhere. Spring Boot includes buildpack support directly for both Maven and Gradle. This means you can type a single command and quickly get a sensible image into a locally running Docker daemon. To create a Docker image using Cloud Native Buildpacks, run the ./mvnw spring-boot:build-image command. With a Docker environment enabled, you can run the application with the docker run --network container:guide-redis docker.io/library/demo:0.0.1-SNAPSHOT command.

The --network flag tells Docker to attach our guide container to the existing network that our external container is using. You can find more information in the Docker documentation.

Native Image Support

Spring Boot also supports compilation to a native image, provided you have a GraalVM distribution on your machine.

You can then run the ./mvnw -Pnative native:compile command to generate a native image. When the build completes, you will be able to run the code with a near-instantaneous start up time by executing the target/demo command.

To create native image container using Maven you should ensure that your pom.xml file uses the spring-boot-starter-parent and the org.graalvm.buildtools:native-maven-plugin. This plugin should be located in the <build> <plugins> section:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
</plugin>

You can also create a Native Image using Buildpacks. You can generate a native image by running the ./mvnw -Pnative spring-boot:build-image command. Once the build completes, you can start your application with the docker run --network container:guide-redis docker.io/library/demo:0.0.1-SNAPSHOT command.

Test the Application in Docker

If you ran the application using a Docker instruction (shown earlier), a simple curl command from a terminal or command line will no longer work. This is because we run our containers in a Docker network that is not accessible from the terminal or command line. To run curl commands, we can start a third container to run our curl commands and attach it to the same network.

First, obtain an interactive shell to a new container that runs on the same network as the Redis container and the application:

docker run --rm --network container:guide-redis -it alpine

Next, from the shell inside the container, install curl:

apk add curl

Finally, you can run the curl commands as described in Test the Application.

Summary

Congratulations! You have developed a Spring application that uses Spring Data and Redis for fully reactive, non-blocking database access!

Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.

All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing.

Get the Code

Go To Repo