Reactive Spring Boot Application with R2DBC and PostgreSQL

Reactive Spring Boot Application with R2DBC and PostgreSQL

*note: the example repository has been updated with Java 17 and Spring Boot 3

Reactive application is getting more popular with the rise of microservice architecture. To utilize the full potential of a reactive system, it is recommended to make all of our systems reactive.

However, making a fully reactive application is still quite a challenge in the JVM world, because JDBC (Java Database Connectivity) is a **synchronous, **and **blocking **API for connecting to relational databases, which most applications use to store their data.

To address this issue, Pivotal (the company behind the Spring framework) led a community effort to create an asynchronous way of connecting to the database, this project is now called R2DBC (Reactive Relational Database Connectivity).

After the R2DBC initiatives, the Spring team decided to support R2DBC in the Spring ecosystem, and thus Spring Data R2DBC was born.

Project setup

Let’s have a look at how we can create a fully reactive application using Spring Boot and Spring Data R2DBC.

We can scaffold the project using the handy Spring Initializr (, we will use Java 8, Maven, and Jar as our packaging.

Three dependencies must be included:

  1. Spring Data R2DBC

  2. PostgreSQL Driver

  3. Spring Reactive Web

Lombok and Spring Boot DevTools is not mandatory, but they do help ease a lot of pain when developing Spring applications. If you don’t know what are their use case, I’d highly recommend taking a look at their documentation.

After opening the project, we will be greeted by the usual Spring Boot main class like this

public class ReactivePostgresApplication {

  public static void main(String[] args) {, args);

To start, we will create our POJO class representing a very simple Member

public class Member {
  private Long id;
  private String name;

The @Value and @Builder is an annotation from Lombok, they generate a setter and getter, and a bunch of other things to make our code less stuffed with boilerplate code.

R2DBC repository

Creating a repository is also straightforward, still very familiar with what we used to do in other Spring Data frameworks, in this example we will extend our interface with R2dbcRepository.

public interface MemberRepository extends R2dbcRepository<Member, Long> {
  Mono<Member> findByName(String name);

On line 2, we create a custom method that will query the member data by name. If you want to see a snippet of what this repository could do, you can check this documentation for more information. In this R2DBC repository, the custom method is not returning Member directly, but it’s wrapped in Mono. Every method in this repository will use either Mono or Flux. This is in line with what the Project Reactor uses, so we have full compatibility with reactive API.

Not only R2dbcRepository, in Spring Data R2DBC we have the option to extends the interface with one of these two options:

  1. ReactiveCrudRepository, for your generic CRUD repository and,

  2. ReactiveSortingRepository for an additional sorting function.

You can choose any of these options, depending on your use case.

R2dbc Repository Class Diagrams

R2dbc Repository Class Diagrams

Next, let’s have a look at how we can implement a reactive controller

@RequestMapping(value = "/api/member")
public class MemberController {

  private final MemberRepository memberRepository;

  public Flux<Member> getAll() {
    return memberRepository.findAll();

  @GetMapping(value = "/{name}")
  public Mono<Member> getOne(@PathVariable String name) {
    return memberRepository.findByName(name);

For this example, we’ll create 2 separate endpoints that will use Mono and Flux:

  1. On method getAll, we use the repository that we created earlier to get all the data in the database, because we will get more than 1 data, the returned data is wrapped in Flux.

  2. On method getOne, we request for a single piece of data, for this case we wrap the returned data in Mono.

We’re almost done now. Now that we have set up the API, all we need to do is connect the application to our database. To do this, we’ll need to add these two properties in our file.


The first line will tell spring to connect to a local database with a database name of reactive with r2dbc as its connection protocol.

The second line is a debugging properties so we can see exactly the queries that are running inside our application.

Next, we need to create a schema.sql file to initialize our database table, we can do that using this query:

    name TEXT NOT NULL

we’re gonna save this inside our resources folder.

One last step, because Spring Data R2DBC doesn’t support auto initializing the database with our schema, we have to manually execute this query when we’re starting our application, this is one of the ways to do it:

we can create a bean on our main application to execute schema.sql whenever we run our application.

ConnectionFactoryInitializer initializer(@Qualifier("connectionFactory") ConnectionFactory connectionFactory) {
  ConnectionFactoryInitializer initializer = new ConnectionFactoryInitializer();
  ResourceDatabasePopulator resource =
      new ResourceDatabasePopulator(new ClassPathResource("schema.sql"));
  return initializer;

Now we can finally run our application. When we see into the log, we can see that the application executed our schema.sql.

202-01-07 12:33:49.037 DEBUG 37404 --- [actor-tcp-nio-1] o.s.r2dbc.connection.init.ScriptUtils    : Executing SQL script from class path resource [schema.sql]
2021-01-07 12:33:49.088 DEBUG 37404 --- [actor-tcp-nio-1] o.s.r2dbc.connection.init.ScriptUtils    : 0 returned as update count for SQL: CREATE TABLE IF NOT EXISTS member ( id SERIAL PRIMARY KEY, name TEXT NOT NULL )

From our example above, we created 2 GET endpoints:

  1. /api/member to get all of our member’s data

  2. /api/member/{name} to get a specific member’s data

When we hit the endpoint of our API to get all member on localhost:8080/api/member we can see that the R2DBC executed this SQL

2021-01-07 12:35:21.823 DEBUG 37404 --- [ctor-http-nio-3] o.s.r2dbc.core.DefaultDatabaseClient     : Executing SQL statement [SELECT member.* FROM member]

and when we do a request on localhost:8080/api/member/{memberName}, the app shows that we’re executing a query to get a single record.

2021-01-07 12:39:24.956 DEBUG 37404 --- [ctor-http-nio-3] o.s.r2dbc.core.DefaultDatabaseClient     : Executing SQL statement [SELECT, FROM member WHERE = $1]

At this point, we have successfully created a fully reactive application with Spring Data R2DBC, with PostgreSQL as our relational database.

Conclusion and improvements

Creating a fully reactive Spring application is easier with the help of Spring Data R2DBC. The process is not too different than what we’re used to and we can still use the same Repository that we use in a non-reactive database.

It is not as smooth as it seems though, this is a very basic example application, not a production scale application with all its complex requirements. So, depending on your use case, you might not be able to use Spring Data R2DBC yet.

There is also a difference in how to fine-tune your database because we don’t use JDBC anymore, one of the examples is connection pooling. We might be familiar with HikariCP for our database connection pooling, but on the reactive side, HikariCP is not available, and one of the options is to use R2DBC Pool.

All in all, R2DBC is a promising technology, allowing us to have a fully reactive application. Even though there are a lot of unknowns, it’s still worth exploring!

If you want to see the full source code, here’s the link to the full repository: kamalhm/spring-boot-r2dbc *An example implementation of Spring Boot R2DBC REST API with PostgreSQL database. Spring Boot 2.4.1.RELEASE Spring Data…*

Thanks for reading! :)