Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/dependencies.adoc[leveloffset=+1] Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repositories.adoc[leveloffset=+1]

This part of the reference documentation explains the core functionality offered by Spring Data R2DBC.

“R2DBC support” introduces the R2DBC module feature set.

“R2DBC Repositories” introduces the repository support for R2DBC.

An easy way to bootstrap setting up a working environment is to create a Spring-based project through start.spring.io.

The repository is also browseable here.

You may also want to set the logging level to DEBUG to see some additional information. To do so, edit the application.properties file to have the following content:

Then you can create a Person class to persist:

Next, you need to create a table structure in your database:

You also need a main application to run:

When you run the main program, the preceding examples produce output similar to the following:

Even in this simple example, there are few things to notice:

There is a GitHub repository with several examples that you can download and play around with to get a feel for how the library works.

One of the first tasks when using relational databases and Spring is to create a io.r2dbc.spi.ConnectionFactory object using the IoC container. The following example explains Java-based configuration.

Spring Data R2DBC includes a reactive, non-blocking DatabaseClient for database interaction. The client has a functional, fluent API with reactive types for declarative composition. DatabaseClient encapsulates resource handling such as opening and closing connections so your application code can make use of executing SQL queries or calling higher-level functionality such as inserting or selecting data.

Another central feature of DatabaseClient is translation of exceptions thrown by R2DBC drivers into Spring’s portable Data Access Exception hierarchy. See “Exception Translation” for more information.

The next section contains an example of how to work with the DatabaseClient in the context of the Spring container.

The Spring framework provides exception translation for a wide variety of database and mapping technologies. The Spring support for R2DBC extends this feature by providing implementations of the R2dbcExceptionTranslator interface.

R2dbcExceptionTranslator is an interface to be implemented by classes that can translate between R2dbcException and Spring’s own org.springframework.dao.DataAccessException, which is agnostic in regard to data access strategy. Implementations can be generic (for example, using SQLState codes) or proprietary (for example, using Postgres error codes) for greater precision.

R2dbcExceptionSubclassTranslator is the implementation of R2dbcExceptionTranslator that is used by default. It considers R2DBC’s categorized exception hierarchy to translate these into Spring’s consistent exception hierarchy. R2dbcExceptionSubclassTranslator uses SqlStateR2dbcExceptionTranslator as fallback if it is not able to translate an exception.

SqlErrorCodeR2dbcExceptionTranslator uses specific vendor codes using Spring JDBC’s SQLErrorCodes. It is more precise than the SQLState implementation. The error code translations are based on codes held in a JavaBean type class called SQLErrorCodes. Instances of this class are created and populated by an SQLErrorCodesFactory, which (as the name suggests) is a factory for creating SQLErrorCodes based on the contents of a configuration file named sql-error-codes.xml from Spring’s Data Access module. This file is populated with vendor codes and based on the ConnectionFactoryName taken from ConnectionFactoryMetadata. The codes for the actual database you are using are used.

The SqlErrorCodeR2dbcExceptionTranslator applies matching rules in the following sequence:

You can extend SqlErrorCodeR2dbcExceptionTranslator, as the following example shows:

In the preceding example, the specific error code (-12345) is translated, while other errors are left to be translated by the default translator implementation. To use this custom translator, you must configure DatabaseClient through the builder method exceptionTranslator, and you must use this DatabaseClient for all of the data access processing where this translator is needed. The following example shows how you can use this custom translator:

Running a statement is the basic functionality that is covered by DatabaseClient. The following example shows what you need to include for minimal but fully functional code that creates a new table:

DatabaseClient is designed for a convenient fluent usage. It exposes intermediate, continuation, and terminal methods at each stage of the execution specification. The example above uses then() to return a completion Publisher that completes as soon as the query (or queries, if the SQL query contains multiple statements) completes.

You have already seen DatabaseClients SQL API that offers you maximum flexibility to execute any type of SQL. DatabaseClient provides a more narrow interface for typical ad-hoc use-cases such as querying, inserting, updating, and deleting data.

The entry points (insert(), select(), update(), and others) follow a natural naming schema based on the operation to be run. Moving on from the entry point, the API is designed to offer only context-dependent methods that lead to a terminating method that creates and runs a SQL statement. Spring Data R2DBC uses a Dialect abstraction to determine bind markers, pagination support and data types natively supported by the underlying driver.

Let’s take a look at a simple query:

The following example declares a more complex query that specifies the table name by name, a WHERE condition and ORDER BY clause:

You can consume Query results in three ways:

You can switch between retrieving a single entity and retrieving multiple entities as through the terminating methods:

A common pattern when using relational databases is grouping multiple queries within a unit of work that is guarded by a transaction. Relational databases typically associate a transaction with a single transport connection. Using different connections hence results in utilizing different transactions. Spring Data R2DBC includes transaction-awareness in DatabaseClient that allows you to group multiple statements within the same transaction using Spring’s Transaction Management. Spring Data R2DBC provides a implementation for ReactiveTransactionManager with R2dbcTransactionManager. See [r2dbc.connections.R2dbcTransactionManager] for further details.

Spring’s declarative Transaction Management is a less invasive, annotation-based approach to transaction demarcation.

This chapter points out the specialties for repository support for R2DBC. This chapter builds on the core repository support explained in [repositories]. Before reading this chapter, you should have a sound understanding of the basic concepts explained there.

To access domain entities stored in a relational database, you can use our sophisticated repository support that eases implementation quite significantly. To do so, create an interface for your repository, as the following example shows:

Right now, this interface serves only to provide type information, but we can add additional methods to it later. To configure R2DBC repositories, you can use the @EnableR2dbcRepositories annotation. If no base package is configured, the infrastructure scans the package of the annotated configuration class. The following example shows how to use Java configuration for a repository:

Because our domain repository extends ReactiveCrudRepository, it provides you with CRUD operations to access the entities. Working with the repository instance is just a matter of dependency injecting it into a client. Consequently, you can retrieve all Person objects would resemble the following code:

The preceding example creates an application context with Spring’s unit test support, which performs annotation-based dependency injection into test cases. Inside the test method, we use the repository to query the database. We use StepVerifier as test aid to verify our expectations against the results.

Most of the data access operations you usually trigger on a repository result in a query being executed against the databases. Defining such a query is a matter of declaring a method on the repository interface, as the following example shows:

Spring obtains an R2DBC connection to the database through a ConnectionFactory. A ConnectionFactory is part of the R2DBC specification and is a generalized connection factory. It lets a container or a framework hide connection pooling and transaction management issues from the application code. As a developer, you need not know details about how to connect to the database. That is the responsibility of the administrator who sets up the ConnectionFactory. You most likely fill both roles as you develop and test code, but you do not necessarily have to know how the production data source is configured.

When you use Spring’s R2DBC layer, you can can configure your own with a connection pool implementation provided by a third party. A popular implementation is R2DBC Pool. Implementations in the Spring distribution are meant only for testing purposes and do not provide pooling.

To configure a ConnectionFactory:

The following example shows how to configure a ConnectionFactory in Java:

The ConnectionFactoryUtils class is a convenient and powerful helper class that provides static methods to obtain connections from ConnectionFactory and close connections if necessary. It supports subscriber Context-bound connections with, for example ConnectionFactoryTransactionManager.

The SmartConnectionFactory interface should be implemented by classes that can provide a connection to a relational database. It extends the ConnectionFactory interface to let classes that use it query whether the connection should be closed after a given operation. This usage is efficient when you know that you need to reuse a connection.

TransactionAwareConnectionFactoryProxy is a proxy for a target ConnectionFactory. The proxy wraps that target ConnectionFactory to add awareness of Spring-managed transactions.

The ConnectionFactoryTransactionManager class is a ReactiveTransactionManager implementation for single R2DBC datasources. It binds an R2DBC connection from the specified data source to the subscriber Context, potentially allowing for one subscriber connection per data source.

Application code is required to retrieve the R2DBC connection through ConnectionFactoryUtils.getConnection(ConnectionFactory) instead of R2DBC’s standard ConnectionFactory.create(). All framework classes (such as DatabaseClient) use this strategy implicitly. If not used with this transaction manager, the lookup strategy behaves exactly like the common one. Thus, it can be used in any case.

The ConnectionFactoryTransactionManager class supports custom isolation levels that get applied to the connection.

MappingR2dbcConverter has a few conventions for mapping objects to rows when no additional mapping metadata is provided. The conventions are:

Unless explicitly configured, an instance of MappingR2dbcConverter is created by default when you create a DatabaseClient. You can create your own instance of the MappingR2dbcConverter. By creating your own instance, you can register Spring converters to map specific classes to and from the database.

You can configure the MappingR2dbcConverter as well as DatabaseClient and ConnectionFactory by using Java-based metadata. The following example uses Spring’s Java-based configuration:

AbstractR2dbcConfiguration requires you to implement a method that defines a ConnectionFactory.

You can add additional converters to the converter by overriding the r2dbcCustomConversions method.

To take full advantage of the object mapping functionality inside the Spring Data R2DBC support, you should annotate your mapped objects with the @Table annotation. Although it is not necessary for the mapping framework to have this annotation (your POJOs are mapped correctly, even without any annotations), it lets the classpath scanner find and pre-process your domain objects to extract the necessary metadata. If you do not use this annotation, your application takes a slight performance hit the first time you store a domain object, because the mapping framework needs to build up its internal metadata model so that it knows about the properties of your domain object and how to persist them. The following example shows a domain object: