[opensourcedex]

hibernate-orm is a free, open source databases project written in Java and released under Apache-2.0. It has 6,471 GitHub stars, 3,818 forks and 152 open issues, and was last pushed 34 minutes ago. On this registry it ranks #121 of 203 tracked projects in Databases, with 5 head-to-head comparisons available.

What is hibernate-orm?

Hibernate ORM is an object/relational mapping framework for Java that exposes relational data in a natural and type-safe form and serves as the de facto standard implementation of the Java Persistence API, now known as Jakarta Persistence, for Java developers and teams building applications on relational databases.

What it is

Hibernate ORM is a persistence framework written in Java and released under the Apache-2.0 licence, with its home at hibernate.org. It is the de facto standard implementation of the Java Persistence API (now Jakarta Persistence), and it also implements the Jakarta Query and Jakarta Data specifications. Its purpose is to expose relational data in a natural and type-safe form, so that application code works with ordinary Java objects rather than with raw result sets.

The concrete problem it solves is the hand-written persistence layer. Rather than composing SQL strings and mapping result sets by hand over JDBC, a Java program declares its mapping and lets Hibernate ORM handle the translation between object state and relational tables. This places it in the Jakarta EE and JPA ecosystem, where it replaces bespoke JDBC-based persistence code with a standard, specification-backed API. It lets a program write complex queries and work with their results, synchronize changes made in memory with the database, respect the ACID properties of transactions, automatically handle temporal data and audit logging, take care of multi-tenancy and row-level security, and apply performance optimizations after the basic persistence logic has already been written.

Key capabilities

  • Implements Jakarta Persistence, Jakarta Query, and Jakarta Data, giving applications a specification-standard persistence API rather than a proprietary one.
  • Maps Java objects onto relational tables and returns query results in a type-safe form.
  • Synchronizes changes made in memory with the database, so that in-memory object state and stored rows stay consistent.
  • Respects the ACID properties of transactions.
  • Handles temporal data and audit logging automatically, the area covered by the Envers topic.
  • Supports multi-tenancy and row-level security.
  • Allows performance optimizations to be applied after the basic persistence logic is already written, rather than requiring it to be planned up front.

Who uses it and how

  • Jakarta EE applications that need a JPA-compliant persistence layer, since Hibernate ORM is the reference implementation of the Jakarta Persistence specification.
  • Teams that need an audit trail or historical record of entity changes, which the temporal data and audit logging support addresses.
  • Multi-tenant applications that need isolation between tenants and row-level security enforced at the persistence layer.
  • Applications with complex query requirements, where the Jakarta Query support lets queries be expressed against the object model instead of through hand-written JDBC code.
  • Contributors building Hibernate ORM itself, who need JDK 25 and use the Gradle Wrapper to compile sources into Java 17 bytecode.

Getting started

Hibernate ORM is consumed as the Maven Central artifact org.hibernate.orm:hibernate-core. The configuration documentation explains how to include Hibernate ORM in a Java project and how to configure a connection to the database.

How it compares

The facts provided name no competing ORM products or paid alternatives, so Hibernate ORM stands alone in this registry. What the facts do establish is its position relative to the specifications it implements: it is described as the de facto standard implementation of Jakarta Persistence, Jakarta Query, and Jakarta Data, meaning applications written against those APIs can adopt it without changing their persistence code.

When to use it — and when not to

Hibernate ORM is the reasonable choice for a Java application that stores its data in a relational database and wants a specification-standard persistence API rather than a bespoke JDBC layer. A team building from source must have JDK 25 available, and any deployment needs a relational database reachable over JDBC, so projects outside Java or projects storing data in non-relational stores should look elsewhere. One honest caveat: the README is build-oriented and thin on usage guidance, covering Gradle tasks and the Gradle Wrapper more thoroughly than it covers configuration, so the linked configuration documentation and hibernate.org remain the real entry points.

project readme (upstream, from github) — read inline

== Hibernate ORM

image:https://img.shields.io/maven-central/v/org.hibernate.orm/hibernate-core.svg?label=Maven%20Central&style=for-the-badge[Maven Central,link=https://central.sonatype.com/search?namespace=org.hibernate.orm&sort=name] image:https://img.shields.io/github/actions/workflow/status/hibernate/hibernate-orm/ci.yml?branch=main&logo=GitHub&style=for-the-badge[GitHub Actions Status,link=https://github.com/hibernate/hibernate-orm/actions/workflows/ci.yml?query=branch%3Amain] image:https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?style=for-the-badge&logo=gradle[Develocity,link=https://develocity.commonhaus.dev/scans?search.rootProjectNames=Hibernate%20ORM] image:https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/hibernate/orm/hibernate-core/badge.json&style=for-the-badge[Reproducible Builds,link=https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/hibernate/orm/hibernate-core/README.md] image:https://testpilot.oracle.com/ords/testpilot/badges/github/hibernate/hibernate-orm[Oracle Test Pilot,link=https://testpilot.oracle.com/]

Hibernate ORM is a powerful object/relational mapping solution for Java, the de facto standard implementation of the https://www.oracle.com/java/technologies/persistence-jsp.html[Java Persistence API] (now also known as https://jakarta.ee/specifications/persistence/4.0/[Jakarta Persistence]), https://jakarta.ee/specifications/query/1.0/[Jakarta Query], and https://jakarta.ee/specifications/data/1.1/[Jakarta Data].

Hibernate exposes relational data in a natural and type safe form,

  • making it easy to write complex queries and work with their results,
  • letting the program easily synchronize changes made in memory with the database,
  • respecting the ACID properties of transactions,
  • automatically handling temporal data and audit logging,
  • taking care of multi-tenancy and row-level security,
  • and allowing performance optimizations to be made after the basic persistence logic has already been written.

Hibernate is the best way for a program written in Java to take advantage of the power of the relational model, and of the expressivity of SQL, without sacrificing performance or code reuse.

See https://hibernate.org/orm/[hibernate.org] for more information.

== Getting started

Documentation for Hibernate ORM is available at:

https://github.com/hibernate/hibernate-orm/blob/main/documentation/src/main/asciidoc/introduction/Configuration.adoc[This page] explains how to include Hibernate ORM in a Java project and configure a connection to the database.

== Building from sources

The build requires at least JDK 25, and produces Java 17 bytecode.

Hibernate uses https://gradle.org[Gradle] as its build tool. See the Gradle Primer section below if you're new to Gradle.

Contributors should read the link:CONTRIBUTING.md[Contributing Guide].

See the guides for setting up https://hibernate.org/community/contribute/intellij-idea/[IntelliJ] or https://hibernate.org/community/contribute/eclipse-ide/[Eclipse] as your development environment.

== Gradle Primer

The Gradle build tool has excellent documentation.

Here we summarize the features you'll need to get started in this project.

NOTE: The project has a https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle Wrapper]. The rest of the section will assume execution via the wrapper.

=== Executing Tasks

To print a list of available build tasks, execute:

./gradlew tasks

To execute a task across all modules, simply execute the task from the root directory.

cd hibernate-orm ./gradlew build

Gradle visits each subproject and executes the task if the subproject defines it.

To execute a task in a specific module, either:

  • cd into that module directory and execute the task, or
  • explicitly qualify the task name with the name of the module.

For example, to run the tests for the hibernate-core module from the root directory you could type:

./gradlew hibernate-core:test

=== Common tasks

The common tasks you might use in building Hibernate include:

build :: Assembles (jars) and tests this project compile :: Performs all compilation tasks including staging resources from both main and test jar :: Generates a jar archive with all the compiled classes test :: Runs the tests publishToMavenLocal or pTML :: Installs the project jar to your local Maven cache at ~/.m2/repository. Note that Gradle never uses this, but it can be useful for testing a build with other local Maven-based builds. clean :: Cleans the build directory

== Testing and databases

Testing Hibernate against an embedded h2 database is easy. Just run:

./gradlew test

To run against another database:

  1. using podman or docker, and then

  2. run the tests with the correct > for that database.

=== Using profiles [[profiles]]

The Hibernate build defines several database testing profiles in local.databases.gradle. A profile may be activated by name using the db build property which can be passed either:

  • as a JVM system property -Ddb=..., or
  • as a Gradle project property -Pdb=....

Examples below use the Gradle project property.

gradle clean build -Pdb=postgresql

To run a test from your IDE, you need to ensure the property expansions happen. Use the following command:

gradle clean compile -Pdb=postgresql

NOTE: To run tests against a JDBC driver that is not available via Maven central, add the driver to your local Maven repository (~/.m2/repository) or to a personal Maven repository server.

=== Starting a test database as a container [[start-test-database]]

If podman or docker is installed, there's no need to install any database to test Hibernate. The script db.sh starts a preconfigured database which can be used for testing.

Simply run the following command:

./db.sh postgresql

Running ./db.sh without an argument prints a list of available database configurations.

By default, ./db.sh kills any previously started database. To keep multiple databases running, use --keep-orphans or -k:

./db.sh -k postgresql ./db.sh -k mysql

When the database is properly started, run tests with the corresponding profile, for example, -Pdb=postgresql for PostgreSQL. The system property dbHost configures the IP address of your docker host.

The command for running tests might look like the following:

./gradlew test -Pdb=postgresql "-DdbHost=192.168.99.100"

The following table illustrates a list of commands for various databases that can be tested locally.

|=== |Database |Start database |Run tests

H2
./gradlew test -Pdb=h2
HSQLDB
./gradlew test -Pdb=hsqldb
Apache Derby
./gradlew test -Pdb=derby

|MySQL |./db.sh mysql |./gradlew test -Pdb=mysql

|MariaDB |./db.sh mariadb |./gradlew test -Pdb=mariadb

|PostgreSQL |./db.sh postgresql |./gradlew test -Pdb=postgresql

|PostgreSQL with PostGIS (required for hibernate-spatial) |./db.sh postgis |./gradlew test -Pdb=postgis

|EnterpriseDB |./db.sh edb |./gradlew test -Pdb=edb

|Oracle |./db.sh oracle |./gradlew test -Pdb=oracle

|DB2 |./db.sh db2 |./gradlew test -Pdb=db2

|SQL Server |./db.sh mssql |./gradlew test -Pdb=mssql

|Sybase ASE (jTDS) |./db.sh sybase |./gradlew test -Pdb=sybase

|Sybase ASE (jConnect) |./db.sh sybase |./gradlew test -Pdb=sybase_jconn

|SAP HANA |./db.sh hana |./gradlew test -Pdb=hana

|CockroachDB |./db.sh cockroachdb |./gradlew test -Pdb=cockroachdb

|TiDB |./db.sh tidb |./gradlew test -Pdb=tidb

|Informix |./db.sh informix |./gradlew test -Pdb=informix

|Spanner PostgreSQL |./db.sh spanner_pg |./gradlew test -Pdb=spannerpgsql

|CUBRID |./db.sh cubrid |./gradlew test -Pdb=cubrid |===

Stopping a test database

To stop a container, use the stop command. For example:

[source]

podman stop mariadb

Substitute docker for podman if appropriate.

== Continuous Integration

See link:MAINTAINERS.md#ci[MAINTAINERS.md] for information about CI.

Frequently asked questions

Is hibernate-orm free to use?

hibernate-orm is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does hibernate-orm do?

Idiomatic persistence for Java and relational databases

What is hibernate-orm written in?

hibernate-orm is primarily written in Java. Its source is publicly available at https://github.com/hibernate/hibernate-orm, and it has 6,471 GitHub stars.