Configure Jakarta Persistence and Hibernate for Maven or Gradle builds

If you want a Java ORM that behaves like an obedient but slightly opinionated intern then welcome to Hibernate with JPA3. This guide walks through dependency selection, persistence unit wiring, entity mapping and runtime settings so your EntityManager does not throw tantrums in production.

Dependencies and build tool setup

Pick a Hibernate core 6.x release and the Jakarta Persistence API 3.x artifact. Add a JDBC driver for your database and consider HikariCP for connection pooling if you like fast apps and less debugging during peak hours. Lock versions in Maven or Gradle so future you does not chase ephemeral bugs.

Example Maven snippet

<dependencies>
  <dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.3.0.Final</version>
  </dependency>
  <dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <version>3.1.0</version>
  </dependency>
  <dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.6.0</version>
  </dependency>
</dependencies>

Example Gradle snippet using Kotlin or Groovy syntax will be similar with implementation entries for the same artifacts.

Provide a persistence unit

You can declare a persistence unit via META-INF/persistence.xml or supply properties programmatically at boot. Both work. persistence.xml remains handy for small apps and tests. When you use it make sure the file lives in src/main/resources/META-INF so the classpath can find it.

Key properties to configure

• jakarta.persistence.jdbc.url = your JDBC connection string for the DB
• jakarta.persistence.jdbc.user = DB username
• jakarta.persistence.jdbc.password = DB password
• jakarta.persistence.schema-generation.database.action = update or create depending on your comfort with data loss
• hibernate.dialect = the correct dialect class for your database

Minimal persistence.xml example

<persistence xmlns="https://jakarta.ee/xml/ns/persistence" version="3.0">
  <persistence-unit name="default" transaction-type="RESOURCE_LOCAL">
    <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
    <properties>
      <property name="jakarta.persistence.jdbc.url" value="jdbc:postgresql://localhost:5432/mydb" />
      <property name="jakarta.persistence.jdbc.user" value="sa" />
      <property name="jakarta.persistence.jdbc.password" value="secret" />
      <property name="jakarta.persistence.schema-generation.database.action" value="update" />
      <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect" />
    </properties>
  </persistence-unit>
</persistence>

Entity classes and mapping best practices

Annotate domain classes with @Entity, mark the primary key with @Id and pick a @GeneratedValue strategy that matches your database. I recommend explicit column mappings for clarity and less accidental SQL oddities later.

• Use @Table and @Column when names differ from defaults
• Prefer eager thinking about fetch strategies instead of trusting defaults
• Validate mappings early with a schema generation pass when convenient

EntityManagerFactory and transactions

In simple apps obtain an EntityManagerFactory via jakarta.persistence.Persistence.createEntityManagerFactory. In Jakarta EE or Spring you will often let the container manage the factory and the transactions. If you go manual then remember to open an EntityManager, begin a transaction, commit or rollback, and always close the EntityManager. That sequence is boring but vital.

EntityManagerFactory emf = Persistence.createEntityManagerFactory("default");
EntityManager em = emf.createEntityManager();
EntityTransaction tx = em.getTransaction();
try {
  tx.begin();
  // persist or query entities
  tx.commit();
} catch (Exception ex) {
  if (tx.isActive()) tx.rollback();
  throw ex;
} finally {
  em.close();
}

Testing and SQL visibility

Write a small integration test that boots the persistence unit, persists an entity, and runs a query. That single test often saves you from weeks of head scratching. Enable SQL logging to inspect the generated SQL and catch mapping mistakes quickly.

• hibernate.show_sql = true
• hibernate.format_sql = true

If you need more structured SQL inspection add a logging appender for org.hibernate.SQL and for bind parameter output set org.hibernate.type.descriptor.sql.BasicBinder to debug level.

Practical tips and common pitfalls

• If your dialect is wrong you will get subtle SQL errors. Pick the dialect that matches your database and major version.
• HikariCP will save your app from connection storms. Use it for production like you would use brakes on a car.
• Avoid letting schema generation run in production unless you enjoy surprises.
• Lock dependency versions and test upgrades in an isolated branch instead of on main when caffeine is low and morale is high.

That covers the essentials for wiring Hibernate with JPA3 in a Java project using Maven or Gradle. You now have a reproducible dependency setup, a persistence unit that is sane, mapping advice that actually helps and a plan for tests and logging. Now go make something that persists data and does not persist regret.