Hibernate is a Java persistence framework that maps Java classes to database tables and writes the SQL for us. It implements the Jakarta Persistence (JPA) standard, so our code uses the standard EntityManager API, and Hibernate adds its own features on top.
We use Hibernate to store and load Java objects in a relational database without writing JDBC code for every table. For example, a notes app saves a note from a web form with one persist() call and lists the notes of a user with one query. These Hibernate tutorials use Hibernate 7.4, Jakarta Persistence 3.2 and Java 25, and each one links a runnable Maven project.
The following example adds the two Maven dependencies that every tutorial uses, starts Hibernate and saves one entity.
<dependency>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-core</artifactId>
<version>7.4.11.Final</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.5.252</version>
</dependency>SessionFactory sessionFactory = new HibernatePersistenceConfiguration("notes")
.managedClass(Note.class)
.jdbcUrl("jdbc:h2:mem:notes")
.jdbcCredentials("sa", "")
.schemaToolingAction(Action.CREATE_DROP)
.showSql(true, false, false)
.createEntityManagerFactory();
sessionFactory.runInTransaction(em -> em.persist(groceries));
// insert into Note (created_on,text,title,id) values (?,?,?,default)Notice that we write no SQL ourselves, and Hibernate prints the INSERT it sends.
Next, we list the tutorials by topic, from the first setup to the common errors, in the order a new project needs them.
1. How to Learn Hibernate
We grouped the tutorials in the order a new project needs them. The first four groups cover the basics, and we can read the rest when a project needs them.
2. Getting Started
These articles set up Hibernate and the test database that the other tutorials build on.
- Hibernate Hello World Example builds the first application with the Maven setup and an entity, and shows the SQL for save, read, update and delete.
- Bootstrapping SessionFactory in Hibernate shows five ways to build a SessionFactory, from Java code to hibernate.cfg.xml.
- Bootstrapping EntityManager in Hibernate starts JPA with persistence.xml or HibernatePersistenceConfiguration and uses the JPA 3.2 runInTransaction() helpers.
- In-memory Database for JUnit Tests sets up H2 for fast, isolated tests.
- Mocking a JNDI DataSource runs code that looks up a JNDI DataSource inside JUnit.
- Connection Pooling with c3p0 configures the pool in plain Hibernate and in Spring Boot 4.
- Configure Hibernate with Spring Boot sets the data source and the JPA properties in a Spring Boot application.
3. Entities and Mapping Annotations
An entity is a Java class mapped to a table. These tutorials cover the annotations on its fields and the column types they produce.
- JPA Persistence Annotations explains @Entity, @Table, @Id, @Column, @Enumerated, @Embedded, @Version and more, each with its DDL.
- Annotations vs XML Mappings compares annotations, orm.xml and the deprecated hbm.xml.
- Mapping Date, Time and Timestamp stores LocalDate, LocalDateTime, Instant and time zones.
- Handling BLOB and CLOB uses @Lob for files and long text.
- Natural Ids with @NaturalId maps business keys and uses the Hibernate 7.3 lookup API.
- @Immutable Entities makes entities and collections read-only.
- Soft Delete with @SoftDelete marks rows as deleted instead of removing them.
- Entity Equality Between Sessions writes equals() and hashCode() that work for entities.
4. Entity States and the Persistence Context
Hibernate tracks each loaded entity in the persistence context, and the state of an entity decides what SQL a call sends.
- Entity Lifecycle States explains the transient, managed, detached and removed states, with the method behind each move.
- Inserting Entities inserts rows with persist(), merge() and the HQL insert statement.
- Saving Child Entities saves a parent and its children with one call.
- save(), update() and saveOrUpdate() shows what the removed methods did and how persist() and merge() replace them.
- Merging and Refreshing Entities copies a detached entity back, or reloads it from the database.
- Deleting Entities covers remove(), bulk deletes and foreign key errors.
- find() vs getReference() shows when Hibernate runs a SELECT and when it returns a proxy.
- get() vs load() compares the old Session methods with their Hibernate 7 replacements.
- Initializing a Proxy uses Hibernate.initialize() for proxies and lazy collections.
- Lifecycle Events and Callbacks runs code in @PrePersist, @PreUpdate and entity listeners.
- Hibernate Interceptors builds an audit trail with Interceptor and StatementInspector.
5. Associations
Associations connect entities through foreign keys. We start with the overview, then read the article for the relationship we need.
- Association Mappings Overview helps pick the annotation, the owning side and the foreign key location.
- One-to-One Mapping compares the foreign key, shared primary key and join table layouts.
- One-to-Many Mapping maps bidirectional and unidirectional @OneToMany associations.
- Many-to-Many Mapping covers join tables, Set vs List and a join entity.
- Cascade Types shows what PERSIST, MERGE, REMOVE and ALL pass to child entities.
- Orphan Removal deletes children removed from a collection.
- Lazy Loading compares LAZY with EAGER and fixes LazyInitializationException.
6. Querying Data
Hibernate queries come as HQL strings or as type-safe Criteria API objects, and we can always fall back to plain SQL.
- HQL Tutorial covers select, joins, join fetch, group by, subqueries and update statements.
- Criteria Queries builds dynamic filters with CriteriaBuilder and the static metamodel.
- Named Queries declares @NamedQuery queries that Hibernate checks at startup.
- Native SELECT Queries covers createNativeQuery(), scalar results and result set mappings.
- Native UPDATE Queries runs executeUpdate() and handles stale entities.
- Native DELETE Queries runs plain SQL deletes and explains foreign key errors.
- Sorting sorts with order by in HQL and Criteria, and with @OrderBy on collections.
- Pagination pages results with offset and keyset paging and a count query.
- Aggregate Functions computes count, min, max, sum and avg.
- Stored Procedures calls procedures with StoredProcedureQuery and IN, OUT and result set parameters.
- @NamedStoredProcedureQuery declares a procedure call once on the entity.
7. Caching and Performance
These tutorials reduce the number of SQL statements and round trips an application sends.
- First Level Cache explains the persistence context as a per-session cache.
- Second Level Cache adds a cache shared across sessions, with the statistics that show the hits.
- Ehcache 3 Setup lists the dependencies and properties for Hibernate 6 and 7.
- Ehcache Configuration configures ehcache.xml regions, expiry and sizing.
- Batch Processing uses hibernate.jdbc.batch_size, flush() and clear(), and StatelessSession.
8. Validation and Full-Text Search
Hibernate Validator and Hibernate Search are separate projects that plug into Hibernate ORM.
- Hibernate Validator covers built-in and custom constraints, groups and validation on persist.
- Hibernate Validator with CDI injects Validator and adds method validation with Weld SE.
- Hibernate Search Guide adds full-text search with Lucene and the Search DSL.
- Hibernate Search with Spring Boot indexes on startup and adds a REST search endpoint.
9. Common Hibernate Errors
Each error article reproduces the message on a real project and shows the cause together with the fix.
| Error message | Usual cause |
|---|---|
| Unable to locate persister | The class is not registered as an entity |
| No row with the given identifier exists | A proxy or foreign key points to a missing row |
| Errors in named queries | A @NamedQuery uses a table name or a wrong attribute |
| GenericJDBCException: could not prepare statement | The database rejects the SQL, for example a missing table or a reserved word |
| Cannot mix named and positional parameters | One query or procedure call uses both parameter styles |
| Invalid character value for cast | Text sent to a number column in HSQLDB |
| No validator could be found for constraint | A constraint on a type it cannot check |
| Pure native scalar queries are not yet supported | A native named query without a result mapping on Hibernate 4.1 or older |
| Bean property configurationClass is not writable | Hibernate 3 Spring XML used with a newer Spring |
| NoClassDefFoundError: CacheProvider | A Hibernate 3 cache jar with Hibernate 4 or later |
| NoClassDefFoundError: SessionFactoryImplementor | A library built for Hibernate 3 with Hibernate 4 or later |
10. Hibernate Tutorials FAQs
10.1. What changed in Hibernate 7 for code from older tutorials?
Hibernate 7 removed several APIs that Hibernate 5 and 6 tutorials use, and these articles use the replacements instead.
| Old API | Hibernate 7 replacement |
|---|---|
| *javax.persistence.** | *jakarta.persistence.** |
| session.save(), update(), saveOrUpdate() | persist() and merge() |
| session.load() | getReference() |
| session.createCriteria() | CriteriaBuilder |
| EmptyInterceptor | The Interceptor interface with default methods |
| @Where | @SQLRestriction or @SoftDelete |
| hibernate.cache.provider_class | hibernate.cache.region.factory_class with JCache |
10.2. Should we learn Hibernate or JPA?
We learn both. JPA (now Jakarta Persistence) is the standard API, and Hibernate implements it. These tutorials use the standard EntityManager API wherever it exists and show the Hibernate-specific features, such as @SoftDelete and @NaturalId, where the standard has no equivalent.
10.3. Do these tutorials need Spring Boot?
No. Most examples start Hibernate with HibernatePersistenceConfiguration and an H2 database, so they run with mvn test and nothing else. The Spring Boot articles say so in their titles, and the same mappings and queries work unchanged inside a Spring Boot application.
11. Conclusion
We recommend starting with the hello world example and the bootstrapping articles, then learning entities, entity states and associations in that order. Queries, caching, validation and the error articles can wait until a project needs them.
12. References
Happy Learning !!
