0
# Quarkus Hibernate ORM with Panache
1
2
A Quarkus extension that dramatically simplifies persistence layer development by providing two complementary patterns: the Active Record pattern through PanacheEntity and the Repository pattern through PanacheRepository. It allows developers to use public fields directly in entity classes while providing sophisticated query capabilities with simplified HQL syntax that automatically expands shorthand queries into full HQL.
3
4
## Package Information
5
6
- **Package Name**: quarkus-hibernate-orm-panache
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `mvn io.quarkus:quarkus-maven-plugin:create -DprojectGroupId=org.acme -DprojectArtifactId=my-project -Dextensions=hibernate-orm-panache`
10
11
## Core Imports
12
13
```java
14
import io.quarkus.hibernate.orm.panache.PanacheEntity;
15
import io.quarkus.hibernate.orm.panache.PanacheRepository;
16
import io.quarkus.hibernate.orm.panache.Panache;
17
import io.quarkus.panache.common.Page;
18
import io.quarkus.panache.common.Sort;
19
import io.quarkus.panache.common.Parameters;
20
```
21
22
## Basic Usage
23
24
### Active Record Pattern
25
26
```java
27
import io.quarkus.hibernate.orm.panache.PanacheEntity;
28
import jakarta.persistence.Entity;
29
30
@Entity
31
public class Person extends PanacheEntity {
32
public String name;
33
public LocalDate birth;
34
public PersonStatus status;
35
36
public static Person findByName(String name) {
37
return find("name", name).firstResult();
38
}
39
40
public static List<Person> findAlive() {
41
return list("status", PersonStatus.Alive);
42
}
43
44
public static void deleteStefs() {
45
delete("name", "Stef");
46
}
47
}
48
49
// Usage
50
Person person = new Person();
51
person.name = "John Doe";
52
person.persist();
53
54
List<Person> allPeople = Person.listAll();
55
Person john = Person.findByName("John Doe");
56
```
57
58
### Repository Pattern
59
60
```java
61
import io.quarkus.hibernate.orm.panache.PanacheRepository;
62
import jakarta.enterprise.context.ApplicationScoped;
63
64
@ApplicationScoped
65
public class PersonRepository implements PanacheRepository<Person> {
66
public Person findByName(String name) {
67
return find("name", name).firstResult();
68
}
69
70
public List<Person> findAlive() {
71
return list("status", PersonStatus.Alive);
72
}
73
74
public void deleteStefs() {
75
delete("name", "Stef");
76
}
77
}
78
79
// Usage
80
@Inject
81
PersonRepository personRepository;
82
83
Person person = new Person();
84
person.name = "Jane Doe";
85
personRepository.persist(person);
86
87
List<Person> allPeople = personRepository.listAll();
88
Person jane = personRepository.findByName("Jane Doe");
89
```
90
91
## Architecture
92
93
Panache provides two main architectural patterns:
94
95
- **Active Record Pattern**: Entities extend PanacheEntity and inherit static query methods directly on the entity class
96
- **Repository Pattern**: Separate repository classes implement PanacheRepository for clean separation of concerns
97
- **Simplified Query Syntax**: Supports shorthand queries that automatically expand to full HQL
98
- **Field Access**: Direct public field access with automatic accessor generation at build time
99
- **Transaction Integration**: Seamless integration with Quarkus's transaction management
100
101
## Capabilities
102
103
### Active Record Operations
104
105
Core functionality for entities using the Active Record pattern through PanacheEntity and PanacheEntityBase. Provides static methods for querying, persistence, and database operations directly on entity classes.
106
107
```java { .api }
108
// Find operations
109
public static <T extends PanacheEntityBase> T findById(Object id);
110
public static <T extends PanacheEntityBase> Optional<T> findByIdOptional(Object id);
111
public static <T extends PanacheEntityBase> PanacheQuery<T> find(String query, Object... params);
112
public static <T extends PanacheEntityBase> PanacheQuery<T> findAll();
113
114
// List operations
115
public static <T extends PanacheEntityBase> List<T> list(String query, Object... params);
116
public static <T extends PanacheEntityBase> List<T> listAll();
117
118
// Stream operations
119
public static <T extends PanacheEntityBase> Stream<T> stream(String query, Object... params);
120
public static <T extends PanacheEntityBase> Stream<T> streamAll();
121
122
// Count operations
123
public static long count();
124
public static long count(String query, Object... params);
125
126
// Persistence operations
127
public void persist();
128
public void persistAndFlush();
129
public static void persist(Object firstEntity, Object... entities);
130
131
// Delete operations
132
public void delete();
133
public static long deleteAll();
134
public static boolean deleteById(Object id);
135
public static long delete(String query, Object... params);
136
```
137
138
[Active Record Operations](./active-record.md)
139
140
### Repository Pattern Operations
141
142
Repository-based persistence operations through PanacheRepository and PanacheRepositoryBase interfaces. Provides the same query and persistence capabilities as Active Record but through dedicated repository classes for better separation of concerns.
143
144
```java { .api }
145
// Find operations
146
public Entity findById(Id id);
147
public Optional<Entity> findByIdOptional(Id id);
148
public PanacheQuery<Entity> find(String query, Object... params);
149
public PanacheQuery<Entity> findAll();
150
151
// List operations
152
public List<Entity> list(String query, Object... params);
153
public List<Entity> listAll();
154
155
// Stream operations
156
public Stream<Entity> stream(String query, Object... params);
157
public Stream<Entity> streamAll();
158
159
// Count operations
160
public long count();
161
public long count(String query, Object... params);
162
163
// Persistence operations
164
public void persist(Entity entity);
165
public void persistAndFlush(Entity entity);
166
public void persist(Entity firstEntity, Entity... entities);
167
168
// Delete operations
169
public void delete(Entity entity);
170
public long deleteAll();
171
public boolean deleteById(Id id);
172
public long delete(String query, Object... params);
173
```
174
175
[Repository Pattern Operations](./repository-pattern.md)
176
177
### Query Building and Pagination
178
179
Advanced query building capabilities including pagination, sorting, filtering, and result processing through the PanacheQuery interface. Supports both page-based and range-based result retrieval.
180
181
```java { .api }
182
// Pagination
183
public <T extends Entity> PanacheQuery<T> page(Page page);
184
public <T extends Entity> PanacheQuery<T> page(int pageIndex, int pageSize);
185
public Page page();
186
public boolean hasNextPage();
187
public int pageCount();
188
189
// Sorting and filtering
190
public <T extends Entity> PanacheQuery<T> withLock(LockModeType lockModeType);
191
public <T extends Entity> PanacheQuery<T> withHint(String hintName, Object value);
192
public <T extends Entity> PanacheQuery<T> filter(String filterName, Parameters parameters);
193
194
// Result retrieval
195
public long count();
196
public <T extends Entity> List<T> list();
197
public <T extends Entity> Stream<T> stream();
198
public <T extends Entity> T firstResult();
199
public <T extends Entity> Optional<T> firstResultOptional();
200
public <T extends Entity> T singleResult();
201
```
202
203
[Query Building and Pagination](./query-pagination.md)
204
205
### Utility Operations
206
207
Utility classes for transaction management, EntityManager access, parameter building, and sorting configuration. Includes the Panache utility class for global operations and supporting classes for query parameters.
208
209
```java { .api }
210
// Panache utilities
211
public static EntityManager getEntityManager();
212
public static Session getSession();
213
public static TransactionManager getTransactionManager();
214
public static int executeUpdate(String query, Object... params);
215
public static void flush();
216
217
// Parameter building
218
public static Parameters with(String name, Object value);
219
public Parameters and(String name, Object value);
220
public Map<String, Object> map();
221
222
// Sorting
223
public static Sort by(String column);
224
public static Sort by(String column, Direction direction);
225
public Sort and(String name, Direction direction);
226
227
// Pagination
228
public static Page of(int index, int size);
229
public static Page ofSize(int size);
230
public Page next();
231
public Page previous();
232
```
233
234
[Utility Operations](./utilities.md)
235
236
## Types
237
238
### Core Entity Types
239
240
```java { .api }
241
public abstract class PanacheEntity extends PanacheEntityBase {
242
@Id
243
@GeneratedValue
244
public Long id;
245
}
246
247
public abstract class PanacheEntityBase {
248
// All static and instance methods for Active Record pattern
249
}
250
251
public interface PanacheRepository<Entity> extends PanacheRepositoryBase<Entity, Long> {
252
// Repository pattern for entities with Long ID
253
}
254
255
public interface PanacheRepositoryBase<Entity, Id> {
256
// All default methods for Repository pattern
257
}
258
```
259
260
### Query and Pagination Types
261
262
```java { .api }
263
public interface PanacheQuery<Entity> {
264
// Query building and result retrieval methods
265
}
266
267
public class Page {
268
public final int index;
269
public final int size;
270
271
public Page(int index, int size);
272
public static Page of(int index, int size);
273
public static Page ofSize(int size);
274
public Page next();
275
public Page previous();
276
}
277
278
public class Parameters {
279
public static Parameters with(String name, Object value);
280
public Parameters and(String name, Object value);
281
public Map<String, Object> map();
282
}
283
284
public class Sort {
285
public static Sort by(String column);
286
public static Sort by(String column, Direction direction);
287
public Sort and(String name, Direction direction);
288
289
public enum Direction {
290
Ascending, Descending
291
}
292
293
public enum NullPrecedence {
294
NULLS_FIRST, NULLS_LAST
295
}
296
}
297
```