MongoDB Extension for Hibernate ORM

Overview

This product enables applications to use databases managed by the MongoDB DBMS via Hibernate ORM.

MongoDB speaks MQL (MongoDB Query Language) instead of SQL. This product works by:

• Creating a JDBC adapter using MongoDB Java Driver, which has to be plugged into Hibernate ORM via a custom ConnectionProvider.
• Translating Hibernate's internal SQL AST into MQL by means of a custom Dialect, which has to be plugged into Hibernate ORM.

User Documentation

• Manual
• API

MongoDB standalone deployments are not supported, because they do not support transactions. If you use one, you may convert it to a replica set.

Maven Artifacts

The groupId:artifactId coordinates: org.mongodb:mongodb-hibernate.

• Maven Central Repository
• Maven Central Repository Search

Examples

Maven is used as a build tool.

The Java module with example applications is located in

• ./example-module

The examples may be run by running the smoke tests as specified in Run Smoke Tests.

Spring Boot & Spring Data JPA

A Spring Boot starter lets a Spring Boot 4.x application use MongoDB through JPA. Add the starter

org.mongodb:mongodb-hibernate-spring-boot-starter

declare MongoDB as the JPA platform, and configure the connection with Spring Boot's standard spring.mongodb.* properties (the value is a MongoDB connection string):

spring.jpa.database-platform=MongoDB
spring.mongodb.uri=mongodb://localhost/mydb
spring.jpa.properties.com.mongodb.hibernate.semantics.nulls=MQL

com.mongodb.hibernate.semantics.nulls is required and must be MQL: it declares that null-comparison semantics follow whatever MongoDB's query language actually does, which is not part of the contract and may change release to release. A future release may add a SQL-semantics option.

When spring.jpa.database-platform is MongoDB, the starter auto-configures a JPA EntityManagerFactory, a JpaTransactionManager, and Spring Data JPA repositories backed by MongoDB. The connection is configured through Spring Boot's spring-boot-mongodb support (the spring.mongodb.* namespace), and the integration borrows that MongoClient rather than creating its own: a single connection pool shared with health checks, metrics, and any other use of the Spring-managed client. This reuses spring-boot-mongodb's client infrastructure and is not Spring Data MongoDB.

The starter brings no SQL connection pool, so a MongoDB-only application needs no spring.datasource.url and Spring Boot's DataSourceAutoConfiguration stays inert. Without spring.jpa.database-platform=MongoDB the starter contributes nothing. It is safe to have on the classpath of a non-MongoDB application.

Requirements

The starter requires Spring Boot 4.x and Hibernate ORM 7.4 or later (the version the MongoDB extension is built against). Spring Boot manages the Hibernate version through its BOM, and some Spring Boot 4.x releases still ship an older Hibernate, for example, Spring Boot 4.0.6 manages Hibernate 7.2.12. When the managed version is below 7.4, the application fails to start with a NoSuchMethodError from the MongoDB dialect. Until your Spring Boot version's BOM ships Hibernate 7.4 or later, override the managed version:

Gradle (with the Spring Boot or io.spring.dependency-management plugin):

ext['hibernate.version'] = '7.4.1.Final'

Maven:

<properties>
    <hibernate.version>7.4.1.Final</hibernate.version>
</properties>

Configuration

The standard Spring Boot JPA properties under spring.jpa.* are honored. For example spring.jpa.show-sql, spring.jpa.hibernate.ddl-auto, and spring.jpa.properties.*, along with any HibernatePropertiesCustomizer / EntityManagerFactoryBuilderCustomizer beans and spring.jpa.open-in-view (Open Session in View, on by default in servlet web applications).

The MongoDB connection uses Spring Boot's spring.mongodb.* properties. To customize the borrowed client further — connection pool sizing, command listeners, UUID representation, and so on — declare a MongoClientSettingsBuilderCustomizer bean, exactly as for any other spring-boot-mongodb application.

Field naming

Unlike a SQL Spring Boot application, the default physical naming strategy is Hibernate's own (the Java property name, e.g. publishYear) rather than Spring Boot's snake_case. MongoDB has no schema to catch a naming mismatch, so a snake_case default could silently leave a collection holding a mix of field names; keeping Hibernate's default means an entity persists the same way whether bootstrapped through this starter or through plain Hibernate ORM. To use snake_case (or any other strategy), set it explicitly:

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

Note: changing the naming strategy after documents have been written changes the field names of new documents only; existing documents are not migrated, which can leave a collection with mixed field names.

Limitations

• Testing: the @DataJpaTest slice is not supported (it wires Spring Boot's SQL JPA auto-configuration); use @SpringBootTest to test against MongoDB. Slice support is tracked by HIBERNATE-179.
• Single persistence unit: a single @Primary EntityManagerFactory is auto-configured.
• Native image: GraalVM native-image execution is not yet validated.

Bug Reports

Use "Extension for Hibernate ORM" at jira.mongodb.org.

Feature Requests

Use "Drivers & Frameworks"/"Frameworks (e.g. Django, Hibernate, EFCore)" at feedback.mongodb.com.

Contributor Documentation

Gradle is used as a build tool.

Build from Source

./gradlew build

Static Code Analysis

Code Formatting

Spotless Gradle plugin is used as a general-purpose formatting tool, Palantir Java Format is used as a Java-specific formatting tool integrated with it.

Check Code Formatting

./gradlew spotlessCheck

Format Code

./gradlew spotlessApply

Code Quality

Error Prone Gradle plugin is used as a Java-specific code analysis tool, NullAway is used as a NullPointerException prevention tool integrated with it. JSpecify annotations are used to specify nullness.

The analysis is done as part of the Gradle compileJava task execution.

Testing

This project uses separate directories for unit, integration, smoke tests:

• ./src/test
• ./src/integrationTest
• ./example-module/src/smokeTest

Run Unit Tests

./gradlew test

Run Integration Tests

The integration tests require a MongoDB deployment that

• is accessible at localhost:27017;
  • You may change the MongoDB connection string via the jakarta.persistence.jdbc.url configuration property in ./src/integrationTest/resources/hibernate.properties.
• has test commands enabled.
  • This may be achieved with the --setParameter enableTestCommands=1 command-line arguments.

./gradlew integrationTest

Run Smoke Tests

The smoke tests with the Tests suffix do not require a MongoDB deployment. The smoke tests with the IntegrationTests suffix, as well as the examples, require a MongoDB deployment that

• is accessible at localhost:27017.
  • You may change this by modifying the examples run by the smoke tests.

source ./.evergreen/java-config.sh \
  && ./gradlew -PjavaVersion=${JAVA_VERSION} publishToMavenLocal \
  && ./example-module/mvnw verify --file ./example-module/pom.xml \
    -DjavaVersion="${JAVA_VERSION}" \
    -DprojectVersion="$(./gradlew -q printProjectVersion)"

Continuous Integration

Evergreen and GitHub Actions are used for continuous integration.