MongoDB Extension for Hibernate ORM is Now GA

The MongoDB Extension for Hibernate ORM is now generally available, giving Java teams a production-ready way to use familiar Hibernate APIs with MongoDB’s document model. It is a first-party, open-source library that enables Java applications to use MongoDB as the backing database via the Hibernate ORM. The extension allows Java developers to enjoy the same experience with MongoDB, reducing the friction for those who want to switch.

Java developers can continue using @Entity annotations, Hibernate Query Language (HQL), Criteria Queries, and Session APIs while building new applications or migrating existing Hibernate workloads from relational databases to MongoDB.

The GA release adds support for JOINs (INNER and LEFT OUTER), optimistic locking, Spring Boot auto-configuration, and clearer exception messaging and logging.

The extension requires an upgrade to Hibernate ORM 7.4 LTS to run.

Read on to learn more about these features and how they can help Java developers.

What are the key features in the GA version of the MongoDB Extension for Hibernate ORM?

Now, Java developers using Hibernate have the best of both worlds: they can use familiar Hibernate paradigms for entity operations, queries, and more, while enjoying the flexibility to evolve their schema over time that comes with building on MongoDB.

The extension now supports key features:

• JOIN support (INNER and LEFT OUTER): Query across related MongoDB collections using standard HQL/JPQL `JOIN` syntax, with no manual lookups required.

• Optimistic locking: Version-based concurrency control (`@Version`) prevents conflicting updates to the same entity.

• Spring Boot auto-configuration: Dialect and connection provider are auto-detected from your MongoDB JDBC URL, so manual overrides aren’t needed.

• Improved exception messaging and logging: Clearer error messages and structured logging make issues easy to diagnose, right out of the box.

• Native embedded documents for faster reads: Nest objects and collections inside a single document for higher read performance and a more intuitive data hierarchy.

• Familiar JPA annotations: Use the same annotations and patterns you already know, bridging the document model with standard JPA semantics.

• Query using Hibernate's query languages and MongoDB's Query API: Write queries in HQL/JPQL, including JOINs, comparison operators, and nested paths, or drop into MongoDB's native Query API for advanced operations like vector search, geospatial queries, and MongoDB Search.

Why build your Java applications with MongoDB and Hibernate?

As an ORM framework for Java, Hibernate was created to map object-oriented Java code to relational databases while accommodating their constraints. For example, a Java object with a nested list of properties can't be stored as-is in a relational table; it has to be broken apart into separate, normalized tables linked by foreign keys, and reassembled through joins every time it's read back. This allowed Java developers to focus more on writing code and less on the tedious, often error-prone process of translating their Java objects into relational persistence.

However, while Java developers building with Hibernate can get a more intuitive experience when working with relational databases, using Hibernate cannot eliminate the core constraints of relational data models, including the difficulty of evolving schemas and handling different data types. As modern applications evolve, they demand support for changing data structures, a capability that can be difficult to implement in relational databases.

When developers need to modify the schema (like adding a new column to a table or introducing a new relationship), they must perform a schema migration. This requires careful consideration of data dependencies (like foreign keys), default values for existing rows (or NULL values), and the performance impact of altering large tables.

MongoDB provides developers with the flexibility they need through its document model, while still allowing them to maintain schema control where needed. For example, Java developers can design suitable data models for their applications and easily add new fields or make other changes to their data schema thanks to the document model. Developers no longer need to predefine a row-and-column structure. They can then enforce the schema using MongoDB's built-in schema validation.

Moreover, MongoDB also makes it easier to store and manage various types of data—from simple text and numbers to complex embedded documents and arrays—all within a single database.

Under the hood: How the Extension talks to MongoDB

To explain how this extension works, let’s look at a code example:

With the new MongoDB Extension, Hibernate can map your entities to MongoDB collections and automatically transform common operations, such as persist, find, and HQL queries, into MongoDB commands. For instance, consider a straightforward HQL query like:

The MongoDB dialect translates the query into an equivalent MongoDB aggregation pipeline, such as:

This translation occurs transparently; developers continue to use Hibernate’s familiar API while the framework generates the corresponding MongoDB Query API commands under the hood.

Get started with the MongoDB Extension for Hibernate

The integration is straightforward—simply add the extension to your project's build setup and configure Hibernate to use it. Follow this getting-started guide for a step-by-step walkthrough.

For more technical information about this extension, please refer to our documentation.

Providing feedback

While the extension covers the most common Hibernate patterns for building and migrating production applications, we haven't aimed for full HQL coverage; some SQL constructs simply don't map to MongoDB's document model, and that's by design. For everything else, we'd love to hear what's missing for your use case. You can suggest new features or vote on existing ideas at the MongoDB Feedback Portal, or reach out directly to your MongoDB account team