Migrate from Panache to Quarkus Data Hibernate
experimentalThis guide helps you migrate an existing Hibernate ORM with Panache or Hibernate Reactive with Panache application to Quarkus Data Hibernate. Both migration paths use managed, stateful sessions to preserve persistence-context and dirty-checking behavior. Follow Hibernate ORM with Panache for Hibernate ORM or Hibernate Reactive with Panache for Hibernate Reactive.
For complete API descriptions, see Hibernate ORM with Panache, Hibernate Reactive with Panache, and the Quarkus Data Hibernate reference guide.
|
Quarkus Data Hibernate is currently experimental. Its APIs may change. |
Hibernate ORM with Panache
Prepare the application
Quarkus Data Hibernate generates repository implementations and metamodel accessors at build time. Enable its annotation processor and add the required extension by following the Quarkus Data Hibernate getting started tutorial.
Remove the quarkus-hibernate-orm-panache extension when converting the application.
Classic Panache extensions and Quarkus Data Hibernate cannot be used together in the same application.
Your existing entity mappings, datasource configuration, Hibernate ORM configuration, and transaction boundaries remain applicable.
Understand the repository changes
With Panache, you define custom query methods either as static methods on the entity class, following the active-record pattern, or as instance methods in a separate repository class.
If your application uses active record, move custom static query methods to a repository interface as default methods or generated query methods.
Nesting the repository inside the entity lets you access it through the entity’s generated Jakarta Persistence metamodel:
Person.list(…) becomes Person_.repo().list(…).
For applications using Panache repository classes, replace each class with a repository interface and convert custom method implementations to default methods or generated query methods.
Both nested and top-level repository interfaces support injection.
The examples below use ManagedEntity and ManagedRepository to preserve Panache’s stateful persistence-context and dirty-checking behavior.
For details about session models, see Session and access models.
Migrate an active-record entity
PanacheEntity combines an inherited generated Long identifier, instance persistence operations, and common
operations such as Person.list(…), Person.listAll(), and Person.count() , called directly on the entity class.
ManagedEntity retains the identifier and instance operations, but does not provide static query methods.
Instead, these operations are provided by ManagedRepository and can be accessed through Person_.repo() on the generated
metamodel.
For example, migrate this Panache entity:
import io.quarkus.hibernate.orm.panache.PanacheEntity;
import jakarta.persistence.Entity;
import java.util.Date;
@Entity
public class Person extends PanacheEntity {
public String name;
public Date birth;
public Status status;
}
to a managed entity with a nested repository:
import io.quarkus.data.hibernate.ManagedEntity;
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.persistence.Entity;
import java.util.Date;
@Entity
public class Person extends ManagedEntity {
public String name;
public Date birth;
public Status status;
public interface Repo extends ManagedRepository<Person> {
}
}
Then migrate the query call site from a static entity method:
List<Person> alive = Person.list("status", Status.ALIVE);
to a call on the nested repository in the generated Jakarta Persistence metamodel:
List<Person> alive = Person_.repo().list("status", Status.ALIVE);
or to call on an injected repository:
import jakarta.inject.Inject;
@Inject
Person.Repo people;
List<Person> alive = people.list("status", Status.ALIVE);
Move custom static methods
Move custom static query helpers from the entity into a repository default method, a generated @Find, @Query, or @Delete method, or an application service.
For example, migrate this Panache entity method:
@Entity
public class Person extends PanacheEntity {
public String name;
public Date birth;
public Status status;
public static List<Person> findAlive() {
return list("status", Status.ALIVE);
}
}
to a default method on the nested repository:
@Entity
public class Person extends ManagedEntity {
public String name;
public Date birth;
public Status status;
public interface Repo extends ManagedRepository<Person> {
default List<Person> findAlive() {
return list("status", Status.ALIVE);
}
}
}
Then migrate the call site:
List<Person> alive = Person.findAlive();
Person.Repo peopleList<Person> alive = people.findAlive();
Alternatively, call Person_.repo().findAlive() through the generated metamodel.
For examples of generated query methods, see Adopt generated repository methods where useful.
Migrate a Panache repository
Replace a handwritten CDI repository implementation with an interface. Quarkus Data generates its CDI implementation at build time.
import io.quarkus.hibernate.orm.panache.PanacheRepository;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;
@ApplicationScoped
public class PersonRepository implements PanacheRepository<Person> {
public List<Person> findAlive() {
return list("status", Status.ALIVE);
}
}
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.data.repository.Repository;
import java.util.List;
@Repository
public interface PersonRepository extends ManagedRepository<Person> {
default List<Person> findAlive() {
return list("status", Status.ALIVE);
}
}
The entity uses ManagedEntity, as in the previous section.
When using this top-level repository, there’s no need for a nested Repo interface in the entity itself.
Replace the @ApplicationScoped class with the @Repository interface and use default for custom method
implementations.
You can also declare annotated methods whose implementations are generated, and take this a step further:
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.data.repository.Repository;
import jakarta.data.repository.Find;
import java.util.List;
@Repository
public interface PersonRepository extends ManagedRepository<Person> {
@Find
List<Person> findByStatus(Status status);
default List<Person> findAlive() {
return findByStatus(Status.ALIVE);
}
}
The top-level interface above uses jakarta.data.repository.Repository; a nested Person.Repo does not need this annotation.
Injection and query call sites remain the same before and after this conversion:
import jakarta.inject.Inject;
@Inject
PersonRepository people;
List<Person> alive = people.findAlive();
Migrate entity identifiers
PanacheEntity maps directly to ManagedEntity: both provide a generated Long identifier.
For a PanacheEntityBase entity with an application-defined identifier, retain its @Id mapping, implement ManagedEntity.CustomId, and use ManagedRepository.CustomId<Entity, Id>.
import io.quarkus.hibernate.orm.panache.PanacheEntityBase;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import java.util.UUID;
@Entity
public class Person extends PanacheEntityBase {
@Id
public UUID id;
}
import io.quarkus.data.hibernate.ManagedEntity;
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import java.util.UUID;
@Entity
public class Person implements ManagedEntity.CustomId {
@Id
public UUID id;
public interface Repo extends ManagedRepository.CustomId<Person, UUID> {
}
}
If you use a top-level Panache repository with a custom identifier, migrate it to a top-level interface instead of declaring the nested Repo above:
import io.quarkus.hibernate.orm.panache.PanacheRepositoryBase;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.UUID;
@ApplicationScoped
public class PersonRepository implements PanacheRepositoryBase<Person, UUID> {
}
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.data.repository.Repository;
import java.util.UUID;
@Repository
public interface PersonRepository extends ManagedRepository.CustomId<Person, UUID> {
}
If you want an inherited generated identifier of another type, Quarkus Data also provides WithId.AutoString, WithId.AutoUUID, and WithId.AutoUUIDv7.
See entity identifiers for details.
Migrate common operations
Most Panache repository and entity operations are available from ManagedRepository and ManagedEntity with the same names.
The following table shows the usual replacements.
| Panache | Quarkus Data Hibernate |
|---|---|
|
|
|
The corresponding |
|
The same instance operations after the entity extends |
|
The same |
|
The corresponding |
|
|
|
The same operations, except that sorting is applied to the query object. See Sorting. |
|
|
The blocking persist(), persistAndFlush(), delete(entity), entity.delete(), and flush() operations return Void instead of void.
The isPersistent() and deleteById() operations return Boolean instead of boolean.
Existing calls that ignore a Void result or unbox a Boolean or Long result can retain their usual form.
For bulk updates, change variables and custom method return types that receive the count from int to long or Long:
int changed = Person.update("status = ?1 where name = ?2", Status.ALIVE, "Ada");
long changed = people.update("status = ?1 where name = ?2", Status.ALIVE, "Ada");
If an existing API must still return int, convert explicitly with Math.toIntExact(people.update(…)).
ManagedRepository supports the indexed Object… and named Map<String, Object> parameter forms used by Panache.
Replace deprecated Panache Parameters instances with a Map, for example Map.of("status", Status.ALIVE).
findByIds(List<?>) has no inherited ManagedRepository counterpart.
Declare a repository method such as @Query("where id in :ids") List<Person> findByIds(List<UUID> ids), or use a dynamic query such as repository.list("id in ?1", ids) with the actual identifier attribute name and type.
Migrate query results
find() and findAll() now return BlockingDataQuery<Entity> instead of PanacheQuery<Entity>.
Most result operations remain direct equivalents.
Panache PanacheQuery |
Quarkus Data BlockingDataQuery |
|---|---|
|
The same method. |
|
The same method; |
|
The same method. Existing Panache projection annotations remain applicable. |
|
The same method; use the |
Sorting
Panache passes io.quarkus.panache.common.Sort directly to find, list, and stream methods.
With Quarkus Data, sort the BlockingDataQuery returned by find() or findAll() using Jakarta Data Sort or Order.
// Before
List<Person> ordered = Person.listAll(Sort.by("name"));
// After
List<Person> ordered = people.findAll().sort(jakarta.data.Sort.asc("name")).list();
// Before
List<Person> alive = Person.list("status", Sort.by("name"), Status.ALIVE);
// After
List<Person> alive = people.find("status", Status.ALIVE)
.sort(jakarta.data.Sort.asc("name"))
.list();
For multiple sort criteria, use jakarta.data.Order:
import jakarta.data.Order;
import jakarta.data.Sort;
List<Person> ordered = people.findAll()
.sort(Order.by(Sort.asc("name"), Sort.desc("birth")))
.list();
Jakarta Data Sort supports ascending, descending, and ignore-case variants, but it does not expose Panache Sort features such as null precedence or disableEscaping().
Use an explicit HQL order by expression when that Hibernate-specific behavior is required.
Pagination and ranges
Paging and ranges are available from nested query operations:
| Panache | Quarkus Data Hibernate |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
pages().page(pageIndex, pageSize) is the closest mechanical replacement and retains Panache’s zero-based page index.
The page request type is jakarta.data.page.PageRequest rather than io.quarkus.panache.common.Page.
Its page() value is one-based: replace reads of query.page().index with query.pages().request().page() - 1.
As with Panache, do not combine fixed ranges and paging on the same query.
Adopt generated repository methods where useful
You can keep existing query strings when moving calls from a Panache entity or repository to ManagedRepository.
The repository’s find, list, count, update, and delete methods interpret these strings at runtime, just as Panache does.
For example, with an injected PersonRepository people:
List<Person> alive = people.list("status", Status.ALIVE); (1)
List<Person> aliveByHql = people.list("from Person where status = ?1", Status.ALIVE); (2)
List<Person> aliveByNamedParameter = people.list("status = :status", Map.of("status", Status.ALIVE)); (3)
List<Person> aliveByNamedQuery = people.list("#Person.findByStatus", Status.ALIVE); (4)
| 1 | Panache Query Language shorthand: "status" expands to a query that matches the status field to the supplied value. |
| 2 | A full Hibernate Query Language (HQL) query with an indexed parameter: ?1 receives the first supplied value. |
| 3 | A named parameter: the status entry in the map supplies the value for :status. |
| 4 | An existing named query declared on the entity with @NamedQuery, referenced by prefixing its name with #.
This example assumes Person.findByStatus is already declared with a ?1 parameter. |
Query options also carry over to the object returned by find().
Use withLock() to request a database lock within a transaction, withHint() to pass query hints to Hibernate, and filter() to enable an existing Hibernate filter while fetching results.
Use project(Dto.class) to return DTO instances containing selected fields instead of complete entities.
These methods have the same roles as on PanacheQuery; see the comparison in Migrate query results.
When a custom helper always uses the same query structure, you can instead declare an annotated repository method and let the annotation processor generate its implementation.
For example, replace this custom method in PersonRepository:
default List<Person> findOrderedByStatus(Status status) {
return list("status = ?1 order by name", status);
}
with an abstract @Query method.
The following repository also illustrates generated finder and delete methods:
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.data.repository.Delete;
import jakarta.data.repository.Find;
import jakarta.data.repository.Query;
import jakarta.data.repository.Repository;
import java.util.List;
@Repository
public interface PersonRepository extends ManagedRepository<Person> {
@Find
List<Person> findByStatus(Status status); (1)
@Delete
long deleteByStatus(Status status); (2)
@Query("where status = :status order by name")
List<Person> findOrderedByStatus(Status status); (3)
}
| 1 | @Find builds a query from the method parameters: the status parameter matches the entity’s status field. |
| 2 | @Delete matches parameters to fields in the same way, deletes matching entities, and returns the number deleted.
Call this method within a transaction, as with the corresponding Panache delete operation. |
| 3 | @Query specifies the query explicitly and binds :status to the method parameter.
This replaces the default method above while retaining its filtering and ordering. |
The annotation processor checks the declared queries and parameter mappings when you build the application, so errors such as an unknown entity field can be reported before the method is called. The methods have no handwritten bodies; Quarkus Data generates them. The call to the custom helper remains the same:
List<Person> alive = people.findOrderedByStatus(Status.ALIVE);
Use @NativeQuery for SQL when necessary. For runtime-built queries, continue to use repository find, list, count, update, and delete methods.
For type-safe dynamic filtering and ordering, consider Jakarta Data restrictions and the generated metamodel; see
generated metamodels and type-safe queries.
Replace global Panache utilities deliberately
Panache global static helpers do not have direct Quarkus Data equivalents.
This includes global getEntityManager(), getSession(), getTransactionManager(), executeUpdate(), setRollbackOnly(), and flush() methods.
For work associated with an entity repository, use repository.getSession() and repository.flush().
For arbitrary HQL, Criteria, or native SQL, inject a Hibernate Session or Jakarta Persistence EntityManager.
An injection with only @Inject selects the default persistence unit.
To select a configured named persistence unit, add Quarkus’s @PersistenceUnit annotation to the injected field.
For example, to obtain the session for a persistence unit named users:
import io.quarkus.hibernate.orm.PersistenceUnit;
import jakarta.inject.Inject;
import org.hibernate.Session;
@Inject
@PersistenceUnit("users")
Session session;
Here, @PersistenceUnit("users") is a CDI qualifier: it tells Quarkus which persistence unit’s session to inject.
The same annotation can select the persistence unit for an injected EntityManager.
See Multiple persistence units for configuration and injection details.
For transaction-manager or rollback-only control, use the Jakarta Transactions facilities appropriate to the application.
Update tests
PanacheMock mocks static active-record methods and therefore does not apply to Quarkus Data repositories.
After moving static entity queries to an injected repository, mock or replace that CDI bean using the normal Quarkus test mechanisms, such as @InjectMock from quarkus-junit-mockito.
Existing tests should continue to cover the same persistence behavior. Add focused tests for every moved static helper and for intentional query changes, particularly sorting, paging, ranges, and custom identifier handling.
Migration checklist
-
Enable the Quarkus Data Hibernate annotation processor and extension.
-
Remove the classic
quarkus-hibernate-orm-panacheextension when converting the application. -
Migrate blocking Panache entities to
ManagedEntity, or implementManagedEntity.CustomIdfor custom identifiers. -
Replace
PanacheRepositorywithManagedRepository<Entity>andPanacheRepositoryBase<Entity, Id>withManagedRepository.CustomId<Entity, Id>. -
Convert repository classes to interfaces, use
defaultfor custom method implementations, and annotate top-level repository interfaces with@Repository. -
Move active-record static query methods and custom static helpers to repositories or services.
-
Replace Panache
Sort,Page, andParametersusages with Jakarta DataSort/Order,PageRequest, andMapas appropriate. -
Replace
findByIdswith an annotated finder or a query. -
Replace uses of global Panache utilities with repository,
Session,EntityManager, or transaction APIs. -
Update static Panache mocks to CDI repository mocks, and run the relevant tests.
Hibernate Reactive with Panache
This section migrates the Java API from io.quarkus.hibernate.reactive.panache to Quarkus Data Hibernate’s managed reactive API.
The examples retain Mutiny Uni return types and stateful Hibernate Reactive sessions.
They use the same Person and Status.ALIVE model as the section that deals with Hibernate ORM but all entity and repository operations in this part are reactive.
Prepare the application
Add quarkus-data-hibernate and enable its quarkus-data-processor annotation processor by following the
getting started tutorial.
Keep quarkus-hibernate-reactive and your reactive SQL driver, such as quarkus-reactive-pg-client for PostgreSQL.
Also add quarkus-hibernate-reactive-panache-common, which supplies the reactive support used by the generated repositories.
See the tutorial’s reactive setup for the dependency configuration.
Remove quarkus-hibernate-reactive-panache when converting the application.
Classic Panache extensions and Quarkus Data Hibernate cannot coexist in the same application.
Keep quarkus-hibernate-reactive-panache-common: this support artifact is distinct from the classic Panache extension you are replacing.
Your entity mappings, reactive datasource configuration, and Hibernate configuration remain applicable. Review session and transaction boundaries as described in Preserve session and transaction boundaries.
Understand the repository changes
As with ORM, replace static entity queries or handwritten CDI repository classes with repository interfaces,
whose implementation is generated at build time by Quarkus Data.
For reactive access, use ManagedEntity.Reactive and ManagedRepository.Reactive<Entity>.
These use a stateful Mutiny.Session, preserving managed-entity dirty checking.
The blocking ManagedRepository<Entity> is a different API.
For alternative session models, see Session and access models.
Queries return Uni results, but the query builder itself is synchronous.
For example, people.find("status", Status.ALIVE) returns a ReactiveDataQuery<Person>, and its list() method returns a Uni<List<Person>>.
Continue composing and returning the Uni so the caller subscribes to the database operation.
Migrate an active-record entity
Migrate this Hibernate Reactive Panache entity:
import io.quarkus.hibernate.reactive.panache.PanacheEntity;
import jakarta.persistence.Entity;
@Entity
public class Person extends PanacheEntity {
public String name;
public Status status;
}
to a managed reactive entity with a nested repository:
import io.quarkus.data.hibernate.ManagedEntity;
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.persistence.Entity;
@Entity
public class Person extends ManagedEntity.Reactive {
public String name;
public Status status;
public interface Repo extends ManagedRepository.Reactive<Person> {
}
}
Then migrate the static query call:
Uni<List<Person>> alive = Person.list("status", Status.ALIVE);
import jakarta.inject.Inject;
@Inject
Person.Repo people;
Uni<List<Person>> alive = people.list("status", Status.ALIVE);
Alternatively, access the declared nested repository through the generated metamodel:
Uni<List<Person>> alive = Person_.repo().list("status", Status.ALIVE);
The accessor follows the nested interface name: a nested ReactiveRepo would be accessed through Person_.reactiveRepo().
Move custom static methods
Move custom static helpers into repository default methods, generated query methods, or application services. For example, migrate this helper on the Panache entity:
Person extends PanacheEntitypublic static Uni<List<Person>> findAlive() {
return list("status", Status.ALIVE);
}
Person extends ManagedEntity.Reactivepublic interface Repo extends ManagedRepository.Reactive<Person> {
default Uni<List<Person>> findAlive() {
return list("status", Status.ALIVE);
}
}
Update its call site while preserving the result type:
Uni<List<Person>> alive = Person.findAlive();
Person.Repo peopleUni<List<Person>> alive = people.findAlive();
The metamodel alternative is Person_.repo().findAlive().
For helpers with a fixed query structure, see Adopt generated repository methods where useful.
Migrate a Panache repository
Replace a handwritten CDI repository implementation with an interface. Quarkus Data generates its CDI implementation at build time.
import io.quarkus.hibernate.reactive.panache.PanacheRepository;
import io.smallrye.mutiny.Uni;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;
@ApplicationScoped
public class PersonRepository implements PanacheRepository<Person> {
public Uni<List<Person>> findAlive() {
return list("status", Status.ALIVE);
}
}
import io.quarkus.data.hibernate.ManagedRepository;
import io.smallrye.mutiny.Uni;
import jakarta.data.repository.Repository;
import java.util.List;
@Repository
public interface PersonRepository extends ManagedRepository.Reactive<Person> {
default Uni<List<Person>> findAlive() {
return list("status", Status.ALIVE);
}
}
Change the entity superclass to ManagedEntity.Reactive as shown above.
When using this top-level repository, the entity does not need a nested Repo interface.
Replace the @ApplicationScoped class with the @Repository interface and use default for custom method
implementations.
You can also declare annotated methods whose implementations are generated, and take this a step further:
import io.quarkus.data.hibernate.ManagedRepository;
import io.smallrye.mutiny.Uni;
import jakarta.data.repository.Repository;
import jakarta.data.repository.Find;
import java.util.List;
@Repository
public interface PersonRepository extends ManagedRepository.Reactive<Person> {
@Find
Uni<List<Person>> findByStatus(Status status);
default Uni<List<Person>> findAlive() {
return findByStatus(Status.ALIVE);
}
}
The top-level example uses jakarta.data.repository.Repository; a nested repository does not need this annotation.
Injection and query call sites remain the same before and after this conversion:
import jakarta.inject.Inject;
@Inject
PersonRepository people;
Uni<List<Person>> alive = people.findAlive();
Migrate entity identifiers
ManagedEntity.Reactive retains the generated Long identifier provided by reactive PanacheEntity.
For a PanacheEntityBase entity with an application-defined identifier, retain the @Id mapping and implement ManagedEntity.Reactive.CustomId.
import io.quarkus.hibernate.reactive.panache.PanacheEntityBase;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import java.util.UUID;
@Entity
public class Person extends PanacheEntityBase {
@Id
public UUID id;
}
import io.quarkus.data.hibernate.ManagedEntity;
import io.quarkus.data.hibernate.ManagedRepository;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import java.util.UUID;
@Entity
public class Person implements ManagedEntity.Reactive.CustomId {
@Id
public UUID id;
public interface Repo extends ManagedRepository.Reactive.CustomId<Person, UUID> {
}
}
Keep the existing identifier generation strategy, if any.
Implementing CustomId does not generate a value for the manually assigned UUID field above.
For a top-level repository, migrate the custom identifier type as follows instead of declaring the nested Repo:
@ApplicationScoped
public class PersonRepository implements PanacheRepositoryBase<Person, UUID> {
}
@Repository
public interface PersonRepository extends ManagedRepository.Reactive.CustomId<Person, UUID> {
}
Here, PanacheRepositoryBase comes from io.quarkus.hibernate.reactive.panache, and @Repository comes from jakarta.data.repository.
See entity identifiers for alternative inherited identifier strategies.
Migrate common operations
Most reactive operations retain their names, but several return types change:
| Operation | Reactive Panache | Quarkus Data reactive |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use |
|
|
The same return types. |
|
|
|
|
|
The same return type; apply sorting through |
|
|
|
|
|
|
|
|
|
Preserve persistence results
If a method returns the persisted entity, restore it after the persistence operation completes:
import io.quarkus.hibernate.reactive.panache.common.WithTransaction;
@WithTransaction
public Uni<Person> create(Person person) {
return person.persist();
}
import jakarta.transaction.Transactional;
@Transactional
public Uni<Person> create(Person person) {
return person.persist().replaceWith(person);
}
|
Notice how we have also switched to using |
Apply the same change to persistAndFlush() and the repository persistence methods.
For example, people.persistAndFlush(person).replaceWith(person) returns a Uni<Person>.
If the caller needs to know whether persistence succeeded or failed, but does not need the entity as a result, return Uni<Void>.
The returned Uni signals when the persistence operation has finished and propagates any failure:
@Transactional
public Uni<Void> create(Person person) {
return person.persist();
}
A lambda such as .chain(saved → …) no longer receives the entity after persist().
Use the original entity or restore it with replaceWith(entity) before continuing the pipeline.
Compose asynchronous operations with chain() or call(); invoke() is for synchronous side effects.
Compose persistence-state checks and flushes
Replace synchronous persistence-state checks with Uni composition:
@WithTransaction
public Uni<Void> persistIfNeeded(Person person) {
return person.isPersistent() ? Uni.createFrom().voidItem() : person.persist().replaceWithVoid();
}
@Transactional
public Uni<Void> persistIfNeeded(Person person) {
return person.isPersistent().chain(managed ->
managed ? Uni.createFrom().voidItem() : person.persist());
}
This check tells you whether the entity is managed by the current session.
It does not query the database to check for an existing row.
When checking after persistence, invoke isPersistent() within the continuation so it observes the updated state:
Uni<Boolean> managed = people.persist(person).chain(() -> person.isPersistent());
Replace entity-level flush calls with repository flush calls:
Uni<Void> flushed = person.flush();
Uni<Void> flushed = people.flush();
Flushing synchronizes all pending changes in the session, rather than only changes to that person.
For example, compose persistence and an explicit flush as people.persist(person).call(() → people.flush()) within a transaction.
Adapt update counts and query parameters
Bulk query updates now return Uni<Long>:
Uni<Integer> changed = people.update("status = ?1 where name = ?2", Status.ALIVE, "Ada");
Uni<Long> changed = people.update("status = ?1 where name = ?2", Status.ALIVE, "Ada");
If an existing API must still return Uni<Integer>, convert explicitly with .map(Math::toIntExact).
Run bulk updates and deletes within a transaction.
Indexed parameters and named Map parameters remain supported.
Replace deprecated Panache Parameters usages with a map:
Uni<List<Person>> alive = people.list("status = :status", Parameters.with("status", Status.ALIVE));
Uni<List<Person>> alive = people.list("status = :status", Map.of("status", Status.ALIVE));
Neither reactive API has the inherited findByIds, Optional-result, or result-streaming methods described for the blocking API in the ORM section.
For a bulk-ID query, use the actual identifier attribute name, for example people.list("id in ?1", ids), or declare a generated query method as shown in Adopt generated repository methods where useful.
Migrate query results
Replace reactive PanacheQuery<Entity> with io.quarkus.data.hibernate.reactive.ReactiveDataQuery<Entity>.
The builder remains synchronous; fetching results remains asynchronous:
PanacheQuery<Person> query = people.find("status", Status.ALIVE);
Uni<List<Person>> alive = query.list();
ReactiveDataQuery<Person> query = people.find("status", Status.ALIVE);
Uni<List<Person>> alive = query.list();
| Reactive Panache query operation | Quarkus Data reactive |
|---|---|
|
The same method returning |
|
The same methods returning |
|
The same method returning |
|
The same builder operation returning |
|
The same builder operations; use a |
Sorting
Move Panache Sort arguments to the query builder, using Jakarta Data Sort:
Uni<List<Person>> alive = Person.list("status", Sort.by("name"), Status.ALIVE);
Uni<List<Person>> alive = people.find("status", Status.ALIVE)
.sort(jakarta.data.Sort.asc("name"))
.list();
For multiple criteria, use jakarta.data.Order:
import jakarta.data.Order;
import jakarta.data.Sort;
Uni<List<Person>> ordered = people.findAll()
.sort(Order.by(Sort.asc("name"), Sort.desc("id")))
.list();
As in the ORM migration section, use an explicit HQL order by expression for requirements such as Panache’s null-precedence settings or disableEscaping():
Uni<List<Person>> ordered = people.find("order by name nulls last").list();
Pagination and ranges
Move paging and ranges to the nested query APIs, and account for changed result types:
| Reactive Panache | Quarkus Data reactive |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For example, migrate the first page:
Uni<List<Person>> firstPage = people.findAll().page(0, 20).list();
Uni<List<Person>> firstPage = people.findAll().pages().page(0, 20).list();
Both page(index, size) and range(start, end) retain zero-based indices, with an inclusive range end.
For a fixed range:
Uni<List<Person>> selected = people.findAll().range(20, 39).list();
Uni<List<Person>> selected = people.findAll().limits().range(20, 39).list();
The PageRequest representation uses one-based page numbers.
Replace reads of query.page().index with query.pages().request().page() - 1 and reads of query.page().size with query.pages().request().size().
To supply a PageRequest, convert the index explicitly:
import jakarta.data.page.PageRequest;
Uni<List<Person>> selected = query.pages()
.request(PageRequest.ofPage(pageIndex + 1, pageSize, false))
.list();
Continue composing last-page navigation before fetching results:
Uni<List<Person>> lastPage = query.lastPage().chain(last -> last.list());
Uni<List<Person>> lastPage = query.pages().last().chain(last -> last.list());
A previous-page check must now be composed too:
if (query.hasPreviousPage()) {
query.previousPage();
}
return query.list();
return query.pages().hasPrevious().chain(hasPrevious -> {
if (hasPrevious) {
query.pages().previous();
}
return query.list();
});
Page counts also change type:
Uni<Integer> pages = query.pageCount();
Uni<Long> pages = query.pages().count();
Configure a page before using page navigation or inspection methods.
query.count() counts matching rows, whereas query.pages().count() counts pages.
Switching between fixed ranges and paging replaces the previous mode.
Projections, locks, and filters
Existing reactive Panache projection annotations remain usable with project().
For example, retain a DTO and migrate its query call:
import io.quarkus.runtime.annotations.RegisterForReflection;
@RegisterForReflection
public record PersonName(String name) {
}
Uni<List<PersonName>> names = Person.find("status", Status.ALIVE).project(PersonName.class).list();
Uni<List<PersonName>> names = people.find("status", Status.ALIVE).project(PersonName.class).list();
Keep constructor parameter metadata and reflection registration where needed for native executables.
The reactive @ProjectedConstructor, @ProjectedFieldName, and @NestedProjectedClass annotations do not require new ORM imports.
Pessimistic locks still require an active transaction. For example, after replacing static calls with an injected repository:
import jakarta.persistence.LockModeType;
@Transactional
public Uni<Person> rename(Long id, String name) {
return people.findById(id, LockModeType.PESSIMISTIC_WRITE)
.invoke(person -> person.name = name);
}
The managed entity’s changes are flushed when the transaction commits.
To retain an existing Hibernate filter named visibleTo, pass its parameters as a map:
Uni<List<Person>> visible = people.findAll()
.filter("visibleTo", Map.of("userId", userId))
.list();
This example assumes the filter and its userId parameter are already declared in the entity mappings.
|
Both reactive query APIs expose |
Adopt generated repository methods where useful
Dynamic queries remain available, including shorthand, HQL, indexed parameters, named parameters, and existing named queries:
Uni<List<Person>> shorthand = people.list("status", Status.ALIVE);
Uni<List<Person>> hql = people.list("from Person where status = ?1", Status.ALIVE);
Uni<List<Person>> namedParameter = people.list("status = :status", Map.of("status", Status.ALIVE));
Uni<List<Person>> namedQuery = people.list("#Person.findByStatus", Status.ALIVE);
The last example assumes an existing @NamedQuery named Person.findByStatus with a ?1 parameter.
These queries are interpreted at runtime.
For a helper with a fixed query structure, you can replace the method body with a generated method declaration. For example, migrate this default method:
PersonRepositorydefault Uni<List<Person>> findOrderedByStatus(Status status) {
return list("status = ?1 order by name", status);
}
import io.quarkus.data.hibernate.ManagedRepository;
import io.smallrye.mutiny.Uni;
import jakarta.data.repository.Delete;
import jakarta.data.repository.Find;
import jakarta.data.repository.Query;
import jakarta.data.repository.Repository;
import java.util.List;
@Repository
public interface PersonRepository extends ManagedRepository.Reactive<Person> {
@Find
Uni<List<Person>> findByStatus(Status status); (1)
@Delete
Uni<Integer> deleteByStatus(Status status); (2)
@Query("where status = :status order by name")
Uni<List<Person>> findOrderedByStatus(Status status); (3)
}
| 1 | @Find matches the method’s status parameter to the entity’s status field. |
| 2 | @Delete matches parameters in the same way and deletes matching entities within a transaction.
This generated method returns Uni<Integer>; the inherited dynamic people.delete(…) method returns Uni<Long>. |
| 3 | @Query replaces the default method body and binds :status to the parameter.
The annotation processor checks the query and parameter mappings at build time. |
The call site retains its asynchronous result:
Uni<List<Person>> alive = people.findOrderedByStatus(Status.ALIVE);
For bulk identifiers, a custom-ID repository can declare:
@Query("where id in :ids")
Uni<List<Person>> findByIds(List<UUID> ids);
Use the mapped identifier’s actual name and type.
For SQL, use jakarta.persistence.query.NativeQuery, referring to database tables and columns rather than entity fields.
For example, assuming the Person table has a name column:
@NativeQuery("select name from Person where name = :name")
Uni<List<String>> findNames(String name);
For type-safe dynamic filtering and ordering, see generated metamodels and type-safe queries.
Preserve session and transaction boundaries
Moving queries to generated repositories does not automatically create an application transaction boundary.
Keep database work on a Vert.x context, compose asynchronous operations, and return the resulting Uni.
For example, migrate a programmatic Panache transaction wrapper to an intercepted CDI service method:
public Uni<Person> create(Person person) {
return Panache.withTransaction(() -> person.persist());
}
Person.Repo peopleimport jakarta.transaction.Transactional;
@Transactional
public Uni<Person> create(Person person) {
return people.persist(person).replaceWith(person);
}
For a read-only session wrapper, migrate similarly:
public Uni<List<Person>> findAlive() {
return Panache.withSession(() -> Person.list("status", Status.ALIVE));
}
import jakarta.transaction.Transactional;
@Transactional
public Uni<List<Person>> findAlive() {
return people.list("status", Status.ALIVE);
}
@Transactional defines the transaction boundary without selecting a persistence unit.
Repository operations select the persistence unit associated with their entity mapping.
For example, if Person is mapped to the users persistence unit, people.persist(person) uses that unit without an additional session injection.
Keep the existing named persistence unit configuration and entity mappings, and use only one persistence unit and datasource within each reactive transaction.
For configuration details, see Multiple persistence units.
For direct session operations, select the named persistence unit with Quarkus’s @PersistenceUnit qualifier on the injected Mutiny.Session:
import io.quarkus.hibernate.orm.PersistenceUnit;
import jakarta.inject.Inject;
import jakarta.transaction.Transactional;
import org.hibernate.reactive.mutiny.Mutiny;
@Inject
@PersistenceUnit("users")
Mutiny.Session usersSession;
@Transactional
public Uni<Person> createForUsers(Person person) {
return usersSession.persist(person).replaceWith(person);
}
Here, @PersistenceUnit("users") selects the session to inject, and @Transactional manages the transaction when that session is used.
Adding the qualifier to a session field does not change which persistence unit a repository uses.
Do not mix @Transactional with @WithTransaction, @WithSession, or @WithSessionOnDemand in the same reactive pipeline.
See reactive transaction limitations and
combining reactive pipelines before changing transaction strategy.
Managed reactive sessions preserve dirty checking, but lazy associations still require explicit asynchronous fetching.
For example, if Person has an existing lazy address association:
@Transactional
public Uni<Address> findAddress(Long id) {
return people.findById(id)
.chain(person -> people.getSession()
.chain(session -> session.fetch(person.address)));
}
Return and compose these operations instead of blocking with await().indefinitely() or discarding a Uni in an invoke() callback.
Replace global Panache utilities deliberately
There is no Quarkus Data facade equivalent to reactive Panache.withSession(), withTransaction(), getSession(), executeUpdate(), flush(), or currentTransaction().
Use the session and transaction boundaries above for repository work.
For entity-bound session access and flushing, migrate as follows:
| Reactive Panache | Quarkus Data replacement |
|---|---|
|
|
|
|
|
|
|
For an entity-targeted update, |
For arbitrary HQL mutations, use the reactive session directly within a transaction:
@Transactional
public Uni<Integer> rename(String oldName, String newName) {
return people.getSession().chain(session -> session
.createMutationQuery("update Person set name = :newName where name = :oldName")
.setParameter("newName", newName)
.setParameter("oldName", oldName)
.executeUpdate());
}
For rollback-only control, use the active reactive transaction, rather than a blocking Jakarta Transactions TransactionManager:
@Transactional
public Uni<Void> markForRollback() {
return people.getSession().invoke(session -> session.currentTransaction().markForRollback()).replaceWithVoid();
}
For programmatic work that uses a session directly, inject Mutiny.SessionFactory and use the session supplied to its callback:
import org.hibernate.reactive.mutiny.Mutiny;
import jakarta.inject.Inject;
@Inject
Mutiny.SessionFactory sessionFactory;
public Uni<Person> createWithSessionFactory(Person person) {
return sessionFactory.withTransaction(session -> session.persist(person).replaceWith(person));
}
To select a named persistence unit, add Quarkus’s @PersistenceUnit qualifier to the factory injection:
import io.quarkus.hibernate.orm.PersistenceUnit;
@Inject
@PersistenceUnit("users")
Mutiny.SessionFactory usersSessionFactory;
public Uni<Person> createForUsers(Person person) {
return usersSessionFactory.withTransaction(session -> session.persist(person).replaceWith(person));
}
The callback above uses its supplied session directly.
That session is not automatically the context-bound session used by repository operations.
For work that calls a repository associated with the users persistence unit, use an intercepted CDI service method instead:
import jakarta.inject.Inject;
import jakarta.transaction.Transactional;
@Inject
Person.Repo people;
@Transactional
public Uni<Person> createForUsers(Person person) {
return people.persist(person).replaceWith(person);
}
Here, Person must be mapped to the users persistence unit, which the repository uses to obtain its session.
@Transactional establishes the transaction boundary; no additional session injection is needed for this repository call.
Update tests
Keep reactive database tests on a Vert.x context and compose assertions through UniAsserter.
For example, test the migrated nested repository using quarkus-test-vertx:
import static org.assertj.core.api.Assertions.assertThat;
import io.quarkus.test.TestReactiveTransaction;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.vertx.RunOnVertxContext;
import io.quarkus.test.vertx.UniAsserter;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
@QuarkusTest
public class PersonRepositoryTest {
@Inject
Person.Repo people;
@Test
@RunOnVertxContext
@TestReactiveTransaction
void persistAndFind(UniAsserter asserter) {
Person person = new Person();
person.name = "Ada";
person.status = Status.ALIVE;
asserter.execute(() -> people.persist(person));
asserter.assertThat(() -> people.find("name", "Ada").singleResult(),
found -> assertThat(found.name).isEqualTo("Ada"));
}
}
@TestReactiveTransaction rolls back the test’s changes.
Keep the test’s transaction handling compatible with the service methods it invokes.
TransactionalUniAsserter can still be used with the Panache-common transaction style; it does not depend on static entity query methods.
See testing Hibernate Reactive for the test dependencies and context requirements.
Replace static PanacheMock stubbing with CDI repository mocks where the application now injects a repository.
Stub reactive methods with their new Uni result types:
import static org.mockito.Mockito.when;
import io.quarkus.test.InjectMock;
import io.smallrye.mutiny.Uni;
@InjectMock
Person.Repo people;
// In the test setup, with an existing Person person:
when(people.persist(person)).thenReturn(Uni.createFrom().voidItem());
when(people.isPersistent(person)).thenReturn(Uni.createFrom().item(true));
when(people.findById(person.id)).thenReturn(Uni.createFrom().item(person));
Use quarkus-junit-mockito for @InjectMock support.
Retain tests for persistence, projections, locks, and custom identifiers, and add focused checks for changed persistence results, asynchronous state checks, update counts, and paging.
Migration checklist
-
Enable
quarkus-data-hibernateand its annotation processor; retain Hibernate Reactive, the reactive SQL driver, andquarkus-hibernate-reactive-panache-common. -
Remove the classic
quarkus-hibernate-reactive-panacheextension when converting the application. -
Replace reactive
PanacheEntitywithManagedEntity.Reactive, or implementManagedEntity.Reactive.CustomIdfor custom identifiers. -
Replace repository classes with
ManagedRepository.Reactive<Entity>orManagedRepository.Reactive.CustomId<Entity, Id>interfaces. -
Move static helpers to repository default methods, generated methods, or services, and update their call sites.
-
Account for
persist()andpersistAndFlush()returningUni<Void>, and composeisPersistent()as aUni<Boolean>. -
Replace entity flush calls with repository flush calls, and adapt bulk-update counts from
IntegertoLongwhere needed. -
Migrate sorting, paging, ranges, and
Parametersusages; compose previous-page checks and handleLongpage counts. -
Preserve a consistent reactive session/transaction strategy and replace global Panache wrappers and utilities.
-
Update static mocks to reactive CDI repository mocks and run the relevant persistence tests.