Project setup

To work with Hibernate you need three things: the Hibernate library, a JDBC driver for your database and a configuration that says where the database is. In this lesson we create a Maven project and check that Hibernate connects to the database.

Creating the project

The project is generated by the standard Maven archetype:

mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 \
  -DgroupId=com.example -DartifactId=blog -Dpackage=com.example.blog \
  -DinteractiveMode=false
cd blog

The blog folder appears with pom.xml and the src/main/java/com/example/blog package. The generated App.java and the test can be deleted.

pom.xml

Replace the contents of pom.xml with this:

<!-- pom.xml -->
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>com.example</groupId>
  <artifactId>blog</artifactId>
  <version>1.0-SNAPSHOT</version>
 
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>25</maven.compiler.release>
    <exec.mainClass>com.example.blog.Main</exec.mainClass>
  </properties>
 
  <dependencies>
    <dependency>
      <groupId>org.hibernate.orm</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>7.4.12.Final</version>
    </dependency>
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
      <version>2.5.252</version>
    </dependency>
  </dependencies>
 
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.6.4</version>
      </plugin>
    </plugins>
  </build>
</project>

hibernate-core brings in Hibernate together with the Jakarta Persistence API. h2 is a database written in Java that can live in memory — no server to install. The exec-maven-plugin runs a class with the mvn exec:java command; which one is set by the exec.mainClass property.

persistence.xml

The connection is described in a persistence unit — a named set of settings. Create the file src/main/resources/META-INF/persistence.xml:

<!-- src/main/resources/META-INF/persistence.xml -->
<persistence xmlns="https://jakarta.ee/xml/ns/persistence" version="3.2">
  <persistence-unit name="blog">
    <properties>
      <property name="jakarta.persistence.jdbc.url" value="jdbc:h2:mem:blog"/>
      <property name="jakarta.persistence.jdbc.user" value="sa"/>
      <property name="jakarta.persistence.jdbc.password" value=""/>
      <property name="jakarta.persistence.schema-generation.database.action" value="drop-and-create"/>
      <property name="hibernate.show_sql" value="true"/>
    </properties>
  </persistence-unit>
</persistence>

Property	Meaning
`jakarta.persistence.jdbc.url`	Database address. `jdbc:h2:mem:blog` is an in-memory database that disappears when the program ends
`jakarta.persistence.jdbc.user`, `password`	Login and password
`...schema-generation.database.action`	`drop-and-create`: build the tables from the entity classes on every start
`hibernate.show_sql`	Print every SQL statement to the console

The first run

// src/main/java/com/example/blog/Main.java
package com.example.blog;
 
import jakarta.persistence.EntityManagerFactory;
import jakarta.persistence.Persistence;
 
public class Main {
    public static void main(String[] args) {
        try (EntityManagerFactory emf = Persistence.createEntityManagerFactory("blog")) {
            Object version = emf.callInTransaction(em ->
                    em.createNativeQuery("select h2version()").getSingleResult());
            IO.println("Connected to H2 " + version);
        }
    }
}

Persistence.createEntityManagerFactory("blog") reads the unit with that name and starts Hibernate. Run it:

mvn compile exec:java

INFO: HHH000001: Hibernate ORM core version 7.4.12.Final
WARN: HHH10001002: Using built-in connection pool (not intended for production use)
... (the rest of the log is shortened)
Hibernate: select h2version()
Connected to H2 2.5.252

The warning about the built-in pool is fine for learning; real applications use a connection pool such as HikariCP.

Configuration in code

Since Jakarta Persistence 3.2, the same settings can be written in Java without an XML file:

// src/main/java/com/example/blog/Main.java
SessionFactory factory = new HibernatePersistenceConfiguration("blog")
        .jdbcUrl("jdbc:h2:mem:blog")
        .jdbcCredentials("sa", "")
        .schemaToolingAction(Action.CREATE_DROP)
        .showSql(true, false, false)
        .createEntityManagerFactory();

Classes are imported from org.hibernate.jpa and org.hibernate.tool.schema. The result is the same: Connected to H2 2.5.252. The course uses persistence.xml, because that is how most existing projects are configured.

Common mistake

The name in the code must match the name attribute in persistence.xml exactly, and the file must lie in src/main/resources/META-INF. Otherwise Hibernate does not find the unit:

Exception in thread "main" jakarta.persistence.PersistenceException: No Persistence provider for EntityManager named blogs

Thanks for reading!