Spring Data R2DBC | Reference Documentation

12. Introduction

This part of the reference documentation describes the core features provided by Spring Data R2DBC. The R2DBC support chapter introduces the feature set of the module, and the R2DBC Repository chapter introduces repository support.

13. R2DBC Support

R2DBC support includes Java-based Spring configuration for R2DBC driver instances, R2dbcEntityTemplate for entity-oriented operations, object mapping integrated with Spring’s conversion service, annotation-based mapping metadata, and automatic implementation of repository interfaces including custom query methods.

Most applications should use R2dbcEntityTemplate or repository support. Both provide rich mapping capabilities and convenient access to common CRUD operations.

13.1. Getting Started

The easiest way to set up a project is through start.spring.io. Add Spring Data R2DBC and an R2DBC driver such as H2 to the project dependencies.

<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-r2dbc</artifactId>
  <version>1.4.0</version>
</dependency>

<dependency>
  <groupId>io.r2dbc</groupId>
  <artifactId>r2dbc-h2</artifactId>
  <version>Arabba-SR10</version>
</dependency>

Debug logging can be enabled with:

logging.level.org.springframework.r2dbc=DEBUG

A simple domain class can be persisted without extra mapping metadata.

public class Person {
  private final String id;
  private final String name;
  private final int age;
  // constructor and getters
}

Create a table and use R2dbcEntityTemplate to insert and select rows.

ConnectionFactory connectionFactory =
    ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE");

R2dbcEntityTemplate template = new R2dbcEntityTemplate(connectionFactory);

template.insert(Person.class)
  .using(new Person("joe", "Joe", 34))
  .as(StepVerifier::create)
  .expectNextCount(1)
  .verifyComplete();

The example shows that Spring Data R2DBC can work with a standard ConnectionFactory, map a regular POJO, access fields directly, and instantiate an object by matching constructor argument names to column names.

13.2. Example Repository

Spring Data examples are available in the Spring Data examples repository on GitHub. They can be downloaded to check how the library behaves in practical scenarios.

13.3. Connecting to a Relational Database with Spring

When using Spring with a relational database, one of the first tasks is creating an io.r2dbc.spi.ConnectionFactory through the IoC container.

@Configuration
public class ApplicationConfiguration extends AbstractR2dbcConfiguration {

  @Override
  @Bean
  public ConnectionFactory connectionFactory() {
    return ...
  }
}

Using AbstractR2dbcConfiguration registers infrastructure such as DatabaseClient and exception translation for classes annotated with @Repository.

13.3.2. R2DBC Drivers

Spring Data R2DBC supports drivers through the R2DBC SPI. It can use any driver that implements the R2DBC specification, but a dialect is required so Spring Data R2DBC can react to database-specific behavior.

Built-in dialect support includes H2, MariaDB, Microsoft SQL Server, MySQL, jasync-sql MySQL, Postgres, and Oracle. If a driver is not recognized, configure a custom R2dbcDialect. Dialects can also be discovered through DialectResolver and spring.factories.

13.4. R2dbcEntityOperations Data Access API

R2dbcEntityTemplate is the central entry point for Spring Data R2DBC. It provides entity-oriented methods and fluent APIs for querying, inserting, updating, and deleting data.

The entry points such as insert(), select(), and update() follow a natural naming scheme. The API exposes only context-sensitive methods until a terminal method creates and executes SQL. Spring Data R2DBC uses R2dbcDialect to determine bind markers, pagination support, and native data types.

All terminal methods return a Publisher. The actual SQL statement is sent to the database when the publisher is subscribed to.

14. R2DBC Repository

R2DBC repositories build on Spring Data’s repository abstraction and reactive APIs. Repository methods can return Mono, Flux, or other supported reactive wrapper types. Query methods can be derived from method names or declared explicitly.

Use repositories when the application benefits from interface-based data access and consistent CRUD behavior. Use R2dbcEntityTemplate when more direct control over ad-hoc operations or fluent query composition is needed.

Summary

Spring Data R2DBC provides a reactive data access layer for relational databases. It combines R2DBC drivers, Spring configuration, mapping metadata, R2dbcEntityTemplate, and repository support to provide non-blocking database access while preserving familiar Spring Data programming models.