数据

1. SQL 数据库

Spring Framework 为使用 SQL 数据库提供了广泛的支持，通过使用 JDBC 直接访问JdbcTemplate完成 Hibernate 等 “对象关系映射” 技术。Spring Data 提供了另一个级别的功能：创建Repository直接从接口实现，并使用约定从您的方法名称生成查询。spring-doc.cadn.net.cn

1.1. 配置 DataSource

Java 的javax.sql.DataSourceinterface 提供了一种使用数据库连接的标准方法。传统上，'DataSource' 使用URL以及用于建立数据库连接的一些凭证。spring-doc.cadn.net.cn

有关更高级的示例，请参阅“作方法”部分，通常是为了完全控制 DataSource 的配置。

1.1.1. 嵌入式数据库支持

使用内存中嵌入式数据库开发应用程序通常很方便。显然，内存数据库不提供持久存储。您需要在应用程序启动时填充数据库，并准备好在应用程序结束时丢弃数据。spring-doc.cadn.net.cn

“作方法”部分包括有关如何初始化数据库的部分。

Spring Boot 可以自动配置嵌入式 H2、HSQL 和 Derby 数据库。您无需提供任何连接 URL。您只需包含对要使用的嵌入式数据库的构建依赖项。如果 Classpath 上有多个嵌入式数据库，请将spring.datasource.embedded-database-connectionconfiguration 属性来控制使用哪一个。将属性设置为none禁用嵌入式数据库的自动配置。spring-doc.cadn.net.cn

如果您在测试中使用此功能，您可能会注意到，无论您使用多少个应用程序上下文，整个测试套件都会重用同一个数据库。如果要确保每个上下文都有一个单独的嵌入式数据库，则应将spring.datasource.generate-unique-name自true.spring-doc.cadn.net.cn

例如，典型的 POM 依赖项如下所示：spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <scope>runtime</scope>
</dependency>

您需要依赖spring-jdbc以自动配置嵌入式数据库。在此示例中，它是通过spring-boot-starter-data-jpa.

如果出于某种原因，您确实为嵌入式数据库配置了连接 URL，请注意确保禁用数据库的自动关闭。如果使用 H2，则应使用DB_CLOSE_ON_EXIT=FALSE执行此作。如果您使用 HSQLDB，则应确保shutdown=true未使用。禁用数据库的自动关闭可以让 Spring Boot 控制数据库何时关闭，从而确保在不再需要访问数据库时进行关闭。

1.1.2. 连接到生产数据库

生产数据库连接也可以使用池DataSource.spring-doc.cadn.net.cn

1.1.3. DataSource 配置

DataSource 配置由spring.datasource.*. 例如，您可以在application.properties:spring-doc.cadn.net.cn

性能

spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
spring.datasource.password=dbpass

Yaml

spring:
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"

您至少应该通过设置spring.datasource.url财产。否则， Spring Boot 会尝试自动配置嵌入式数据库。

Spring Boot 可以从 URL 中推断出大多数数据库的 JDBC 驱动程序类。如果需要指定特定类，可以使用spring.datasource.driver-class-name财产。

对于池化DataSource要创建，我们需要能够验证有效的Driverclass 可用，因此我们在执行任何作之前都会检查一下。换句话说，如果您将spring.datasource.driver-class-name=com.mysql.jdbc.Driver，则该类必须是可加载的。

看DataSourceProperties了解更多支持的选项。这些是无论实际实现如何都有效的标准选项。还可以使用各自的前缀（spring.datasource.hikari.*,spring.datasource.tomcat.*,spring.datasource.dbcp2.*和spring.datasource.oracleucp.*). 有关更多详细信息，请参阅您正在使用的连接池实现的文档。spring-doc.cadn.net.cn

例如，如果您使用 Tomcat 连接池，则可以自定义许多其他设置，如以下示例所示：spring-doc.cadn.net.cn

性能

spring.datasource.tomcat.max-wait=10000
spring.datasource.tomcat.max-active=50
spring.datasource.tomcat.test-on-borrow=true

Yaml

spring:
  datasource:
    tomcat:
      max-wait: 10000
      max-active: 50
      test-on-borrow: true

这会将池设置为在没有可用连接的情况下等待 10000 毫秒，然后再引发异常，将最大连接数限制为 50 个，并在从池中借用连接之前验证连接。spring-doc.cadn.net.cn

1.1.4. 支持的连接池

Spring Boot 使用以下算法来选择特定实现：spring-doc.cadn.net.cn

我们更喜欢 HikariCP 的性能和并发性。如果 HikariCP 可用，我们总是会选择它。spring-doc.cadn.net.cn
否则，如果 Tomcat 池化DataSource可用，我们使用它。spring-doc.cadn.net.cn
否则，如果 Commons DBCP2 可用，我们就会使用它。spring-doc.cadn.net.cn
如果 HikariCP、Tomcat 和 DBCP2 都不可用，并且 Oracle UCP 可用，则使用它。spring-doc.cadn.net.cn

如果您使用spring-boot-starter-jdbc或spring-boot-starter-data-jpa“starters”，则会自动获得对HikariCP.

您可以完全绕过该算法，并通过设置spring.datasource.type财产。如果您在 Tomcat 容器中运行应用程序，这一点尤其重要，因为tomcat-jdbc默认提供。spring-doc.cadn.net.cn

其他连接池始终可以手动配置，使用DataSourceBuilder. 如果您定义自己的DataSourcebean，则不会进行自动配置。以下连接池由DataSourceBuilder:spring-doc.cadn.net.cn

光CPspring-doc.cadn.net.cn
Tomcat 池Datasourcespring-doc.cadn.net.cn
共享 DBCP2spring-doc.cadn.net.cn
Oracle UCP 和OracleDataSourcespring-doc.cadn.net.cn
Spring 框架的SimpleDriverDataSourcespring-doc.cadn.net.cn
H2 系列JdbcDataSourcespring-doc.cadn.net.cn
PostgreSQL 数据库PGSimpleDataSourcespring-doc.cadn.net.cn
C3P0spring-doc.cadn.net.cn

1.1.5. 连接到 JNDI 数据源

如果将 Spring Boot 应用程序部署到 Application Server，则可能需要使用 Application Server 的内置功能来配置和管理 DataSource，并使用 JNDI 访问它。spring-doc.cadn.net.cn

这spring.datasource.jndi-name属性可以用作spring.datasource.url,spring.datasource.username和spring.datasource.password属性以访问DataSource从特定的 JNDI 位置。例如，以下部分application.properties演示如何访问定义的 JBoss ASDataSource:spring-doc.cadn.net.cn

性能

spring.datasource.jndi-name=java:jboss/datasources/customers

Yaml

spring:
  datasource:
    jndi-name: "java:jboss/datasources/customers"

1.2. 使用 JdbcTemplate

Spring的JdbcTemplate和NamedParameterJdbcTemplate类是自动配置的，你可以@Autowire将它们直接放入您自己的 bean 中，如以下示例所示：spring-doc.cadn.net.cn

Java

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final JdbcTemplate jdbcTemplate;

    public MyBean(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    public void doSomething() {
        this.jdbcTemplate ...
    }

}



Kotlin

import org.springframework.jdbc.core.JdbcTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val jdbcTemplate: JdbcTemplate) {

    fun doSomething() {
        jdbcTemplate.execute("delete from customer")
    }

}




You can customize some properties of the template by using the spring.jdbc.template.* properties, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.jdbc.template.max-rows=500



Yaml

spring:
  jdbc:
    template:
      max-rows: 500









The NamedParameterJdbcTemplate reuses the same JdbcTemplate instance behind the scenes.
If more than one JdbcTemplate is defined and no primary candidate exists, the NamedParameterJdbcTemplate is not auto-configured.



1.3. JPA and Spring Data JPA

The Java Persistence API is a standard technology that lets you “map” objects to relational databases.
The spring-boot-starter-data-jpa POM provides a quick way to get started.
It provides the following key dependencies:spring-doc.cadn.net.cn




Hibernate: One of the most popular JPA implementations.spring-doc.cadn.net.cn


Spring Data JPA: Helps you to implement JPA-based repositories.spring-doc.cadn.net.cn


Spring ORM: Core ORM support from the Spring Framework.spring-doc.cadn.net.cn










We do not go into too many details of JPA or Spring Data here.
You can follow the “Accessing Data with JPA” guide from spring.io and read the Spring Data JPA and Hibernate reference documentation.





1.3.1. Entity Classes

Traditionally, JPA “Entity” classes are specified in a persistence.xml file.
With Spring Boot, this file is not necessary and “Entity Scanning” is used instead.
By default the auto-configuration packages are scanned.spring-doc.cadn.net.cn


Any classes annotated with @Entity, @Embeddable, or @MappedSuperclass are considered.
A typical entity class resembles the following example:spring-doc.cadn.net.cn


Java

import java.io.Serializable;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

@Entity
public class City implements Serializable {

    @Id
    @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private String state;

    // ... additional members, often include @OneToMany mappings

    protected City() {
        // no-args constructor required by JPA spec
        // this one is protected since it should not be used directly
    }

    public City(String name, String state) {
        this.name = name;
        this.state = state;
    }

    public String getName() {
        return this.name;
    }

    public String getState() {
        return this.state;
    }

    // ... etc

}




Kotlin

import java.io.Serializable
import javax.persistence.Column
import javax.persistence.Entity
import javax.persistence.GeneratedValue
import javax.persistence.Id

@Entity
class City : Serializable {

    @Id
    @GeneratedValue
    private val id: Long? = null

    @Column(nullable = false)
    var name: String? = null
        private set

    // ... etc
    @Column(nullable = false)
    var state: String? = null
        private set

    // ... additional members, often include @OneToMany mappings

    protected constructor() {
        // no-args constructor required by JPA spec
        // this one is protected since it should not be used directly
    }

    constructor(name: String?, state: String?) {
        this.name = name
        this.state = state
    }

}










You can customize entity scanning locations by using the @EntityScan annotation.
See the “howto.html” how-to.






1.3.2. Spring Data JPA Repositories

Spring Data JPA repositories are interfaces that you can define to access data.
JPA queries are created automatically from your method names.
For example, a CityRepository interface might declare a findAllByState(String state) method to find all the cities in a given state.spring-doc.cadn.net.cn


For more complex queries, you can annotate your method with Spring Data’s Query annotation.spring-doc.cadn.net.cn


Spring Data repositories usually extend from the Repository or CrudRepository interfaces.
If you use auto-configuration, the auto-configuration packages are searched for repositories.spring-doc.cadn.net.cn








You can customize the locations to look for repositories using @EnableJpaRepositories.





The following example shows a typical Spring Data repository interface definition:spring-doc.cadn.net.cn


Java

import org.springframework.boot.docs.data.sql.jpaandspringdata.entityclasses.City;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.repository.Repository;

public interface CityRepository extends Repository<City, Long> {

    Page<City> findAll(Pageable pageable);

    City findByNameAndStateAllIgnoringCase(String name, String state);

}




Kotlin

import org.springframework.boot.docs.data.sql.jpaandspringdata.entityclasses.City
import org.springframework.data.domain.Page
import org.springframework.data.domain.Pageable
import org.springframework.data.repository.Repository

interface CityRepository : Repository<City?, Long?> {

    fun findAll(pageable: Pageable?): Page<City?>?

    fun findByNameAndStateAllIgnoringCase(name: String?, state: String?): City?

}




Spring Data JPA repositories support three different modes of bootstrapping: default, deferred, and lazy.
To enable deferred or lazy bootstrapping, set the spring.data.jpa.repositories.bootstrap-mode property to deferred or lazy respectively.
When using deferred or lazy bootstrapping, the auto-configured EntityManagerFactoryBuilder will use the context’s AsyncTaskExecutor, if any, as the bootstrap executor.
If more than one exists, the one named applicationTaskExecutor will be used.spring-doc.cadn.net.cn









When using deferred or lazy bootstrapping, make sure to defer any access to the JPA infrastructure after the application context bootstrap phase.
You can use SmartInitializingSingleton to invoke any initialization that requires the JPA infrastructure.
For JPA components (such as converters) that are created as Spring beans, use ObjectProvider to delay the resolution of dependencies, if any.spring-doc.cadn.net.cn












We have barely scratched the surface of Spring Data JPA.
For complete details, see the Spring Data JPA reference documentation.






1.3.3. Spring Data Envers Repositories

If Spring Data Envers is available, JPA repositories are auto-configured to support typical Envers queries.spring-doc.cadn.net.cn


To use Spring Data Envers, make sure your repository extends from RevisionRepository as shown in the following example:spring-doc.cadn.net.cn


Java

import org.springframework.boot.docs.data.sql.jpaandspringdata.entityclasses.Country;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.repository.Repository;
import org.springframework.data.repository.history.RevisionRepository;

public interface CountryRepository extends RevisionRepository<Country, Long, Integer>, Repository<Country, Long> {

    Page<Country> findAll(Pageable pageable);

}




Kotlin

import org.springframework.boot.docs.data.sql.jpaandspringdata.entityclasses.Country
import org.springframework.data.domain.Page
import org.springframework.data.domain.Pageable
import org.springframework.data.repository.Repository
import org.springframework.data.repository.history.RevisionRepository

interface CountryRepository :
        RevisionRepository<Country?, Long?, Int>,
        Repository<Country?, Long?> {

    fun findAll(pageable: Pageable?): Page<Country?>?

}










For more details, check the Spring Data Envers reference documentation.






1.3.4. Creating and Dropping JPA Databases

By default, JPA databases are automatically created only if you use an embedded database (H2, HSQL, or Derby).
You can explicitly configure JPA settings by using spring.jpa.* properties.
For example, to create and drop tables you can add the following line to your application.properties:spring-doc.cadn.net.cn


Properties

spring.jpa.hibernate.ddl-auto=create-drop



Yaml

spring:
  jpa:
    hibernate.ddl-auto: "create-drop"









Hibernate’s own internal property name for this (if you happen to remember it better) is hibernate.hbm2ddl.auto.
You can set it, along with other Hibernate native properties, by using spring.jpa.properties.* (the prefix is stripped before adding them to the entity manager).
The following line shows an example of setting JPA properties for Hibernate:





Properties

spring.jpa.properties.hibernate[globally_quoted_identifiers]=true



Yaml

spring:
  jpa:
    properties:
      hibernate:
        "globally_quoted_identifiers": "true"



The line in the preceding example passes a value of true for the hibernate.globally_quoted_identifiers property to the Hibernate entity manager.spring-doc.cadn.net.cn


By default, the DDL execution (or validation) is deferred until the ApplicationContext has started.
There is also a spring.jpa.generate-ddl flag, but it is not used if Hibernate auto-configuration is active, because the ddl-auto settings are more fine-grained.spring-doc.cadn.net.cn



1.3.5. Open EntityManager in View

If you are running a web application, Spring Boot by default registers OpenEntityManagerInViewInterceptor to apply the “Open EntityManager in View” pattern, to allow for lazy loading in web views.
If you do not want this behavior, you should set spring.jpa.open-in-view to false in your application.properties.spring-doc.cadn.net.cn




1.4. Spring Data JDBC

Spring Data includes repository support for JDBC and will automatically generate SQL for the methods on CrudRepository.
For more advanced queries, a @Query annotation is provided.spring-doc.cadn.net.cn


Spring Boot will auto-configure Spring Data’s JDBC repositories when the necessary dependencies are on the classpath.
They can be added to your project with a single dependency on spring-boot-starter-data-jdbc.
If necessary, you can take control of Spring Data JDBC’s configuration by adding the @EnableJdbcRepositories annotation or an AbstractJdbcConfiguration subclass to your application.spring-doc.cadn.net.cn








For complete details of Spring Data JDBC, see the reference documentation.






1.5. Using H2’s Web Console

The H2 database provides a browser-based console that Spring Boot can auto-configure for you.
The console is auto-configured when the following conditions are met:spring-doc.cadn.net.cn




You are developing a servlet-based web application.spring-doc.cadn.net.cn


com.h2database:h2 is on the classpath.spring-doc.cadn.net.cn


You are using Spring Boot’s developer tools.spring-doc.cadn.net.cn










If you are not using Spring Boot’s developer tools but would still like to make use of H2’s console, you can configure the spring.h2.console.enabled property with a value of true.











The H2 console is only intended for use during development, so you should take care to ensure that spring.h2.console.enabled is not set to true in production.





1.5.1. Changing the H2 Console’s Path

By default, the console is available at /h2-console.
You can customize the console’s path by using the spring.h2.console.path property.spring-doc.cadn.net.cn



1.5.2. Accessing the H2 Console in a Secured Application

H2 Console uses frames and, as it is intended for development only, does not implement CSRF protection measures.
If your application uses Spring Security, you need to configure it tospring-doc.cadn.net.cn




disable CSRF protection for requests against the console,spring-doc.cadn.net.cn


set the header X-Frame-Options to SAMEORIGIN on responses from the console.spring-doc.cadn.net.cn




More information on CSRF and the header X-Frame-Options can be found in the Spring Security Reference Guide.spring-doc.cadn.net.cn


In simple setups, a SecurityFilterChain like the following can be used:spring-doc.cadn.net.cn


Java

import org.springframework.boot.autoconfigure.security.servlet.PathRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Profile("dev")
@Configuration(proxyBeanMethods = false)
public class DevProfileSecurityConfiguration {

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE)
    SecurityFilterChain h2ConsoleSecurityFilterChain(HttpSecurity http) throws Exception {
        http.requestMatcher(PathRequest.toH2Console());
        http.authorizeRequests(yourCustomAuthorization());
        http.csrf((csrf) -> csrf.disable());
        http.headers((headers) -> headers.frameOptions().sameOrigin());
        return http.build();
    }


}




Kotlin

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.Profile
import org.springframework.core.Ordered
import org.springframework.core.annotation.Order
import org.springframework.security.config.Customizer
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Profile("dev")
@Configuration(proxyBeanMethods = false)
class DevProfileSecurityConfiguration {

    @Bean
    @Order(Ordered.HIGHEST_PRECEDENCE)
    fun h2ConsoleSecurityFilterChain(http: HttpSecurity): SecurityFilterChain {
        return http.authorizeHttpRequests(yourCustomAuthorization())
            .csrf().disable()
            .headers().frameOptions().sameOrigin().and()
            .build()
    }


}










The H2 console is only intended for use during development.
In production, disabling CSRF protection or allowing frames for a website may create severe security risks.











PathRequest.toH2Console() returns the correct request matcher also when the console’s path has been customized.







1.6. Using jOOQ

jOOQ Object Oriented Querying (jOOQ) is a popular product from Data Geekery which generates Java code from your database and lets you build type-safe SQL queries through its fluent API.
Both the commercial and open source editions can be used with Spring Boot.spring-doc.cadn.net.cn


1.6.1. Code Generation

In order to use jOOQ type-safe queries, you need to generate Java classes from your database schema.
You can follow the instructions in the jOOQ user manual.
If you use the jooq-codegen-maven plugin and you also use the spring-boot-starter-parent “parent POM”, you can safely omit the plugin’s <version> tag.
You can also use Spring Boot-defined version variables (such as h2.version) to declare the plugin’s database dependency.
The following listing shows an example:spring-doc.cadn.net.cn



<plugin>
    <groupId>org.jooq</groupId>
    <artifactId>jooq-codegen-maven</artifactId>
    <executions>
        ...
    </executions>
    <dependencies>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>${h2.version}</version>
        </dependency>
    </dependencies>
    <configuration>
        <jdbc>
            <driver>org.h2.Driver</driver>
            <url>jdbc:h2:~/yourdatabase</url>
        </jdbc>
        <generator>
            ...
        </generator>
    </configuration>
</plugin>




1.6.2. Using DSLContext

The fluent API offered by jOOQ is initiated through the org.jooq.DSLContext interface.
Spring Boot auto-configures a DSLContext as a Spring Bean and connects it to your application DataSource.
To use the DSLContext, you can inject it, as shown in the following example:spring-doc.cadn.net.cn


Java

import java.util.GregorianCalendar;
import java.util.List;

import org.jooq.DSLContext;

import org.springframework.stereotype.Component;

import static org.springframework.boot.docs.data.sql.jooq.dslcontext.Tables.AUTHOR;

@Component
public class MyBean {

    private final DSLContext create;

    public MyBean(DSLContext dslContext) {
        this.create = dslContext;
    }


}




Kotlin

import org.jooq.DSLContext
import org.springframework.stereotype.Component
import java.util.GregorianCalendar

@Component
class MyBean(private val create: DSLContext) {


}










The jOOQ manual tends to use a variable named create to hold the DSLContext.





You can then use the DSLContext to construct your queries, as shown in the following example:spring-doc.cadn.net.cn


Java

public List<GregorianCalendar> authorsBornAfter1980() {
    return this.create.selectFrom(AUTHOR)
            .where(AUTHOR.DATE_OF_BIRTH.greaterThan(new GregorianCalendar(1980, 0, 1)))
            .fetch(AUTHOR.DATE_OF_BIRTH);




Kotlin

fun authorsBornAfter1980(): List<GregorianCalendar> {
    return create.selectFrom<Tables.TAuthorRecord>(Tables.AUTHOR)
        .where(Tables.AUTHOR?.DATE_OF_BIRTH?.greaterThan(GregorianCalendar(1980, 0, 1)))
        .fetch(Tables.AUTHOR?.DATE_OF_BIRTH)
}





1.6.3. jOOQ SQL Dialect

Unless the spring.jooq.sql-dialect property has been configured, Spring Boot determines the SQL dialect to use for your datasource.
If Spring Boot could not detect the dialect, it uses DEFAULT.spring-doc.cadn.net.cn








Spring Boot can only auto-configure dialects supported by the open source version of jOOQ.






1.6.4. Customizing jOOQ

More advanced customizations can be achieved by defining your own DefaultConfigurationCustomizer bean that will be invoked prior to creating the org.jooq.Configuration @Bean.
This takes precedence to anything that is applied by the auto-configuration.spring-doc.cadn.net.cn


You can also create your own org.jooq.Configuration @Bean if you want to take complete control of the jOOQ configuration.spring-doc.cadn.net.cn




1.7. Using R2DBC

The Reactive Relational Database Connectivity (R2DBC) project brings reactive programming APIs to relational databases.
R2DBC’s io.r2dbc.spi.Connection provides a standard method of working with non-blocking database connections.
Connections are provided by using a ConnectionFactory, similar to a DataSource with jdbc.spring-doc.cadn.net.cn


ConnectionFactory configuration is controlled by external configuration properties in spring.r2dbc.*.
For example, you might declare the following section in application.properties:spring-doc.cadn.net.cn


Properties

spring.r2dbc.url=r2dbc:postgresql://localhost/test
spring.r2dbc.username=dbuser
spring.r2dbc.password=dbpass



Yaml

spring:
  r2dbc:
    url: "r2dbc:postgresql://localhost/test"
    username: "dbuser"
    password: "dbpass"









You do not need to specify a driver class name, since Spring Boot obtains the driver from R2DBC’s Connection Factory discovery.











At least the url should be provided.
Information specified in the URL takes precedence over individual properties, that is name, username, password and pooling options.











The “How-to” section includes a section on how to initialize a database.





To customize the connections created by a ConnectionFactory, that is, set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a ConnectionFactoryOptionsBuilderCustomizer @Bean.
The following example shows how to manually override the database port while the rest of the options are taken from the application configuration:spring-doc.cadn.net.cn


Java

import io.r2dbc.spi.ConnectionFactoryOptions;

import org.springframework.boot.autoconfigure.r2dbc.ConnectionFactoryOptionsBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyR2dbcConfiguration {

    @Bean
    public ConnectionFactoryOptionsBuilderCustomizer connectionFactoryPortCustomizer() {
        return (builder) -> builder.option(ConnectionFactoryOptions.PORT, 5432);
    }

}




Kotlin

import io.r2dbc.spi.ConnectionFactoryOptions
import org.springframework.boot.autoconfigure.r2dbc.ConnectionFactoryOptionsBuilderCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyR2dbcConfiguration {

    @Bean
    fun connectionFactoryPortCustomizer(): ConnectionFactoryOptionsBuilderCustomizer {
        return ConnectionFactoryOptionsBuilderCustomizer { builder ->
            builder.option(ConnectionFactoryOptions.PORT, 5432)
        }
    }

}




The following examples show how to set some PostgreSQL connection options:spring-doc.cadn.net.cn


Java

import java.util.HashMap;
import java.util.Map;

import io.r2dbc.postgresql.PostgresqlConnectionFactoryProvider;

import org.springframework.boot.autoconfigure.r2dbc.ConnectionFactoryOptionsBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyPostgresR2dbcConfiguration {

    @Bean
    public ConnectionFactoryOptionsBuilderCustomizer postgresCustomizer() {
        Map<String, String> options = new HashMap<>();
        options.put("lock_timeout", "30s");
        options.put("statement_timeout", "60s");
        return (builder) -> builder.option(PostgresqlConnectionFactoryProvider.OPTIONS, options);
    }

}




Kotlin

import io.r2dbc.postgresql.PostgresqlConnectionFactoryProvider
import org.springframework.boot.autoconfigure.r2dbc.ConnectionFactoryOptionsBuilderCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyPostgresR2dbcConfiguration {

    @Bean
    fun postgresCustomizer(): ConnectionFactoryOptionsBuilderCustomizer {
        val options: MutableMap<String, String> = HashMap()
        options["lock_timeout"] = "30s"
        options["statement_timeout"] = "60s"
        return ConnectionFactoryOptionsBuilderCustomizer { builder ->
            builder.option(PostgresqlConnectionFactoryProvider.OPTIONS, options)
        }
    }

}




When a ConnectionFactory bean is available, the regular JDBC DataSource auto-configuration backs off.
If you want to retain the JDBC DataSource auto-configuration, and are comfortable with the risk of using the blocking JDBC API in a reactive application, add @Import(DataSourceAutoConfiguration.class) on a @Configuration class in your application to re-enable it.spring-doc.cadn.net.cn


1.7.1. Embedded Database Support

Similarly to the JDBC support, Spring Boot can automatically configure an embedded database for reactive usage.
You need not provide any connection URLs.
You need only include a build dependency to the embedded database that you want to use, as shown in the following example:spring-doc.cadn.net.cn



<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-h2</artifactId>
    <scope>runtime</scope>
</dependency>










If you are using this feature in your tests, you may notice that the same database is reused by your whole test suite regardless of the number of application contexts that you use.
If you want to make sure that each context has a separate embedded database, you should set spring.r2dbc.generate-unique-name to true.spring-doc.cadn.net.cn







1.7.2. Using DatabaseClient

A DatabaseClient bean is auto-configured, and you can @Autowire it directly into your own beans, as shown in the following example:spring-doc.cadn.net.cn


Java

import java.util.Map;

import reactor.core.publisher.Flux;

import org.springframework.r2dbc.core.DatabaseClient;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final DatabaseClient databaseClient;

    public MyBean(DatabaseClient databaseClient) {
        this.databaseClient = databaseClient;
    }

    // ...

    public Flux<Map<String, Object>> someMethod() {
        return this.databaseClient.sql("select * from user").fetch().all();
    }

}




Kotlin

import org.springframework.r2dbc.core.DatabaseClient
import org.springframework.stereotype.Component
import reactor.core.publisher.Flux

@Component
class MyBean(private val databaseClient: DatabaseClient) {

    // ...

    fun someMethod(): Flux<Map<String, Any>> {
        return databaseClient.sql("select * from user").fetch().all()
    }

}





1.7.3. Spring Data R2DBC Repositories

Spring Data R2DBC repositories are interfaces that you can define to access data.
Queries are created automatically from your method names.
For example, a CityRepository interface might declare a findAllByState(String state) method to find all the cities in a given state.spring-doc.cadn.net.cn


For more complex queries, you can annotate your method with Spring Data’s Query annotation.spring-doc.cadn.net.cn


Spring Data repositories usually extend from the Repository or CrudRepository interfaces.
If you use auto-configuration, the auto-configuration packages are searched for repositories.spring-doc.cadn.net.cn


The following example shows a typical Spring Data repository interface definition:spring-doc.cadn.net.cn


Java

import reactor.core.publisher.Mono;

import org.springframework.data.repository.Repository;

public interface CityRepository extends Repository<City, Long> {

    Mono<City> findByNameAndStateAllIgnoringCase(String name, String state);

}




Kotlin

import org.springframework.data.repository.Repository
import reactor.core.publisher.Mono

interface CityRepository : Repository<City?, Long?> {

    fun findByNameAndStateAllIgnoringCase(name: String?, state: String?): Mono<City?>?

}










We have barely scratched the surface of Spring Data R2DBC. For complete details, see the Spring Data R2DBC reference documentation.



2. Working with NoSQL Technologies


Spring Data provides additional projects that help you access a variety of NoSQL technologies, including:spring-doc.cadn.net.cn




Cassandraspring-doc.cadn.net.cn


Couchbasespring-doc.cadn.net.cn


Elasticsearchspring-doc.cadn.net.cn


GemFire or Geodespring-doc.cadn.net.cn


LDAPspring-doc.cadn.net.cn


MongoDBspring-doc.cadn.net.cn


Neo4Jspring-doc.cadn.net.cn


Redisspring-doc.cadn.net.cn




Of these, Spring Boot provides auto-configuration for Cassandra, Couchbase, Elasticsearch, LDAP, MongoDB, Neo4J and Redis.
Additionally, Spring Boot for Apache Geode provides auto-configuration for Apache Geode.
You can make use of the other projects, but you must configure them yourself.
See the appropriate reference documentation at spring.io/projects/spring-data.spring-doc.cadn.net.cn


Spring Boot also provides auto-configuration for InfluxDB and Solr clients.spring-doc.cadn.net.cn


2.1. Redis

Redis is a cache, message broker, and richly-featured key-value store.
Spring Boot offers basic auto-configuration for the Lettuce and Jedis client libraries and the abstractions on top of them provided by Spring Data Redis.spring-doc.cadn.net.cn


There is a spring-boot-starter-data-redis “Starter” for collecting the dependencies in a convenient way.
By default, it uses Lettuce.
That starter handles both traditional and reactive applications.spring-doc.cadn.net.cn








We also provide a spring-boot-starter-data-redis-reactive “Starter” for consistency with the other stores with reactive support.





2.1.1. Connecting to Redis

You can inject an auto-configured RedisConnectionFactory, StringRedisTemplate, or vanilla RedisTemplate instance as you would any other Spring Bean.
The following listing shows an example of such a bean:spring-doc.cadn.net.cn


Java

import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final StringRedisTemplate template;

    public MyBean(StringRedisTemplate template) {
        this.template = template;
    }

    // ...

    public Boolean someMethod() {
        return this.template.hasKey("spring");
    }

}




Kotlin

import org.springframework.data.redis.core.StringRedisTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val template: StringRedisTemplate) {

    // ...

    fun someMethod(): Boolean {
        return template.hasKey("spring")
    }

}




By default, the instance tries to connect to a Redis server at localhost:6379.
You can specify custom connection details using spring.redis.* properties, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.username=user
spring.redis.password=secret



Yaml

spring:
  redis:
    host: "localhost"
    port: 6379
    database: 0
    username: "user"
    password: "secret"









You can also register an arbitrary number of beans that implement LettuceClientConfigurationBuilderCustomizer for more advanced customizations.
ClientResources can also be customized using ClientResourcesBuilderCustomizer.
If you use Jedis, JedisClientConfigurationBuilderCustomizer is also available.
Alternatively, you can register a bean of type RedisStandaloneConfiguration, RedisSentinelConfiguration, or RedisClusterConfiguration to take full control over the configuration.





If you add your own @Bean of any of the auto-configured types, it replaces the default (except in the case of RedisTemplate, when the exclusion is based on the bean name, redisTemplate, not its type).spring-doc.cadn.net.cn


By default, a pooled connection factory is auto-configured if commons-pool2 is on the classpath.spring-doc.cadn.net.cn




2.2. MongoDB

MongoDB is an open-source NoSQL document database that uses a JSON-like schema instead of traditional table-based relational data.
Spring Boot offers several conveniences for working with MongoDB, including the spring-boot-starter-data-mongodb and spring-boot-starter-data-mongodb-reactive “Starters”.spring-doc.cadn.net.cn


2.2.1. Connecting to a MongoDB Database

To access MongoDB databases, you can inject an auto-configured org.springframework.data.mongodb.MongoDatabaseFactory.
By default, the instance tries to connect to a MongoDB server at mongodb://localhost/test.
The following example shows how to connect to a MongoDB database:spring-doc.cadn.net.cn


Java

import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import org.bson.Document;

import org.springframework.data.mongodb.MongoDatabaseFactory;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final MongoDatabaseFactory mongo;

    public MyBean(MongoDatabaseFactory mongo) {
        this.mongo = mongo;
    }

    // ...

    public MongoCollection<Document> someMethod() {
        MongoDatabase db = this.mongo.getMongoDatabase();
        return db.getCollection("users");
    }

}




Kotlin

import com.mongodb.client.MongoCollection
import org.bson.Document
import org.springframework.data.mongodb.MongoDatabaseFactory
import org.springframework.stereotype.Component

@Component
class MyBean(private val mongo: MongoDatabaseFactory) {

    // ...

    fun someMethod(): MongoCollection<Document> {
        val db = mongo.mongoDatabase
        return db.getCollection("users")
    }

}




If you have defined your own MongoClient, it will be used to auto-configure a suitable MongoDatabaseFactory.spring-doc.cadn.net.cn


The auto-configured MongoClient is created using a MongoClientSettings bean.
If you have defined your own MongoClientSettings, it will be used without modification and the spring.data.mongodb properties will be ignored.
Otherwise a MongoClientSettings will be auto-configured and will have the spring.data.mongodb properties applied to it.
In either case, you can declare one or more MongoClientSettingsBuilderCustomizer beans to fine-tune the MongoClientSettings configuration.
Each will be called in order with the MongoClientSettings.Builder that is used to build the MongoClientSettings.spring-doc.cadn.net.cn


You can set the spring.data.mongodb.uri property to change the URL and configure additional settings such as the replica set, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.data.mongodb.uri=mongodb://user:[email protected]:12345,mongo2.example.com:23456/test



Yaml

spring:
  data:
    mongodb:
      uri: "mongodb://user:[email protected]:12345,mongo2.example.com:23456/test"



Alternatively, you can specify connection details using discrete properties.
For example, you might declare the following settings in your application.properties:spring-doc.cadn.net.cn


Properties

spring.data.mongodb.host=mongoserver.example.com
spring.data.mongodb.port=27017
spring.data.mongodb.database=test
spring.data.mongodb.username=user
spring.data.mongodb.password=secret



Yaml

spring:
  data:
    mongodb:
      host: "mongoserver.example.com"
      port: 27017
      database: "test"
      username: "user"
      password: "secret"









If spring.data.mongodb.port is not specified, the default of 27017 is used.
You could delete this line from the example shown earlier.











If you do not use Spring Data MongoDB, you can inject a MongoClient bean instead of using MongoDatabaseFactory.
If you want to take complete control of establishing the MongoDB connection, you can also declare your own MongoDatabaseFactory or MongoClient bean.











If you are using the reactive driver, Netty is required for SSL.
The auto-configuration configures this factory automatically if Netty is available and the factory to use has not been customized already.






2.2.2. MongoTemplate

Spring Data MongoDB provides a MongoTemplate class that is very similar in its design to Spring’s JdbcTemplate.
As with JdbcTemplate, Spring Boot auto-configures a bean for you to inject the template, as follows:spring-doc.cadn.net.cn


Java

import com.mongodb.client.MongoCollection;
import org.bson.Document;

import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final MongoTemplate mongoTemplate;

    public MyBean(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    // ...

    public MongoCollection<Document> someMethod() {
        return this.mongoTemplate.getCollection("users");
    }

}




Kotlin

import com.mongodb.client.MongoCollection
import org.bson.Document
import org.springframework.data.mongodb.core.MongoTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val mongoTemplate: MongoTemplate) {

    // ...

    fun someMethod(): MongoCollection<Document> {
        return mongoTemplate.getCollection("users")
    }

}




See the MongoOperations Javadoc for complete details.spring-doc.cadn.net.cn



2.2.3. Spring Data MongoDB Repositories

Spring Data includes repository support for MongoDB.
As with the JPA repositories discussed earlier, the basic principle is that queries are constructed automatically, based on method names.spring-doc.cadn.net.cn


In fact, both Spring Data JPA and Spring Data MongoDB share the same common infrastructure.
You could take the JPA example from earlier and, assuming that City is now a MongoDB data class rather than a JPA @Entity, it works in the same way, as shown in the following example:spring-doc.cadn.net.cn


Java

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.repository.Repository;

public interface CityRepository extends Repository<City, Long> {

    Page<City> findAll(Pageable pageable);

    City findByNameAndStateAllIgnoringCase(String name, String state);

}




Kotlin

import org.springframework.data.domain.Page
import org.springframework.data.domain.Pageable
import org.springframework.data.repository.Repository

interface CityRepository :
    Repository<City?, Long?> {
    fun findAll(pageable: Pageable?): Page<City?>?
    fun findByNameAndStateAllIgnoringCase(name: String?, state: String?): City?
}




Repositories and documents are found through scanning.
By default, the auto-configuration packages are scanned.
You can customize the locations to look for repositories and documents by using @EnableMongoRepositories and @EntityScan respectively.spring-doc.cadn.net.cn








For complete details of Spring Data MongoDB, including its rich object mapping technologies, see its reference documentation.






2.2.4. Embedded Mongo

Spring Boot offers auto-configuration for Embedded Mongo.
To use it in your Spring Boot application, add a dependency on de.flapdoodle.embed:de.flapdoodle.embed.mongo and set the spring.mongodb.embedded.version property to match the version of MongoDB that your application will use in production.spring-doc.cadn.net.cn








The default download configuration allows access to most of the versions listed in Embedded Mongo’s Version class as well as some others.
Configuring an inaccessible version will result in an error when attempting to download the server.
Such an error can be corrected by defining an appropriately configured DownloadConfigBuilderCustomizer bean.





The port that Mongo listens on can be configured by setting the spring.data.mongodb.port property.
To use a randomly allocated free port, use a value of 0.
The MongoClient created by MongoAutoConfiguration is automatically configured to use the randomly allocated port.spring-doc.cadn.net.cn








If you do not configure a custom port, the embedded support uses a random port (rather than 27017) by default.





If you have SLF4J on the classpath, the output produced by Mongo is automatically routed to a logger named org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongo.spring-doc.cadn.net.cn


You can declare your own IMongodConfig and IRuntimeConfig beans to take control of the Mongo instance’s configuration and logging routing.
The download configuration can be customized by declaring a DownloadConfigBuilderCustomizer bean.spring-doc.cadn.net.cn




2.3. Neo4j

Neo4j is an open-source NoSQL graph database that uses a rich data model of nodes connected by first class relationships, which is better suited for connected big data than traditional RDBMS approaches.
Spring Boot offers several conveniences for working with Neo4j, including the spring-boot-starter-data-neo4j “Starter”.spring-doc.cadn.net.cn


2.3.1. Connecting to a Neo4j Database

To access a Neo4j server, you can inject an auto-configured org.neo4j.driver.Driver.
By default, the instance tries to connect to a Neo4j server at localhost:7687 using the Bolt protocol.
The following example shows how to inject a Neo4j Driver that gives you access, amongst other things, to a Session:spring-doc.cadn.net.cn


Java

import org.neo4j.driver.Driver;
import org.neo4j.driver.Session;
import org.neo4j.driver.Values;

import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final Driver driver;

    public MyBean(Driver driver) {
        this.driver = driver;
    }

    // ...

    public String someMethod(String message) {
        try (Session session = this.driver.session()) {
            return session.writeTransaction(
                    (transaction) -> transaction
                        .run("CREATE (a:Greeting) SET a.message = $message RETURN a.message + ', from node ' + id(a)",
                                Values.parameters("message", message))
                        .single()
                        .get(0)
                        .asString());
        }
    }

}




Kotlin

import org.neo4j.driver.Driver
import org.neo4j.driver.Transaction
import org.neo4j.driver.Values
import org.springframework.stereotype.Component

@Component
class MyBean(private val driver: Driver) {

    // ...

    fun someMethod(message: String?): String {
        driver.session().use { session ->
            return@someMethod session.writeTransaction { transaction: Transaction ->
                transaction.run(
                    "CREATE (a:Greeting) SET a.message = \$message RETURN a.message + ', from node ' + id(a)",
                    Values.parameters("message", message)
                ).single()[0].asString()
            }
        }
    }

}




You can configure various aspects of the driver using spring.neo4j.* properties.
The following example shows how to configure the uri and credentials to use:spring-doc.cadn.net.cn


Properties

spring.neo4j.uri=bolt://my-server:7687
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=secret



Yaml

spring:
  neo4j:
    uri: "bolt://my-server:7687"
    authentication:
      username: "neo4j"
      password: "secret"



The auto-configured Driver is created using ConfigBuilder.
To fine-tune its configuration, declare one or more ConfigBuilderCustomizer beans.
Each will be called in order with the ConfigBuilder that is used to build the Driver.spring-doc.cadn.net.cn



2.3.2. Spring Data Neo4j Repositories

Spring Data includes repository support for Neo4j.
For complete details of Spring Data Neo4j, see the reference documentation.spring-doc.cadn.net.cn


Spring Data Neo4j shares the common infrastructure with Spring Data JPA as many other Spring Data modules do.
You could take the JPA example from earlier and define City as Spring Data Neo4j @Node rather than JPA @Entity and the repository abstraction works in the same way, as shown in the following example:spring-doc.cadn.net.cn


Java

import java.util.Optional;

import org.springframework.data.neo4j.repository.Neo4jRepository;

public interface CityRepository extends Neo4jRepository<City, Long> {

    Optional<City> findOneByNameAndState(String name, String state);

}




Kotlin

import org.springframework.data.neo4j.repository.Neo4jRepository
import java.util.Optional

interface CityRepository : Neo4jRepository<City?, Long?> {

    fun findOneByNameAndState(name: String?, state: String?): Optional<City?>?

}




The spring-boot-starter-data-neo4j “Starter” enables the repository support as well as transaction management.
Spring Boot supports both classic and reactive Neo4j repositories, using the Neo4jTemplate or ReactiveNeo4jTemplate beans.
When Project Reactor is available on the classpath, the reactive style is also auto-configured.spring-doc.cadn.net.cn


Repositories and entities are found through scanning.
By default, the auto-configuration packages are scanned.
You can customize the locations to look for repositories and entities by using @EnableNeo4jRepositories and @EntityScan respectively.spring-doc.cadn.net.cn









In an application using the reactive style, a ReactiveTransactionManager is not auto-configured.
To enable transaction management, the following bean must be defined in your configuration:spring-doc.cadn.net.cn


Java

import org.neo4j.driver.Driver;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.neo4j.core.ReactiveDatabaseSelectionProvider;
import org.springframework.data.neo4j.core.transaction.ReactiveNeo4jTransactionManager;

@Configuration(proxyBeanMethods = false)
public class MyNeo4jConfiguration {

    @Bean
    public ReactiveNeo4jTransactionManager reactiveTransactionManager(Driver driver,
            ReactiveDatabaseSelectionProvider databaseNameProvider) {
        return new ReactiveNeo4jTransactionManager(driver, databaseNameProvider);
    }

}




Kotlin

import org.neo4j.driver.Driver
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.neo4j.core.ReactiveDatabaseSelectionProvider
import org.springframework.data.neo4j.core.transaction.ReactiveNeo4jTransactionManager

@Configuration(proxyBeanMethods = false)
class MyNeo4jConfiguration {

    @Bean
    fun reactiveTransactionManager(driver: Driver,
            databaseNameProvider: ReactiveDatabaseSelectionProvider): ReactiveNeo4jTransactionManager {
        return ReactiveNeo4jTransactionManager(driver, databaseNameProvider)
    }
}










2.4. Solr

Apache Solr is a search engine.
Spring Boot offers basic auto-configuration for the Solr 5 client library.spring-doc.cadn.net.cn


2.4.1. Connecting to Solr

You can inject an auto-configured SolrClient instance as you would any other Spring bean.
By default, the instance tries to connect to a server at localhost:8983/solr.
The following example shows how to inject a Solr bean:spring-doc.cadn.net.cn


Java

import java.io.IOException;

import org.apache.solr.client.solrj.SolrClient;
import org.apache.solr.client.solrj.SolrServerException;
import org.apache.solr.client.solrj.response.SolrPingResponse;

import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final SolrClient solr;

    public MyBean(SolrClient solr) {
        this.solr = solr;
    }

    // ...

    public SolrPingResponse someMethod() throws SolrServerException, IOException {
        return this.solr.ping("users");
    }

}




Kotlin

import org.apache.solr.client.solrj.SolrClient
import org.apache.solr.client.solrj.response.SolrPingResponse
import org.springframework.stereotype.Component

@Component
class MyBean(private val solr: SolrClient) {

    // ...

    fun someMethod(): SolrPingResponse {
        return solr.ping("users")
    }

}




If you add your own @Bean of type SolrClient, it replaces the default.spring-doc.cadn.net.cn




2.5. Elasticsearch

Elasticsearch is an open source, distributed, RESTful search and analytics engine.
Spring Boot offers basic auto-configuration for Elasticsearch clients.spring-doc.cadn.net.cn


Spring Boot supports several clients:spring-doc.cadn.net.cn




The official Java "Low Level" and "High Level" REST clientsspring-doc.cadn.net.cn


The ReactiveElasticsearchClient provided by Spring Data Elasticsearchspring-doc.cadn.net.cn




Spring Boot provides a dedicated “Starter”, spring-boot-starter-data-elasticsearch.spring-doc.cadn.net.cn


2.5.1. Connecting to Elasticsearch Using REST clients

Elasticsearch ships two different REST clients that you can use to query a cluster: the low-level client from the org.elasticsearch.client:elasticsearch-rest-client module and the high-level client from the org.elasticsearch.client:elasticsearch-high-level-client module.
Additionally, Spring Boot provides support for a reactive client, based on Spring Framework’s WebClient, from the org.springframework.data:spring-data-elasticsearch module.
By default, the clients will target localhost:9200.
You can use spring.elasticsearch.* properties to further tune how the clients are configured, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.elasticsearch.uris=https://search.example.com:9200
spring.elasticsearch.socket-timeout=10s
spring.elasticsearch.username=user
spring.elasticsearch.password=secret



Yaml

spring:
  elasticsearch:
    uris: "https://search.example.com:9200"
    socket-timeout: "10s"
    username: "user"
    password: "secret"



Connecting to Elasticsearch Using RestClient

If you have elasticsearch-rest-client on the classpath, Spring Boot will auto-configure and register a RestClient bean.
If you have elasticsearch-rest-high-level-client on the classpath a RestHighLevelClient bean will be auto-configured as well.
Following Elasticsearch’s deprecation of RestHighLevelClient, its auto-configuration is deprecated and will be removed in a future release.
In addition to the properties described previously, to fine-tune the RestClient and RestHighLevelClient, you can register an arbitrary number of beans that implement RestClientBuilderCustomizer for more advanced customizations.
To take full control over the clients' configuration, define a RestClientBuilder bean.spring-doc.cadn.net.cn


Additionally, if elasticsearch-rest-client-sniffer is on the classpath, a Sniffer is auto-configured to automatically discover nodes from a running Elasticsearch cluster and set them on the RestClient bean.
You can further tune how Sniffer is configured, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.elasticsearch.restclient.sniffer.interval=10m
spring.elasticsearch.restclient.sniffer.delay-after-failure=30s



Yaml

spring:
  elasticsearch:
    restclient:
      sniffer:
        interval: "10m"
        delay-after-failure: "30s"




Connecting to Elasticsearch Using ReactiveElasticsearchClient

Spring Data Elasticsearch ships ReactiveElasticsearchClient for querying Elasticsearch instances in a reactive fashion.
It is built on top of WebFlux’s WebClient, so both spring-boot-starter-elasticsearch and spring-boot-starter-webflux dependencies are useful to enable this support.spring-doc.cadn.net.cn


By default, Spring Boot will auto-configure and register a ReactiveElasticsearchClient.
In addition to the properties described previously, the spring.elasticsearch.webclient.* properties can be used to configure reactive-specific settings, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.elasticsearch.webclient.max-in-memory-size=1MB



Yaml

spring:
  elasticsearch:
    webclient:
      max-in-memory-size: "1MB"



If the spring.elasticsearch. and spring.elasticsearch.webclient. configuration properties are not enough and you’d like to fully control the client configuration, you can register a custom ClientConfiguration bean.spring-doc.cadn.net.cn




2.5.2. Connecting to Elasticsearch by Using Spring Data

To connect to Elasticsearch, a RestHighLevelClient bean must be defined,
auto-configured by Spring Boot or manually provided by the application (see previous sections).
With this configuration in place, an
ElasticsearchRestTemplate can be injected like any other Spring bean,
as shown in the following example:spring-doc.cadn.net.cn


Java

import org.springframework.data.elasticsearch.core.ElasticsearchRestTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final ElasticsearchRestTemplate template;

    public MyBean(ElasticsearchRestTemplate template) {
        this.template = template;
    }

    // ...

    public boolean someMethod(String id) {
        return this.template.exists(id, User.class);
    }

}




Kotlin

import org.springframework.data.elasticsearch.core.ElasticsearchRestTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val template: ElasticsearchRestTemplate) {

    // ...

    fun someMethod(id: String): Boolean {
        return template.exists(id, User::class.java)
    }

}




In the presence of spring-data-elasticsearch and the required dependencies for using a WebClient (typically spring-boot-starter-webflux), Spring Boot can also auto-configure a ReactiveElasticsearchClient and a ReactiveElasticsearchTemplate as beans.
They are the reactive equivalent of the other REST clients.spring-doc.cadn.net.cn



2.5.3. Spring Data Elasticsearch Repositories

Spring Data includes repository support for Elasticsearch.
As with the JPA repositories discussed earlier, the basic principle is that queries are constructed for you automatically based on method names.spring-doc.cadn.net.cn


In fact, both Spring Data JPA and Spring Data Elasticsearch share the same common infrastructure.
You could take the JPA example from earlier and, assuming that City is now an Elasticsearch @Document class rather than a JPA @Entity, it works in the same way.spring-doc.cadn.net.cn


Repositories and documents are found through scanning.
By default, the auto-configuration packages are scanned.
You can customize the locations to look for repositories and documents by using @EnableElasticsearchRepositories and @EntityScan respectively.spring-doc.cadn.net.cn








For complete details of Spring Data Elasticsearch, see the reference documentation.





Spring Boot supports both classic and reactive Elasticsearch repositories, using the ElasticsearchRestTemplate or ReactiveElasticsearchTemplate beans.
Most likely those beans are auto-configured by Spring Boot given the required dependencies are present.spring-doc.cadn.net.cn


If you wish to use your own template for backing the Elasticsearch repositories, you can add your own ElasticsearchRestTemplate or ElasticsearchOperations @Bean, as long as it is named "elasticsearchTemplate".
Same applies to ReactiveElasticsearchTemplate and ReactiveElasticsearchOperations, with the bean name "reactiveElasticsearchTemplate".spring-doc.cadn.net.cn


You can choose to disable the repositories support with the following property:spring-doc.cadn.net.cn


Properties

spring.data.elasticsearch.repositories.enabled=false



Yaml

spring:
  data:
    elasticsearch:
      repositories:
        enabled: false





2.6. Cassandra

Cassandra is an open source, distributed database management system designed to handle large amounts of data across many commodity servers.
Spring Boot offers auto-configuration for Cassandra and the abstractions on top of it provided by Spring Data Cassandra.
There is a spring-boot-starter-data-cassandra “Starter” for collecting the dependencies in a convenient way.spring-doc.cadn.net.cn


2.6.1. Connecting to Cassandra

You can inject an auto-configured CassandraTemplate or a Cassandra CqlSession instance as you would with any other Spring Bean.
The spring.data.cassandra.* properties can be used to customize the connection.
Generally, you provide keyspace-name and contact-points as well the local datacenter name, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.data.cassandra.keyspace-name=mykeyspace
spring.data.cassandra.contact-points=cassandrahost1:9042,cassandrahost2:9042
spring.data.cassandra.local-datacenter=datacenter1



Yaml

spring:
  data:
    cassandra:
      keyspace-name: "mykeyspace"
      contact-points: "cassandrahost1:9042,cassandrahost2:9042"
      local-datacenter: "datacenter1"



If the port is the same for all your contact points you can use a shortcut and only specify the host names, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.data.cassandra.keyspace-name=mykeyspace
spring.data.cassandra.contact-points=cassandrahost1,cassandrahost2
spring.data.cassandra.local-datacenter=datacenter1



Yaml

spring:
  data:
    cassandra:
      keyspace-name: "mykeyspace"
      contact-points: "cassandrahost1,cassandrahost2"
      local-datacenter: "datacenter1"









Those two examples are identical as the port default to 9042.
If you need to configure the port, use spring.data.cassandra.port.












The Cassandra driver has its own configuration infrastructure that loads an application.conf at the root of the classpath.spring-doc.cadn.net.cn


Spring Boot does not look for such a file by default but can load one using spring.data.cassandra.config.
If a property is both present in spring.data.cassandra.* and the configuration file, the value in spring.data.cassandra.* takes precedence.spring-doc.cadn.net.cn


For more advanced driver customizations, you can register an arbitrary number of beans that implement DriverConfigLoaderBuilderCustomizer.
The CqlSession can be customized with a bean of type CqlSessionBuilderCustomizer.spring-doc.cadn.net.cn












If you use CqlSessionBuilder to create multiple CqlSession beans, keep in mind the builder is mutable so make sure to inject a fresh copy for each session.





The following code listing shows how to inject a Cassandra bean:spring-doc.cadn.net.cn


Java

import org.springframework.data.cassandra.core.CassandraTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final CassandraTemplate template;

    public MyBean(CassandraTemplate template) {
        this.template = template;
    }

    // ...

    public long someMethod() {
        return this.template.count(User.class);
    }

}




Kotlin

import org.springframework.data.cassandra.core.CassandraTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val template: CassandraTemplate) {

    // ...

    fun someMethod(): Long {
        return template.count(User::class.java)
    }

}




If you add your own @Bean of type CassandraTemplate, it replaces the default.spring-doc.cadn.net.cn



2.6.2. Spring Data Cassandra Repositories

Spring Data includes basic repository support for Cassandra.
Currently, this is more limited than the JPA repositories discussed earlier and needs to annotate finder methods with @Query.spring-doc.cadn.net.cn


Repositories and entities are found through scanning.
By default, the auto-configuration packages are scanned.
You can customize the locations to look for repositories and entities by using @EnableCassandraRepositories and @EntityScan respectively.spring-doc.cadn.net.cn








For complete details of Spring Data Cassandra, see the reference documentation.







2.7. Couchbase

Couchbase is an open-source, distributed, multi-model NoSQL document-oriented database that is optimized for interactive applications.
Spring Boot offers auto-configuration for Couchbase and the abstractions on top of it provided by Spring Data Couchbase.
There are spring-boot-starter-data-couchbase and spring-boot-starter-data-couchbase-reactive “Starters” for collecting the dependencies in a convenient way.spring-doc.cadn.net.cn


2.7.1. Connecting to Couchbase

You can get a Cluster by adding the Couchbase SDK and some configuration.
The spring.couchbase.* properties can be used to customize the connection.
Generally, you provide the connection string, username, and password, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.couchbase.connection-string=couchbase://192.168.1.123
spring.couchbase.username=user
spring.couchbase.password=secret



Yaml

spring:
  couchbase:
    connection-string: "couchbase://192.168.1.123"
    username: "user"
    password: "secret"



It is also possible to customize some of the ClusterEnvironment settings.
For instance, the following configuration changes the timeout to use to open a new Bucket and enables SSL support:spring-doc.cadn.net.cn


Properties

spring.couchbase.env.timeouts.connect=3s
spring.couchbase.env.ssl.key-store=/location/of/keystore.jks
spring.couchbase.env.ssl.key-store-password=secret



Yaml

spring:
  couchbase:
    env:
      timeouts:
        connect: "3s"
      ssl:
        key-store: "/location/of/keystore.jks"
        key-store-password: "secret"









Check the spring.couchbase.env.* properties for more details.
To take more control, one or more ClusterEnvironmentBuilderCustomizer beans can be used.






2.7.2. Spring Data Couchbase Repositories

Spring Data includes repository support for Couchbase.spring-doc.cadn.net.cn


Repositories and documents are found through scanning.
By default, the auto-configuration packages are scanned.
You can customize the locations to look for repositories and documents by using @EnableCouchbaseRepositories and @EntityScan respectively.spring-doc.cadn.net.cn


For complete details of Spring Data Couchbase, see the reference documentation.spring-doc.cadn.net.cn


You can inject an auto-configured CouchbaseTemplate instance as you would with any other Spring Bean, provided a CouchbaseClientFactory bean is available.
This happens when a Cluster is available, as described above, and a bucket name has been specified:spring-doc.cadn.net.cn


Properties

spring.data.couchbase.bucket-name=my-bucket



Yaml

spring:
  data:
    couchbase:
      bucket-name: "my-bucket"



The following examples shows how to inject a CouchbaseTemplate bean:spring-doc.cadn.net.cn


Java

import org.springframework.data.couchbase.core.CouchbaseTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final CouchbaseTemplate template;

    public MyBean(CouchbaseTemplate template) {
        this.template = template;
    }

    // ...

    public String someMethod() {
        return this.template.getBucketName();
    }

}




Kotlin

import org.springframework.data.couchbase.core.CouchbaseTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val template: CouchbaseTemplate) {

    // ...

    fun someMethod(): String {
        return template.bucketName
    }

}




There are a few beans that you can define in your own configuration to override those provided by the auto-configuration:spring-doc.cadn.net.cn




A CouchbaseMappingContext @Bean with a name of couchbaseMappingContext.spring-doc.cadn.net.cn


A CustomConversions @Bean with a name of couchbaseCustomConversions.spring-doc.cadn.net.cn


A CouchbaseTemplate @Bean with a name of couchbaseTemplate.spring-doc.cadn.net.cn




To avoid hard-coding those names in your own config, you can reuse BeanNames provided by Spring Data Couchbase.
For instance, you can customize the converters to use, as follows:spring-doc.cadn.net.cn


Java

import org.assertj.core.util.Arrays;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.couchbase.config.BeanNames;
import org.springframework.data.couchbase.core.convert.CouchbaseCustomConversions;

@Configuration(proxyBeanMethods = false)
public class MyCouchbaseConfiguration {

    @Bean(BeanNames.COUCHBASE_CUSTOM_CONVERSIONS)
    public CouchbaseCustomConversions myCustomConversions() {
        return new CouchbaseCustomConversions(Arrays.asList(new MyConverter()));
    }

}




Kotlin

import org.assertj.core.util.Arrays
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.couchbase.config.BeanNames
import org.springframework.data.couchbase.core.convert.CouchbaseCustomConversions

@Configuration(proxyBeanMethods = false)
class MyCouchbaseConfiguration {

    @Bean(BeanNames.COUCHBASE_CUSTOM_CONVERSIONS)
    fun myCustomConversions(): CouchbaseCustomConversions {
        return CouchbaseCustomConversions(Arrays.asList(MyConverter()))
    }

}






2.8. LDAP

LDAP (Lightweight Directory Access Protocol) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an IP network.
Spring Boot offers auto-configuration for any compliant LDAP server as well as support for the embedded in-memory LDAP server from UnboundID.spring-doc.cadn.net.cn


LDAP abstractions are provided by Spring Data LDAP.
There is a spring-boot-starter-data-ldap “Starter” for collecting the dependencies in a convenient way.spring-doc.cadn.net.cn


2.8.1. Connecting to an LDAP Server

To connect to an LDAP server, make sure you declare a dependency on the spring-boot-starter-data-ldap “Starter” or spring-ldap-core and then declare the URLs of your server in your application.properties, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.ldap.urls=ldap://myserver:1235
spring.ldap.username=admin
spring.ldap.password=secret



Yaml

spring:
  ldap:
    urls: "ldap://myserver:1235"
    username: "admin"
    password: "secret"



If you need to customize connection settings, you can use the spring.ldap.base and spring.ldap.base-environment properties.spring-doc.cadn.net.cn


An LdapContextSource is auto-configured based on these settings.
If a DirContextAuthenticationStrategy bean is available, it is associated to the auto-configured LdapContextSource.
If you need to customize it, for instance to use a PooledContextSource, you can still inject the auto-configured LdapContextSource.
Make sure to flag your customized ContextSource as @Primary so that the auto-configured LdapTemplate uses it.spring-doc.cadn.net.cn



2.8.2. Spring Data LDAP Repositories

Spring Data includes repository support for LDAP.spring-doc.cadn.net.cn


Repositories and documents are found through scanning.
By default, the auto-configuration packages are scanned.
You can customize the locations to look for repositories and documents by using @EnableLdapRepositories and @EntityScan respectively.spring-doc.cadn.net.cn


For complete details of Spring Data LDAP, see the reference documentation.spring-doc.cadn.net.cn


You can also inject an auto-configured LdapTemplate instance as you would with any other Spring Bean, as shown in the following example:spring-doc.cadn.net.cn


Java

import java.util.List;

import org.springframework.ldap.core.LdapTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final LdapTemplate template;

    public MyBean(LdapTemplate template) {
        this.template = template;
    }

    // ...

    public List<User> someMethod() {
        return this.template.findAll(User.class);
    }

}




Kotlin

import org.springframework.ldap.core.LdapTemplate
import org.springframework.stereotype.Component

@Component
class MyBean(private val template: LdapTemplate) {

    // ...

    fun someMethod(): List<User> {
        return template.findAll(User::class.java)
    }

}





2.8.3. Embedded In-memory LDAP Server

For testing purposes, Spring Boot supports auto-configuration of an in-memory LDAP server from UnboundID.
To configure the server, add a dependency to com.unboundid:unboundid-ldapsdk and declare a spring.ldap.embedded.base-dn property, as follows:spring-doc.cadn.net.cn


Properties

spring.ldap.embedded.base-dn=dc=spring,dc=io



Yaml

spring:
  ldap:
    embedded:
      base-dn: "dc=spring,dc=io"










It is possible to define multiple base-dn values, however, since distinguished names usually contain commas, they must be defined using the correct notation.spring-doc.cadn.net.cn


In yaml files, you can use the yaml list notation. In properties files, you must include the index as part of the property name:spring-doc.cadn.net.cn


Properties

spring.ldap.embedded.base-dn[0]=dc=spring,dc=io
spring.ldap.embedded.base-dn[1]=dc=vmware,dc=com



Yaml

spring.ldap.embedded.base-dn:
  - "dc=spring,dc=io"
  - "dc=vmware,dc=com"







By default, the server starts on a random port and triggers the regular LDAP support.
There is no need to specify a spring.ldap.urls property.spring-doc.cadn.net.cn


If there is a schema.ldif file on your classpath, it is used to initialize the server.
If you want to load the initialization script from a different resource, you can also use the spring.ldap.embedded.ldif property.spring-doc.cadn.net.cn


By default, a standard schema is used to validate LDIF files.
You can turn off validation altogether by setting the spring.ldap.embedded.validation.enabled property.
If you have custom attributes, you can use spring.ldap.embedded.validation.schema to define your custom attribute types or object classes.spring-doc.cadn.net.cn




2.9. InfluxDB

InfluxDB is an open-source time series database optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet-of-Things sensor data, and real-time analytics.spring-doc.cadn.net.cn


2.9.1. Connecting to InfluxDB

Spring Boot auto-configures an InfluxDB instance, provided the influxdb-java client is on the classpath and the URL of the database is set, as shown in the following example:spring-doc.cadn.net.cn


Properties

spring.influx.url=https://172.0.0.1:8086



Yaml

spring:
  influx:
    url: "https://172.0.0.1:8086"



If the connection to InfluxDB requires a user and password, you can set the spring.influx.user and spring.influx.password properties accordingly.spring-doc.cadn.net.cn


InfluxDB relies on OkHttp.
If you need to tune the http client InfluxDB uses behind the scenes, you can register an InfluxDbOkHttpClientBuilderProvider bean.spring-doc.cadn.net.cn


If you need more control over the configuration, consider registering an InfluxDbCustomizer bean.spring-doc.cadn.net.cn






3. What to Read Next


You should now have a feeling for how to use Spring Boot with various data technologies.
From here, you can read about Spring Boot’s support for various messaging technologies and how to enable them in your application.spring-doc.cadn.net.cn