Upgrade JPA 2.x to Jakarta Persistence 3.0 – Step‑by‑Step Guide

Although Similar, Changes Exist

If you examine JPA 3.0 you will notice that it introduces no new functionality; the specification merely renames packages from javax.persistence to jakarta.persistence, updates a few configuration‑property prefixes, and changes the XML schema namespaces. These changes complete the transition from Java EE to Jakarta EE and require code and configuration migration.

Frameworks Implementing JPA 3.0

Both major JPA implementations already support version 3.0. For EclipseLink you need at least version 3.0.1:

<dependency>
  <groupId>org.eclipse.persistence</groupId>
  <artifactId>org.eclipse.persistence.jpa</artifactId>
  <version>3.0.1</version>
</dependency>

Hibernate added JPA 3.0 support starting with version 5.5.2. All Jakarta‑compatible artifacts carry the “‑jakarta” suffix:

<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-core-jakarta</artifactId>
  <version>5.5.2</version>
</dependency>

Migrating an Existing Application

After updating the Maven dependencies, you must adjust import statements, XML configuration files, and property names. IDE‑wide search‑and‑replace or simple command‑line scripts can handle most of the work.

Changing JPA‑Related Imports

The only functional change is the package rename. Replace every occurrence of import javax.persistence with import jakarta.persistence. After the replacement, an entity class looks like this:

import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Version;

@Entity
public class ChessGame {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    private Long id;
    private LocalDate date;
    private int round;
    @Version
    private int version;
    @ManyToOne
    private ChessTournament chessTournament;
    @ManyToOne(fetch = FetchType.LAZY)
    private ChessPlayer playerWhite;
    @ManyToOne(fetch = FetchType.LAZY)
    private ChessPlayer playerBlack;
    ...
}

Updating XML Namespaces

If you use persistence.xml or orm.xml, replace the old namespaces with the Jakarta ones.

In persistence.xml change the root namespace URL to https://jakarta.ee/xml/ns/persistence:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            version="3.0"
            xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd">
    <persistence-unit name="my-persistence-unit">
        ...
    </persistence-unit>
</persistence>

In orm.xml replace the schema URL with https://jakarta.ee/xml/ns/persistence/orm:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<entity-mappings version="3.0"
                 xmlns="https://jakarta.ee/xml/ns/persistence/orm"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <entity class="com.thorben.janssen.model.ChessPlayer" name="ChessPlayer">
        ...
    </entity>
</entity-mappings>

Migrating Configuration Parameters

Configuration properties that previously used the javax.persistence prefix must be renamed to jakarta.persistence. For example, replace javax.persistence.jdbc.driver with jakarta.persistence.jdbc.driver. A typical persistence.xml after migration looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            version="3.0"
            xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd">
    <persistence-unit name="my-persistence-unit">
        <description>Hibernate example configuration - thorben-janssen.com</description>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="hibernate.jdbc.time_zone" value="UTC"/>
            <property name="jakarta.persistence.jdbc.driver" value="org.postgresql.Driver"/>
            <property name="jakarta.persistence.jdbc.url" value="jdbc:postgresql://localhost:5432/test"/>
            <property name="jakarta.persistence.jdbc.user" value="postgres"/>
            <property name="jakarta.persistence.jdbc.password" value="postgres"/>
            <property name="jakarta.persistence.schema-generation.database.action" value="drop-and-create"/>
            <property name="jakarta.persistence.sql-load-script-source" value="data.sql"/>
        </properties>
    </persistence-unit>
</persistence>

After completing these steps—updating dependencies, imports, XML namespaces, and property names—your application will compile and run against JPA 3.0 without functional changes.