Configure the Spring Boot Starter

Overview

In this guide, you can learn how to configure the Spring Boot starter that the MongoDB Extension for Hibernate ORM provides. To learn how to install the starter and create an application that uses it, see Get Started with the Spring Boot Starter.

Activate the Starter

To activate the starter, set the spring.jpa.database-platform property to MongoDB in your application's application.properties file, as shown in the following example:

spring.jpa.database-platform=MongoDB

The starter uses this standard Spring Boot property and requires no dedicated configuration of its own. When the property has any other value or is unset, the starter remains inactive. An inactive starter does not affect your application.

Configure the Connection

The starter reuses the MongoClient instance that Spring Boot creates from the spring.mongodb.* properties. The starter does not create a client of its own and does not manage the client's lifecycle, so your application uses one connection pool for Java Persistence API (JPA) persistence, health checks, metrics, and any other component that uses the client.

The starter uses the database name set in the spring.mongodb.database property. If you do not set that property, the starter uses the database name in the connection string that you set in the spring.mongodb.uri property.

To customize this client, declare a MongoClientSettingsBuilderCustomizer bean. This interface customizes the MongoClientSettings.Builder instance before Spring Boot creates the client.

Set JPA Properties

The starter uses the standard spring.jpa.* properties. The following table describes commonly used properties:

You can also declare HibernatePropertiesCustomizer and EntityManagerFactoryBuilderCustomizer beans to modify the configuration that the starter builds. The HibernatePropertiesCustomizer interface customizes the Hibernate ORM properties that the starter passes to the EntityManagerFactory, and the EntityManagerFactoryBuilderCustomizer interface customizes the builder that creates it.

Scan for Entities and Repositories

The starter scans for entities in the packages that you register by using the @EntityScan annotation. If you register no packages, the starter scans the package of your @SpringBootApplication class and its subpackages.

Declare the @EntityScan annotation on your main application class, as shown in the following example:

@SpringBootApplication
@EntityScan("org.example.model")
public class MovieApplication {
    // ...
}

The starter enables Spring Data JPA repositories in the same package scope. If you declare the @EnableJpaRepositories annotation yourself, your declaration takes precedence over the starter's.

The starter enables these repositories without a SQL DataSource and brings no SQL connection pool. A MongoDB-only application therefore requires no spring.datasource.url property, and Spring Boot does not use its DataSourceAutoConfiguration class.

Configure Field Naming

Unlike a SQL Spring Boot application, which maps entity properties to snake_case column names by default, the starter maps each entity property to a document field of the same name. An entity that you bootstrap through the starter persists the same way as an entity that you bootstrap through Hibernate ORM directly.

To use a different naming strategy, set the strategy explicitly in your application's application.properties file, as shown in the following example:

spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategySnakeCaseImpl

Troubleshoot Startup Errors

When the starter is active but cannot configure a persistence unit, it reports the error at startup. The following table describes these errors:

Use a Dedicated Client

To connect through a client that only the starter uses, such as a client with different credentials, declare a MongoConfigurationContributor bean that sets the client and the database name. When you declare this bean, the starter uses your client instead of the Spring-managed client.

If you declare more than one MongoConfigurationContributor bean, the starter applies them in the order that you specify by using the @Order annotation, and the last bean that sets a value determines that value.

Limitations

The starter has the following limitations:

• The @DataJpaTest annotation is not supported. To test against MongoDB, use the @SpringBootTest annotation, which loads your full application context.

• The starter configures a single persistence unit. To use more than one persistence unit, configure the additional units yourself.