CREATE TABLE IF NOT EXISTS customer (id SERIAL PRIMARY KEY, first_name VARCHAR(255), last_name VARCHAR(255));
Accessing data with R2DBC
This guide walks you through the process of building an application that uses Spring Data R2DBC to store and retrieve data in a relational database using reactive database drivers.
What You Will build
You will build an application that stores Customer
POJOs (Plain Old Java Objects) in a memory-based database.
What You Need
-
About 15 minutes
-
A favorite text editor or IDE
-
Java 17 or later
-
You can also import the code straight into your IDE:
How to complete this guide
Like most Spring Getting Started guides, you can start from scratch and complete each step or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.
To start from scratch, move on to Starting with Spring Initializr.
To skip the basics, do the following:
-
Download and unzip the source repository for this guide, or clone it using Git:
git clone https://github.com/spring-guides/{project_id}.git
-
cd into
{project_id}/initial
-
Jump ahead to Define a Schema.
When you finish, you can check your results against the code in {project_id}/complete
.
Starting with Spring Initializr
You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.
To manually initialize the project:
-
Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.
-
Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.
-
Click Dependencies and select Spring Data R2DBC and H2 Database.
-
Click Generate.
-
Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.
If your IDE has the Spring Initializr integration, you can complete this process from your IDE. |
You can also fork the project from Github and open it in your IDE or other editor. |
Define a Schema
In this example, you store Customer
objects, each annotated as a R2DBC entity. The following listing shows the SQL schema class (in src/main/resources/schema.sql
):
Here you have a customer
table with three columns: id
, first_name
, and last_name
. The id
column is auto-incremented, the other columns follow the default snake case naming scheme. Later on, we need to register a ConnectionFactoryInitializer
to pick up the schema.sql
file during application startup to initialize the database schema. Because the H2 driver is on the class path and we haven’t specified a connection URL, Spring Boot starts an embedded H2 database.
Define a Simple Entity
In this example, you store Customer
objects, each annotated as a R2DBC entity. The following listing shows the Customer class (in src/main/java/com/example/accessingdatar2dbc/Customer.java
):
package com.example.accessingdatar2dbc;
import org.springframework.data.annotation.Id;
public class Customer {
@Id
private Long id;
private final String firstName;
private final String lastName;
public Customer(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
public Long getId() {
return this.id;
}
public void setId(Long id) {
this.id = id;
}
public String getFirstName() {
return this.firstName;
}
public String getLastName() {
return this.lastName;
}
@Override
public String toString() {
return String.format(
"Customer[id=%d, firstName='%s', lastName='%s']",
id, firstName, lastName);
}
}
Here you have a Customer
class with three attributes: id
, firstName
, and lastName
. The Customer
class is minimally annotated. The id
property is annotated with @Id
so that Spring Data R2DBC can identify the primary key. By default, primary keys are assumed to be generated by the database on INSERT
.
The other two properties, firstName
and lastName
, are left unannotated. It is assumed that they are mapped to columns that share the same names as the properties themselves.
The convenient toString()
method print outs the customer’s properties.
Create Simple Queries
Spring Data R2DBC focuses on using R2DBC as underlying technology to store data in a relational database. Its most compelling feature is the ability to create repository implementations, at runtime, from a repository interface.
To see how this works, create a repository interface that works with Customer
entities as the following listing (in src/main/java/com/example/accessingdatar2dbc/CustomerRepository.java
) shows:
package com.example.accessingdatar2dbc;
import org.springframework.data.r2dbc.repository.Query;
import org.springframework.data.repository.reactive.ReactiveCrudRepository;
import reactor.core.publisher.Flux;
public interface CustomerRepository extends ReactiveCrudRepository<Customer, Long> {
@Query("SELECT * FROM customer WHERE last_name = :lastname")
Flux<Customer> findByLastName(String lastName);
}
CustomerRepository
extends the ReactiveCrudRepository
interface. The type of entity and ID that it works with, Customer
and Long
, are specified in the generic parameters on ReactiveCrudRepository
. By extending ReactiveCrudRepository
, CustomerRepository
inherits several methods for working with Customer
persistence, including methods for saving, deleting, and finding Customer
entities using reactive types.
Spring Data R2DBC also lets you define other query methods by annotating these with @Query
. For example, CustomerRepository
includes the findByLastName()
method.
In a typical Java application, you might expect to write a class that implements CustomerRepository
. However, that is what makes Spring Data R2DBC so powerful: You need not write an implementation of the repository interface. Spring Data R2DBC creates an implementation when you run the application.
Now you can wire up this example and see what it looks like!
Create an Application Class
Spring Initializr creates a simple class for the application. The following listing shows the class that Initializr created for this example (in src/main/java/com/example/accessingdatar2dbc/AccessingDataR2dbcApplication.java
):
package com.example.accessingdatar2dbc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class AccessingDataR2dbcApplication {
public static void main(String[] args) {
SpringApplication.run(AccessingDataR2dbcApplication.class, args);
}
}
@SpringBootApplication
is a convenience annotation that adds all of the following:
-
@Configuration
: Tags the class as a source of bean definitions for the application context. -
@EnableAutoConfiguration
: Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. For example, ifspring-webmvc
is on the classpath, this annotation flags the application as a web application and activates key behaviors, such as setting up aDispatcherServlet
. -
@ComponentScan
: Tells Spring to look for other components, configurations, and services in thecom/example
package, letting it find the controllers.
The main()
method uses Spring Boot’s SpringApplication.run()
method to launch an application. Did you notice that there was not a single line of XML? There is no web.xml
file, either. This web application is 100% pure Java and you did not have to deal with configuring any plumbing or infrastructure.
Now you need to modify the simple class that the Initializr created for you. To get output (to the console, in this example), you need to set up a logger. Then you need to set up the initializer to setup the schema and some data and use it to generate output. The following listing shows the finished AccessingDataR2dbcApplication
class (in src/main/java/com/example/accessingdatar2dbc/AccessingDataR2dbcApplication.java
):
package com.example.accessingdatar2dbc;
import io.r2dbc.spi.ConnectionFactory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.core.io.ClassPathResource;
import org.springframework.r2dbc.connection.init.ConnectionFactoryInitializer;
import org.springframework.r2dbc.connection.init.ResourceDatabasePopulator;
import java.time.Duration;
import java.util.Arrays;
@SpringBootApplication
public class AccessingDataR2dbcApplication {
private static final Logger log = LoggerFactory.getLogger(AccessingDataR2dbcApplication.class);
public static void main(String[] args) {
SpringApplication.run(AccessingDataR2dbcApplication.class, args);
}
@Bean
public CommandLineRunner demo(CustomerRepository repository) {
return (args) -> {
// save a few customers
repository.saveAll(Arrays.asList(new Customer("Jack", "Bauer"),
new Customer("Chloe", "O'Brian"),
new Customer("Kim", "Bauer"),
new Customer("David", "Palmer"),
new Customer("Michelle", "Dessler")))
.blockLast(Duration.ofSeconds(10));
// fetch all customers
log.info("Customers found with findAll():");
log.info("-------------------------------");
repository.findAll().doOnNext(customer -> {
log.info(customer.toString());
}).blockLast(Duration.ofSeconds(10));
log.info("");
// fetch an individual customer by ID
repository.findById(1L).doOnNext(customer -> {
log.info("Customer found with findById(1L):");
log.info("--------------------------------");
log.info(customer.toString());
log.info("");
}).block(Duration.ofSeconds(10));
// fetch customers by last name
log.info("Customer found with findByLastName('Bauer'):");
log.info("--------------------------------------------");
repository.findByLastName("Bauer").doOnNext(bauer -> {
log.info(bauer.toString());
}).blockLast(Duration.ofSeconds(10));;
log.info("");
};
}
}
The AccessingDataR2dbcApplication
class includes a main()
method that puts the CustomerRepository
through a few tests. First, it fetches the CustomerRepository
from the Spring application context. Then it saves a handful of Customer
objects, demonstrating the save()
method and setting up some data to use. Next, it calls findAll()
to fetch all Customer
objects from the database. Then it calls findById()
to fetch a single Customer
by its ID. Finally, it calls findByLastName()
to find all customers whose last name is "Bauer".
R2DBC is a reactive programming technology. At the same time we’re using it in a synchronized, imperative flow and that is why we’re required to synchronize each call with a variant of the block(…)
method. In a typical reactive application, the resulting Mono
or Flux
would represent a pipeline of operators that is handed back to a web controller or event processor that subscribes to the reactive sequence without blocking the calling thread.
By default, Spring Boot enables R2DBC repository support and looks in the package (and its subpackages) where @SpringBootApplication is located. If your configuration has R2DBC repository interface definitions located in a package that is not visible, you can point out alternate packages by using @EnableR2dbcRepositories and its type-safe basePackageClasses=MyRepository.class parameter. |
Build an executable JAR
You can run the application from the command line with Gradle or Maven. You can also build a single executable JAR file that contains all the necessary dependencies, classes, and resources and run that. Building an executable jar makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.
If you use Gradle, you can run the application by using ./gradlew bootRun
. Alternatively, you can build the JAR file by using ./gradlew build
and then run the JAR file, as follows:
If you use Maven, you can run the application by using ./mvnw spring-boot:run
. Alternatively, you can build the JAR file with ./mvnw clean package
and then run the JAR file, as follows:
The steps described here create a runnable JAR. You can also build a classic WAR file. |
When you run your application, you should see output similar to the following:
== Customers found with findAll(): Customer[id=1, firstName='Jack', lastName='Bauer'] Customer[id=2, firstName='Chloe', lastName='O'Brian'] Customer[id=3, firstName='Kim', lastName='Bauer'] Customer[id=4, firstName='David', lastName='Palmer'] Customer[id=5, firstName='Michelle', lastName='Dessler'] == Customer found with findOne(1L): Customer[id=1, firstName='Jack', lastName='Bauer'] == Customer found with findByLastName('Bauer'): Customer[id=1, firstName='Jack', lastName='Bauer'] Customer[id=3, firstName='Kim', lastName='Bauer']
Summary
Congratulations! You have written a simple application that uses Spring Data R2DBC to save objects to and fetch them from a database, all without writing a concrete repository implementation.
See Also
The following guides may also be helpful:
Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.
All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing. |