Hibernate ORM is a powerful object/relational mapping solution for Java, and makes it easy to develop persistence logic for applications, libraries, and frameworks.
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,
-
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 hibernate.org for more information.
Documentation for Hibernate ORM is available at:
This page explains how to include Hibernate ORM in a Java project and configure a connection to the database.
The build requires at least JDK 25, and produces Java 17 bytecode.
Hibernate uses Gradle as its build tool. See the Gradle Primer section below if you’re new to Gradle.
Contributors should read the Contributing Guide.
The Gradle build tool has excellent documentation.
-
Gradle User Guide is a typical user guide in that it follows a topical approach to describing all of the capabilities of Gradle.
-
Gradle DSL Guide is unique and excellent in quickly getting up to speed on certain aspects of Gradle.
Here we summarize the features you’ll need to get started in this project.
|
Note
|
The project has a Gradle Wrapper. The rest of the section will assume execution via the wrapper. |
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:
-
cdinto 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
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
publishToMavenLocalorpTML-
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 Hibernate against an embedded h2 database is easy. Just run:
./gradlew test
To run against another database:
-
start the database using
podmanordocker, and then -
run the tests with the correct profile for that database.
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.
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 |
- |
|
HSQLDB |
- |
|
Apache Derby |
- |
|
MySQL |
|
|
MariaDB |
|
|
PostgreSQL |
|
|
EnterpriseDB |
|
|
Oracle |
|
|
DB2 |
|
|
SQL Server |
|
|
Sybase ASE (jTDS) |
|
|
Sybase ASE (jConnect) |
|
|
SAP HANA |
|
|
CockroachDB |
|
|
TiDB |
|
|
Informix |
|
|
Spanner PostgreSQL |
|
|
Stopping a test database
To stop a container, use the stop command.
For example:
podman stop mariadbSubstitute docker for podman if appropriate.
See MAINTAINERS.md for information about CI.
