spring-projects/spring-framework

spring-r2dbc

Active contributors: Juergen Hoeller, Sam Brannen, rstoyanchev

Purpose

spring-r2dbc is the reactive equivalent of spring-jdbc. It provides a fluent, non-blocking API for talking to relational databases over R2DBC (Reactive Relational Database Connectivity), plus a ReactiveTransactionManager implementation. It targets the same workloads as spring-webflux/spring-r2dbc reactive applications.

Directory layout

spring-r2dbc/
└── src/main/java/org/springframework/r2dbc/
    ├── BadSqlGrammarException.java
    ├── core/                                       # DatabaseClient and supporting types
    │   ├── DatabaseClient.java                     # the central type
    │   ├── DefaultDatabaseClient.java
    │   ├── BindMarkers.java
    │   ├── ColumnMapRowMapper.java
    │   ├── binding/
    │   ├── …
    ├── connection/                                 # R2dbcTransactionManager, ConnectionFactory utils
    │   ├── R2dbcTransactionManager.java
    │   ├── ConnectionFactoryUtils.java
    │   ├── ConnectionAccessor.java
    │   ├── lookup/                                 # routing connection factories
    │   └── …
    └── core/binding/, core/sql/, …

Key abstractions

Type	File	Role
`DatabaseClient`	`spring-r2dbc/src/main/java/org/springframework/r2dbc/core/DatabaseClient.java`	Fluent reactive SQL client (analog of `JdbcTemplate`)
`R2dbcTransactionManager`	`spring-r2dbc/src/main/java/org/springframework/r2dbc/connection/R2dbcTransactionManager.java`	`ReactiveTransactionManager` for R2DBC
`ConnectionFactoryUtils`	`spring-r2dbc/src/main/java/org/springframework/r2dbc/connection/ConnectionFactoryUtils.java`	Tx-aware connection acquisition
`BindMarkers`	`spring-r2dbc/src/main/java/org/springframework/r2dbc/core/BindMarkers.java`	Generates dialect-specific parameter markers

How it works

graph LR
    App -->|"sql(…).bind(…).fetch().all()"| DC[DatabaseClient]
    DC -->|"acquires"| CFU[ConnectionFactoryUtils — tx-aware]
    CFU -->|"reactive ConnectionFactory"| R2DBC[R2DBC Driver]
    R2DBC -->|"streams rows"| DC
    DC -->|"Mono / Flux"| App

    Tx["@Transactional + ReactiveTransactionManager"] -.controls.-> CFU

Differences from `spring-jdbc`

Aspect	`spring-jdbc`	`spring-r2dbc`
Programming model	Imperative	Reactive (`Mono`, `Flux`)
Driver SPI	JDBC	R2DBC
Transaction state	`ThreadLocal`	Reactor `Context`
Transaction manager	`DataSourceTransactionManager`	`R2dbcTransactionManager`
Templates	`JdbcTemplate`, `NamedParameterJdbcTemplate`	`DatabaseClient`
Vendor mapping	`sql-error-codes.xml`	`R2dbcExceptionTranslator`

`DatabaseClient` fluent style

client.sql("SELECT id, name FROM users WHERE id = :id")
      .bind("id", userId)
      .map(row -> new User(row.get("id", Long.class), row.get("name", String.class)))
      .first();   // Mono<User>

Integration points

Depends on spring-beans, spring-core, spring-tx (for ReactiveTransactionManager).
Used by Spring Data R2DBC, reactive web applications.
Companion to spring-webflux for reactive end-to-end stacks.

Entry points for modification

New dialect — Provide a BindMarkersFactory for the database's parameter syntax.
Custom routing — Use AbstractRoutingConnectionFactory (in connection/lookup/) for tenant-aware connection routing.