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
```