Course topics

By WebNest Studio Engineering Team

Spring Boot Tutorial

R2DBC: Reactive Database Access

A reactive web layer is only non-blocking if everything below it is too. JDBC is inherently blocking — every query parks a thread until the database answers — so WebFlux applications need a different database API. R2DBC (Reactive Relational Database Connectivity) is a non-blocking specification for SQL databases, with drivers for PostgreSQL, MySQL, MariaDB, SQL Server, Oracle and H2.

Spring Data R2DBC offers repositories and a fluent DatabaseClient on top of it. This lesson configures R2DBC in Spring Boot 4, maps entities, writes reactive repositories and custom queries, uses reactive transactions, manages schema with Flyway, and explains R2DBC's limitations compared with JPA.

Setup

Add spring-boot-starter-data-r2dbc and an R2DBC driver such as org.postgresql:r2dbc-postgresql. Configure spring.r2dbc.url (for example r2dbc:postgresql://localhost:5432/webnest), username and password. Spring Boot configures a connection pool (r2dbc-pool), a DatabaseClient, an R2dbcEntityTemplate and a reactive transaction manager.

Entities and Repositories

Spring Data R2DBC maps simple objects or records with @Table, @Id and @Column. Repositories extend ReactiveCrudRepository or R2dbcRepository, return Mono/Flux, and support derived queries and @Query with SQL. Auditing (@CreatedDate) and optimistic locking (@Version) are supported.

Limitations Compared with JPA

R2DBC is deliberately simpler than JPA: there is no lazy loading, no relationship mapping (@OneToMany), no cascading, no first-level cache and no automatic schema generation. You load related data explicitly with separate queries or joins. Many teams find this predictable and easy to reason about; it resembles Spring Data JDBC.

Transactions and Schema

@Transactional works on methods that return Mono or Flux, managed by R2dbcTransactionManager; TransactionalOperator offers programmatic control. Schema migrations still run through Flyway or Liquibase, which use JDBC — so also add the JDBC driver and point spring.flyway.url at the same database.

Examples

Dependencies and configuration

Java
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-r2dbc</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
    <scope>runtime</scope>
</dependency>
<!-- Flyway runs migrations over JDBC -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-flyway</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

# application.yml
spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:5432/webnest
    username: webnest
    password: ${DB_PASSWORD}
    pool:
      max-size: 20
  flyway:
    url: jdbc:postgresql://localhost:5432/webnest
    user: webnest
    password: ${DB_PASSWORD}
Output
Flyway: Successfully applied 2 migrations
Netty started on port 8080 (http)

Entity, repository and custom SQL

Java
@Table("courses")
public record Course(
        @Id Long id,
        String slug,
        String title,
        BigDecimal price,
        @Column("published_at") Instant publishedAt,
        @Version Long version) {}

public interface CourseRepository extends R2dbcRepository<Course, Long> {

    Mono<Course> findBySlug(String slug);

    Flux<Course> findByPriceLessThanOrderByPriceAsc(BigDecimal max);

    @Query("select * from courses where title ilike concat('%', :text, '%') order by title limit :limit")
    Flux<Course> search(String text, int limit);
}

courseRepository.findByPriceLessThanOrderByPriceAsc(new BigDecimal("2000"))
    .map(Course::title)
    .subscribe(System.out::println);
Output
HTML
Java - Core

Loading related data explicitly and using DatabaseClient

Java
public record Lesson(@Id Long id, Long courseId, String title, int position) {}
public record CourseWithLessons(Course course, List<Lesson> lessons) {}

public Mono<CourseWithLessons> withLessons(String slug) {
    return courses.findBySlug(slug)
        .flatMap(c -> lessons.findByCourseIdOrderByPosition(c.id())
            .collectList()
            .map(list -> new CourseWithLessons(c, list)));
}

// Hand-written SQL with DatabaseClient
public Flux<CourseStat> stats() {
    return db.sql("""
            select c.title, count(e.id) as students
            from courses c left join enrollments e on e.course_id = c.id
            group by c.title order by students desc
            """)
        .map((row, meta) -> new CourseStat(row.get("title", String.class), row.get("students", Long.class)))
        .all();
}
Output
withLessons("spring-boot") -> CourseWithLessons[course=Course[slug=spring-boot,...], lessons=[Lesson[title=Spring vs Spring Boot vs Spring MVC,...], ...]]
stats() -> CourseStat[title=Spring Boot, students=1240], CourseStat[title=Java - Core, students=980]

Reactive transactions

Java
@Service
public class EnrollmentService {

    private final CourseRepository courses;
    private final EnrollmentRepository enrollments;
    private final WalletRepository wallets;

    public EnrollmentService(CourseRepository courses, EnrollmentRepository enrollments, WalletRepository wallets) {
        this.courses = courses;
        this.enrollments = enrollments;
        this.wallets = wallets;
    }

    @Transactional
    public Mono<Enrollment> enroll(long studentId, String slug) {
        return courses.findBySlug(slug)
            .switchIfEmpty(Mono.error(new CourseNotFoundException(slug)))
            .flatMap(course -> wallets.debit(studentId, course.price())      // fails if insufficient balance
                .then(enrollments.save(new Enrollment(null, studentId, course.id(), Instant.now()))));
    }
}
Output
enroll(7, "spring-boot") -> COMMIT: wallet debited, enrollment saved
enroll(8, "spring-boot") (insufficient balance) -> ROLLBACK: no enrollment, wallet unchanged

Common Mistakes

  • Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls.
  • Expecting @OneToMany mappings and lazy loading in R2DBC; relationships must be loaded explicitly.
  • Forgetting that Flyway needs a JDBC URL and driver even in an R2DBC application.
  • Using an r2dbc: URL in spring.datasource.url or a jdbc: URL in spring.r2dbc.url.
  • Choosing R2DBC for a traditional MVC app where JPA or JDBC with virtual threads would be simpler.

Exercise

Using the lesson's Dependencies and configuration example, create a small implementation or design sketch that demonstrates R2DBC provides non-blocking SQL access for reactive applications.. Add a test case or scenario that would catch Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls., and describe the expected result.

Show hints
  • Start with Setup and compare your approach with Dependencies and configuration. Identify the decision or behavior the lesson recommends.
  • Walk through your scenario step by step. Confirm that it follows R2DBC provides non-blocking SQL access for reactive applications. and that it would catch the failure described by Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls..

Quick quiz

1. Which choice is a mistake to avoid in R2DBC: Reactive Database Access?

  • A. Expecting @OneToMany mappings and lazy loading in R2DBC; relationships must be loaded explicitly.
  • B. R2DBC provides non-blocking SQL access for reactive applications.
  • C. Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls.
Show answer

C. Avoid this approach: Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls. The lesson recommends: R2DBC provides non-blocking SQL access for reactive applications.

Interview questions

A teammate is about to make this mistake: Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls. How would you diagnose and correct it using the lesson's guidance?

Show answer

R2DBC provides non-blocking SQL access for reactive applications. Apply this in Setup; the example Dependencies and configuration shows one way to do it. Avoid Mixing JPA repositories into a WebFlux app "just for one query", reintroducing blocking calls. and explain how your implementation or design prevents that failure.

Key Points to Remember

  • R2DBC provides non-blocking SQL access for reactive applications.
  • spring-boot-starter-data-r2dbc + an R2DBC driver + spring.r2dbc.* configure it.
  • R2dbcRepository returns Mono/Flux and supports derived queries, @Query, @Version and auditing.
  • No lazy loading or relationship mapping — load related data explicitly or with DatabaseClient.
  • @Transactional works on reactive methods; migrations still use Flyway over JDBC.

Practice in the playground

Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.

Run the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.

WebNest Studio

Written by

WebNest Studio Engineering Team

Practical lessons from developers working with Java, Python, React, databases and production systems.

Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering