Choosing the surrounding persistence stack
Latest stable Based on Bluetape4k release 1.11.0
Confirm that the problem needs an ORM
Section titled “Confirm that the problem needs an ORM”Hibernate fits aggregate lifecycle, dirty checking, lazy associations, JPA annotations, and Spring Data JPA. A small SQL adapter or reporting query can be simpler without entity state and flush rules.
| Need | Start with | Boundary |
|---|---|---|
| Direct SQL, connection, and vendor control | bluetape4k-jdbc | Explicit mapping and transactions |
| JPA lifecycle and Spring Data | bluetape4k-hibernate | ORM aggregate model |
| Kotlin table and SQL DSL | bluetape4k-exposed | SQL-oriented JDBC or R2DBC runtime |
| Non-blocking persistence | bluetape4k-hibernate-reactive, bluetape4k-r2dbc | Do not wrap blocking Session calls in coroutines |
Hibernate and JDBC can coexist, but one transaction owner must provide the connection when they share a transaction. Do not leak Hibernate entities, Exposed rows, and JDBC DTOs across the same persistence boundary.
Hibernate is natural when aggregate changes are persisted by dirty checking. Exposed is often simpler when SQL shape stays explicit and rows map directly to DTOs. Existing JPA mappings, Spring Data repositories, and operational tooling also influence the choice. Align all library versions through the bluetape4k-dependencies BOM.
Executable next steps
Section titled “Executable next steps”- JPA Querydsl demo: Spring Data repositories, dynamic queries, and DTO projections.
- Blaze-Persistence demo: Entity Views, offset and keyset pagination, and count metadata.
SimpleQuerydslExamples: module-local Querydsl examples.mappingtests: associations, inheritance, IDs, trees, and localized entities.
This chapter can later link to a central ecosystem guide for Hibernate versus Exposed, JDBC-to-R2DBC migration, and transaction-manager combinations.