Spring Boot integrates with a number of data technologies, both SQL and NoSQL.
1. SQL Databases
The Spring Framework provides extensive support for working with SQL databases, from direct JDBC access using JdbcTemplate
to complete “object relational mapping” technologies such as Hibernate.
Spring Data provides an additional level of functionality: creating Repository
implementations directly from interfaces and using conventions to generate queries from your method names.
1.1. Configure a DataSource
Java’s javax.sql.DataSource
interface provides a standard method of working with database connections.
Traditionally, a 'DataSource' uses a URL
along with some credentials to establish a database connection.
See the “How-to” section for more advanced examples, typically to take full control over the configuration of the DataSource. |
1.1.1. Embedded Database Support
It is often convenient to develop applications by using an in-memory embedded database. Obviously, in-memory databases do not provide persistent storage. You need to populate your database when your application starts and be prepared to throw away data when your application ends.
The “How-to” section includes a section on how to initialize a database. |
Spring Boot can auto-configure embedded H2, HSQL, and Derby databases.
You need not provide any connection URLs.
You need only include a build dependency to the embedded database that you want to use.
If there are multiple embedded databases on the classpath, set the spring.datasource.embedded-database-connection
configuration property to control which one is used.
Setting the property to none
disables auto-configuration of an embedded database.
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 |
For example, the typical POM dependencies would be as follows:
<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>
You need a dependency on spring-jdbc for an embedded database to be auto-configured.
In this example, it is pulled in transitively through spring-boot-starter-data-jpa .
|
If, for whatever reason, you do configure the connection URL for an embedded database, take care to ensure that the database’s automatic shutdown is disabled.
If you use H2, you should use DB_CLOSE_ON_EXIT=FALSE to do so.
If you use HSQLDB, you should ensure that shutdown=true is not used.
Disabling the database’s automatic shutdown lets Spring Boot control when the database is closed, thereby ensuring that it happens once access to the database is no longer needed.
|
1.1.2. Connection to a Production Database
Production database connections can also be auto-configured by using a pooling DataSource
.
1.1.3. DataSource Configuration
DataSource configuration is controlled by external configuration properties in spring.datasource.*
.
For example, you might declare the following section in application.properties
:
spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
spring.datasource.password=dbpass
spring:
datasource:
url: "jdbc:mysql://localhost/test"
username: "dbuser"
password: "dbpass"
You should at least specify the URL by setting the spring.datasource.url property.
Otherwise, Spring Boot tries to auto-configure an embedded database.
|
Spring Boot can deduce the JDBC driver class for most databases from the URL.
If you need to specify a specific class, you can use the spring.datasource.driver-class-name property.
|
For a pooling DataSource to be created, we need to be able to verify that a valid Driver class is available, so we check for that before doing anything.
In other words, if you set spring.datasource.driver-class-name=com.mysql.jdbc.Driver , then that class has to be loadable.
|
See DataSourceProperties
for more of the supported options.
These are the standard options that work regardless of the actual implementation.
It is also possible to fine-tune implementation-specific settings by using their respective prefix (spring.datasource.hikari.*
, spring.datasource.tomcat.*
, spring.datasource.dbcp2.*
, and spring.datasource.oracleucp.*
).
Refer to the documentation of the connection pool implementation you are using for more details.
For instance, if you use the Tomcat connection pool, you could customize many additional settings, as shown in the following example:
spring.datasource.tomcat.max-wait=10000
spring.datasource.tomcat.max-active=50
spring.datasource.tomcat.test-on-borrow=true
spring:
datasource:
tomcat:
max-wait: 10000
max-active: 50
test-on-borrow: true
This will set the pool to wait 10000ms before throwing an exception if no connection is available, limit the maximum number of connections to 50 and validate the connection before borrowing it from the pool.
1.1.4. Supported Connection Pools
Spring Boot uses the following algorithm for choosing a specific implementation:
-
We prefer HikariCP for its performance and concurrency. If HikariCP is available, we always choose it.
-
Otherwise, if the Tomcat pooling
DataSource
is available, we use it. -
Otherwise, if Commons DBCP2 is available, we use it.
-
If none of HikariCP, Tomcat, and DBCP2 are available and if Oracle UCP is available, we use it.
If you use the spring-boot-starter-jdbc or spring-boot-starter-data-jpa “starters”, you automatically get a dependency to HikariCP .
|
You can bypass that algorithm completely and specify the connection pool to use by setting the spring.datasource.type
property.
This is especially important if you run your application in a Tomcat container, as tomcat-jdbc
is provided by default.
Additional connection pools can always be configured manually, using DataSourceBuilder
.
If you define your own DataSource
bean, auto-configuration does not occur.
The following connection pools are supported by DataSourceBuilder
:
-
HikariCP
-
Tomcat pooling
Datasource
-
Commons DBCP2
-
Oracle UCP &
OracleDataSource
-
Spring Framework’s
SimpleDriverDataSource
-
H2
JdbcDataSource
-
PostgreSQL
PGSimpleDataSource
1.1.5. Connection to a JNDI DataSource
If you deploy your Spring Boot application to an Application Server, you might want to configure and manage your DataSource by using your Application Server’s built-in features and access it by using JNDI.
The spring.datasource.jndi-name
property can be used as an alternative to the spring.datasource.url
, spring.datasource.username
, and spring.datasource.password
properties to access the DataSource
from a specific JNDI location.
For example, the following section in application.properties
shows how you can access a JBoss AS defined DataSource
:
spring.datasource.jndi-name=java:jboss/datasources/customers
spring:
datasource:
jndi-name: "java:jboss/datasources/customers"
1.2. Using JdbcTemplate
Spring’s JdbcTemplate
and NamedParameterJdbcTemplate
classes are auto-configured, and you can @Autowire
them directly into your own beans, as shown in the following example:
@Component
public class MyBean {
private final JdbcTemplate jdbcTemplate;
public MyBean(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
public void doSomething() {
this.jdbcTemplate ...
}
}
You can customize some properties of the template by using the spring.jdbc.template.*
properties, as shown in the following example:
spring.jdbc.template.max-rows=500
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:
-
Hibernate: One of the most popular JPA implementations.
-
Spring Data JPA: Helps you to implement JPA-based repositories.
-
Spring ORM: Core ORM support from the Spring Framework.
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, all packages below your main configuration class (the one annotated with @EnableAutoConfiguration
or @SpringBootApplication
) are searched.
Any classes annotated with @Entity
, @Embeddable
, or @MappedSuperclass
are considered.
A typical entity class resembles the following example:
@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
}
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.
For more complex queries, you can annotate your method with Spring Data’s Query
annotation.
Spring Data repositories usually extend from the Repository
or CrudRepository
interfaces.
If you use auto-configuration, repositories are searched from the package containing your main configuration class (the one annotated with @EnableAutoConfiguration
or @SpringBootApplication
) down.
The following example shows a typical Spring Data repository interface definition:
public interface CityRepository extends Repository<City, Long> {
Page<City> findAll(Pageable pageable);
City findByNameAndStateAllIgnoringCase(String name, String state);
}
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.
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 |
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.
To use Spring Data Envers, make sure your repository extends from RevisionRepository
as show in the following example:
public interface CountryRepository extends RevisionRepository<Country, Long, Integer>, Repository<Country, Long> {
Page<Country> findAll(Pageable pageable);
}
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.jpa.hibernate.ddl-auto=create-drop
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:
|
spring.jpa.properties.hibernate[globally_quoted_identifiers]=true
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.
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.
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
.
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 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 a JdbcConfiguration
subclass to your application.
For complete details of Spring Data JDBC, please refer to 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:
-
You are developing a servlet-based web application.
-
com.h2database:h2
is on the classpath. -
You are using Spring Boot’s developer tools.
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.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.
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:
<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:
@Component
public class MyBean {
private final DSLContext create;
public MyBean(DSLContext dslContext) {
this.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:
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);
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 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.
You can also create your own org.jooq.Configuration
@Bean
if you want to take complete control of the jOOQ configuration.
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 via a ConnectionFactory
, similar to a DataSource
with jdbc.
ConnectionFactory
configuration is controlled by external configuration properties in spring.r2dbc.*
.
For example, you might declare the following section in application.properties
:
spring.r2dbc.url=r2dbc:postgresql://localhost/test
spring.r2dbc.username=dbuser
spring.r2dbc.password=dbpass
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, i.e. 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
, i.e., 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 is taken from the application configuration:
@Configuration(proxyBeanMethods = false)
public class MyR2dbcConfiguration {
@Bean
public ConnectionFactoryOptionsBuilderCustomizer connectionFactoryPortCustomizer() {
return (builder) -> builder.option(ConnectionFactoryOptions.PORT, 5432);
}
}
The following examples show how to set some PostgreSQL connection options:
@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);
}
}
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.
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:
<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 |
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:
@Component
public class MyBean {
private final DatabaseClient databaseClient;
public MyBean(DatabaseClient databaseClient) {
this.databaseClient = databaseClient;
}
}
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.
For more complex queries, you can annotate your method with Spring Data’s Query
annotation.
Spring Data repositories usually extend from the Repository
or CrudRepository
interfaces.
If you use auto-configuration, repositories are searched from the package containing your main configuration class (the one annotated with @EnableAutoConfiguration
or @SpringBootApplication
) down.
The following example shows a typical Spring Data repository interface definition:
public interface CityRepository extends Repository<City, Long> {
Mono<City> findByNameAndStateAllIgnoringCase(String name, String state);
}
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 Boot provides auto-configuration for Redis, MongoDB, Neo4j, Solr, Elasticsearch, Cassandra, Couchbase, LDAP and InfluxDB. You can make use of the other projects, but you must configure them yourself. Refer to the appropriate reference documentation at spring.io/projects/spring-data.
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.
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.
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.
By default, the instance tries to connect to a Redis server at localhost:6379
.
The following listing shows an example of such a bean:
@Component
public class MyBean {
private final StringRedisTemplate template;
public MyBean(StringRedisTemplate template) {
this.template = template;
}
}
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).
By default, a pooled connection factory is auto-configured if commons-pool2
is on the classpath.
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”.
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:
@Component
public class MyBean {
private final MongoDatabaseFactory mongo;
public MyBean(MongoDatabaseFactory mongo) {
this.mongo = mongo;
}
}
If you have defined your own MongoClient
, it will be used to auto-configure a suitable MongoDatabaseFactory
.
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
.
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.data.mongodb.uri=mongodb://user:[email protected]:12345,mongo2.example.com:23456/test
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.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
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:
@Component
public class MyBean {
private final MongoTemplate mongoTemplate;
public MyBean(MongoTemplate mongoTemplate) {
this.mongoTemplate = mongoTemplate;
}
}
See the MongoOperations
Javadoc for complete details.
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.
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:
public interface CityRepository extends Repository<City, Long> {
Page<City> findAll(Pageable pageable);
City findByNameAndStateAllIgnoringCase(String name, String state);
}
You can customize document scanning locations by using the @EntityScan annotation.
|
For complete details of Spring Data MongoDB, including its rich object mapping technologies, refer to 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.
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.
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
.
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.
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”.
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
:
@Component
public class MyBean {
private final Driver driver;
public MyBean(Driver driver) {
this.driver = driver;
}
}
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.neo4j.uri=bolt://my-server:7687
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=secret
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
.
2.3.2. Spring Data Neo4j Repositories
Spring Data includes repository support for Neo4j. For complete details of Spring Data Neo4j, refer to the reference documentation.
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:
public interface CityRepository extends Neo4jRepository<City, Long> {
Optional<City> findOneByNameAndState(String name, String state);
}
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.
You can customize the locations to look for repositories and entities by using @EnableNeo4jRepositories
and @EntityScan
respectively on a @Configuration
-bean.
In an application using the reactive style, a
|
2.4. Solr
Apache Solr is a search engine. Spring Boot offers basic auto-configuration for the Solr 5 client library.
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:
@Component
public class MyBean {
private final SolrClient solr;
public MyBean(SolrClient solr) {
this.solr = solr;
}
}
If you add your own @Bean
of type SolrClient
, it replaces the default.
2.5. Elasticsearch
Elasticsearch is an open source, distributed, RESTful search and analytics engine. Spring Boot offers basic auto-configuration for Elasticsearch clients.
Spring Boot supports several clients:
-
The official Java "Low Level" and "High Level" REST clients
-
The
ReactiveElasticsearchClient
provided by Spring Data Elasticsearch
Spring Boot provides a dedicated “Starter”, spring-boot-starter-data-elasticsearch
.
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 and the "High Level" client.
Spring Boot provides support for the "High Level" client, which ships with org.elasticsearch.client:elasticsearch-rest-high-level-client
.
Additionally, Spring Boot provides support for a reactive client, based on Spring Framework’s WebClient
, that ships with org.springframework.data:spring-data-elasticsearch
.
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.elasticsearch.uris=https://search.example.com:9200
spring.elasticsearch.socket-timeout=10s
spring.elasticsearch.username=user
spring.elasticsearch.password=secret
spring:
elasticsearch:
uris: "https://search.example.com:9200"
socket-timeout: "10s"
username: "user"
password: "secret"
Connecting to Elasticsearch using RestHighLevelClient
If you have elasticsearch-rest-high-level-client
on the classpath, Spring Boot will auto-configure and register a RestHighLevelClient
bean.
In addition to the properties described previously, to fine-tune the RestHighLevelClient
, you can register an arbitrary number of beans that implement RestClientBuilderCustomizer
for more advanced customizations.
To take full control over its registration, define a RestClientBuilder
bean.
If your application needs access to a "Low Level" RestClient , you can get it by calling client.getLowLevelClient() on the auto-configured RestHighLevelClient .
|
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 RestHighLevelClient
bean.
You can further tune how Sniffer
is configured, as shown in the following example:
spring.elasticsearch.restclient.sniffer.interval=10m
spring.elasticsearch.restclient.sniffer.delay-after-failure=30s
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.
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.elasticsearch.webclient.max-in-memory-size=1MB
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.
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:
@Component
public class MyBean {
private final ElasticsearchRestTemplate template;
public MyBean(ElasticsearchRestTemplate template) {
this.template = template;
}
}
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.
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.
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.
For complete details of Spring Data Elasticsearch, refer to 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.
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"
.
You can choose to disable the repositories support with the following property:
spring.data.elasticsearch.repositories.enabled=false
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.
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.data.cassandra.keyspace-name=mykeyspace
spring.data.cassandra.contact-points=cassandrahost1:9042,cassandrahost2:9042
spring.data.cassandra.local-datacenter=datacenter1
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.data.cassandra.keyspace-name=mykeyspace
spring.data.cassandra.contact-points=cassandrahost1,cassandrahost2
spring.data.cassandra.local-datacenter=datacenter1
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 Spring Boot does not look for such a file by default but can load one using For more advanced driver customizations, you can register an arbitrary number of beans that implement |
If you’re using 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:
@Component
public class MyBean {
private final CassandraTemplate template;
public MyBean(CassandraTemplate template) {
this.template = template;
}
}
If you add your own @Bean
of type CassandraTemplate
, it replaces the default.
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
.
For complete details of Spring Data Cassandra, refer to 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.
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.couchbase.connection-string=couchbase://192.168.1.123
spring.couchbase.username=user
spring.couchbase.password=secret
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.couchbase.env.timeouts.connect=3s
spring.couchbase.env.ssl.key-store=/location/of/keystore.jks
spring.couchbase.env.ssl.key-store-password=secret
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. For complete details of Spring Data Couchbase, refer to the reference documentation.
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.data.couchbase.bucket-name=my-bucket
spring:
data:
couchbase:
bucket-name: "my-bucket"
The following examples shows how to inject a CouchbaseTemplate
bean:
@Component
public class MyBean {
private final CouchbaseTemplate template;
public MyBean(CouchbaseTemplate template) {
this.template = template;
}
}
There are a few beans that you can define in your own configuration to override those provided by the auto-configuration:
-
A
CouchbaseMappingContext
@Bean
with a name ofcouchbaseMappingContext
. -
A
CustomConversions
@Bean
with a name ofcouchbaseCustomConversions
. -
A
CouchbaseTemplate
@Bean
with a name ofcouchbaseTemplate
.
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:
@Configuration(proxyBeanMethods = false)
public class MyCouchbaseConfiguration {
@Bean(BeanNames.COUCHBASE_CUSTOM_CONVERSIONS)
public CouchbaseCustomConversions myCustomConversions() {
return new CouchbaseCustomConversions(Arrays.asList(new 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.
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.
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.ldap.urls=ldap://myserver:1235
spring.ldap.username=admin
spring.ldap.password=secret
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.
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.
2.8.2. Spring Data LDAP Repositories
Spring Data includes repository support for LDAP. For complete details of Spring Data LDAP, refer to the reference documentation.
You can also inject an auto-configured LdapTemplate
instance as you would with any other Spring Bean, as shown in the following example:
@Component
public class MyBean {
private final LdapTemplate template;
public MyBean(LdapTemplate template) {
this.template = template;
}
}
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.ldap.embedded.base-dn=dc=spring,dc=io
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. In yaml files, you can use the yaml list notation. In properties files, you must include the index as part of the property name: Properties
Yaml
|
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.
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.
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.
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.
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.influx.url=https://172.0.0.1:8086
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.
InfluxDB relies on OkHttp.
If you need to tune the http client InfluxDB
uses behind the scenes, you can register an InfluxDbOkHttpClientBuilderProvider
bean.
If you need more control over the configuration, consider registering an InfluxDbCustomizer
bean.
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 technolgoies and how to enable them in your application.