Skip to main content

Data access APIs (JPA)

Wiring Spring Data JPA onto the existing SQL DbLayer, including how writes are fed back into the UpdateQueue.

Overview​

genesis-data-spring-boot-starter lets a Spring Boot Genesis process read and write its data through Spring Data JPA / Hibernate, instead of (or alongside) the classic generated-DAO / DbLayer API. It is a Spring Boot autoconfiguration module (GenesisDataConfig): adding it to a module's dependencies is enough to get a working EntityManagerFactory, DataSource, PlatformTransactionManager and Spring Data repository support, all pre-wired to Genesis's own storage — spring-boot-starter-data-jpa itself comes along transitively, and only needs to be declared explicitly if a consuming module excludes transitive dependencies.

This is not a generic JPA set-up pointed at some database — every bean is deliberately wired back into the same storage stack the classic data access APIs already use:

  • The DataSource is the JDBC connection pool the SQL engine already owns, not an independently configured pool.
  • Table, column, schema and sequence names are mapped onto the exact physical names the Genesis dictionary and SQL engine use, so a JPA entity reads and writes the identical tables the generated DAO/view code targets.
  • Record IDs and sequence values come from the same allocator the rest of the platform uses, not a JPA/Hibernate-native identity or sequence strategy.
  • A Hibernate write is converted into the same DbRecord/WriteResult shape as any other write and published through the UpdateQueue, so it is visible to data servers, consolidators and other subscribers exactly like a classic write. See Writing back to the UpdateQueue.
  • An entity can opt into the same audit trail the rest of the platform uses. See Auditing.

Use this starter where ORM-style entity/repository code — Spring Data query derivation, JPQL, transactional service methods — fits better than the generated DAO API, while still participating fully in the platform's write-propagation and audit machinery. It is not a way to bypass the dictionary or manage schema independently of it.

Compared with the data access APIs​

Data access APIs (SyncEntityDb / AsyncEntityDb / RxEntityDb / RxDb)JPA data access (genesis-data-spring-boot-starter)
Programming modelGenerated type-safe DAOs, called directly (db.insert(trade))Spring Data repositories over @Entity classes (repository.save(trade)); derived and @Query finder methods
Supported DbLayerAny (FoundationDB, MS SQL, Oracle, PostgreSQL)SQL engines only — no FoundationDB equivalent
EntitiesGenerated table/view entities implementing DbEntityGenerated @Entity classes extending GenesisJpaEntity — driven by the same dictionary
Schema managementSchema created via the classic dictionary/table-definition processSame schema, but this starter never creates or migrates it — it only validates against it at start-up
TransactionsreadTransaction / writeTransaction blocksStandard Spring @Transactional, via a plain JpaTransactionManager
Write propagation to UpdateQueueBuilt into every write callVia a Hibernate integrator, registered on the same insert/update/delete events
Listening to UpdateQueue changesUpdateQueue table subscriptions@UpdateQueueListener methods on Spring beans — see Listening to UpdateQueue changes
AuditingExplicit entity.toAuditEntity(...) call made by the callerAutomatic, in the same transaction as the write, for entities implementing JpaAuditableEntity
Concurrency controlSystem-definition DbOptimisticConcurrencyMode check, enforced by the API on modify/deleteNone — see Optimistic concurrency below

Getting set up​

Before writing any code against this starter, two things must already be true:

  1. JPA entities have been generated from the dictionary. This starter supplies plumbing only — the DataSource, EntityManagerFactory, naming strategy, ID allocation, write-propagation and auditing. It has no entities of its own to persist. The @Entity classes and their Spring Data Repository interfaces are produced by a separate, dictionary-driven generator — see Data model (Spring), a hard prerequisite for this module.
  2. The Gradle plugin that drives generation is applied to the module. Entity and repository generation runs as a KSP-based Gradle plugin step during the build, not as something invoked by hand. See Spring Boot plugin.

With those in place, add genesis-data-spring-boot-starter to the module's dependencies. There is nothing further to @Import — GenesisDataConfig is a Spring Boot autoconfiguration, active as soon as both it and spring-boot-starter-data-jpa are on the classpath. spring-boot-starter-data-jpa is typically already present transitively via genesis-data-spring-boot-starter; it only needs to be declared explicitly if a consuming module excludes transitive dependencies.

Two things about this set-up differ from a typical Spring Data JPA project, and are worth calling out before going further:

SQL engines only

This starter requires a SQL DbLayer (H2, PostgreSQL, Oracle or SQL Server). A process running on the FoundationDB DbLayer has no SQLEngine bean to satisfy this configuration, so the starter simply does not apply — there is no FoundationDB equivalent.

Schema must already exist

genesis.jpa.ddl-auto defaults to validate. This starter does not create, update or migrate schema — it only checks, at start-up, that the existing schema matches the mapped entities. The physical tables and columns must already exist via the classic dictionary/table-definition process. Standing up a brand-new environment and expecting JPA entities to create their own tables — the default in many standalone Spring Boot JPA projects — will fail Hibernate's validation at start-up.

PropertyDefaultMeaning
genesis.jpa.enabledtrueGates GenesisDataConfig. Even when true, the configuration only activates if EntityManagerFactory is on the classpath — i.e. spring-boot-starter-data-jpa must be a dependency. If it isn't, the whole autoconfiguration is inert, with no error.
genesis.jpa.ddl-autovalidateFed to Hibernate's schema-management setting. See above.

Example configuration​

The smallest realistic path is a generated entity, a generated Spring Data repository, and a CRUD call. For a dictionary table POSITION with a PositionId primary key and fields instrumentId, quantity, notional, value, pnl, generation produces an entity extending GenesisJpaEntity.Base (which supplies the framework-managed recordId/timestamp columns) and implementing DbRecordProvider (which is what lets a write reach the UpdateQueue):

@Entity
@Table(schema = GenesisJpaEntity.GENESIS_SCHEMA, name = "POSITION")
class Position @JvmOverloads constructor(
positionId: String = "",
instrumentId: String? = null,
@field:NotNull
@field:Column(nullable = false)
var quantity: Int = 0,
var notional: Double? = null,
var value: Double? = null,
var pnl: Double? = null,
) : GenesisJpaEntity.Base<String>(), DbRecordProvider {

@field:Id
@field:Column(unique = true, nullable = false, name = "POSITION_ID", updatable = false, length = 64)
override var pk: String = positionId

@field:NotNull
@field:Column(unique = true, nullable = false, length = 64)
lateinit var instrumentId: String

override fun toDbRecord(): DbRecord = PositionDbMapper.toDbRecord(this)
}

alongside a generated repository extending one of the GenesisJpaRepository base interfaces (save, saveAll, delete, deleteByPk, findAll, findByPk):

interface PositionRepository : GenesisJpaRepository.Nullable<Position, String>

Using it needs nothing beyond @Autowired (or constructor injection); GenesisDataConfig's beans and Spring Data JPA's own repository factory do the rest. Calling save on a new entity inserts; calling it on a loaded entity updates:

@Autowired
lateinit var positionRepository: PositionRepository

fun createPosition() {
val saved = positionRepository.save(
Position(positionId = "POS1", instrumentId = "INSTR1", quantity = 100),
)
// saved.recordId / saved.timestamp are now populated by the framework generators
}

fun readPosition(): Position? = positionRepository.findByPk("POS1")

The entity and repository classes themselves are only ever generated as Kotlin source — there is no Java-generation mode — but everything above this line is genuinely usable from either language; a Java-only process consumes the generated Kotlin classes exactly as shown.

Configuration options​

Repository wiring​

Every generated repository extends GenesisJpaRepository (or its read-only counterpart, for view-backed entities), in one of a Nullable or Optional variant depending on how a missing record should be represented. Read methods run read-only; the mutating ones each run in their own read-write transaction.

GenesisJpaRepository itself extends Spring Data's minimal marker interface, org.springframework.data.repository.Repository, not CrudRepository or JpaRepository as you might expect from stock Spring Data JPA. Repository declares no methods of its own — every CRUD method (save, saveAll, delete, deleteByPk, and the findAll overloads) is declared directly on GenesisJpaRepository, rather than inherited from a richer Spring Data ancestor.

For each dictionary index, the generator emits a findBy* method — plus, for non-unique indices, Sort/Pageable overloads, existsBy* and countBy* — backed by an explicit @Query. These are generated JPQL, not Spring Data's method-name query derivation:

interface TypedRecordRepository : GenesisJpaRepository.Nullable<TypedRecord, TypedRecord.ByGroupIdItemId> {
@Query("select e from TypedRecord e where e.pk.groupId = :groupId")
fun findByGroupId(groupId: String): List<TypedRecord>

@Query("select e from TypedRecord e where e.pk.groupId = :groupId")
fun findByGroupId(groupId: String, pageable: Pageable): Page<TypedRecord>

@Query("select count(e) > 0 from TypedRecord e where e.pk.groupId = :groupId")
fun existsByGroupId(groupId: String): Boolean

@Query("""
select e from TypedRecord e
where e.pk.groupId = :groupId and e.pk.itemId = :itemId
""")
fun findByGroupIdAndItemId(groupId: String, itemId: Int): TypedRecord?
}
fun recordsInGroup(groupId: String): List<TypedRecord> =
typedRecordRepository.findByGroupId(groupId, Sort.by("itemId"))

fun oneRecord(groupId: String, itemId: Int): TypedRecord? =
typedRecordRepository.findByGroupIdAndItemId(groupId, itemId)

A unique-index lookup returns a single nullable result — there is no Optional-returning variant generated by default for a Nullable repository. Projections are not generated either; declare an interface extending the generated repository with a projection return type if one is needed.

Writing back to the UpdateQueue​

Genesis's platform — data servers, consolidators, request servers, any reactive subscriber — learns about data changes through the UpdateQueue. A JPA write, left alone, would be invisible to all of that: Hibernate would happily persist rows that the rest of the platform never hears about.

This starter closes that gap with a Hibernate integrator registered on the POST_INSERT/POST_UPDATE/POST_DELETE events. For an entity that is both a GenesisJpaEntity and a DbRecordProvider (every generated entity is both), it builds the same kind of update the classic RxDb API publishes, and sends it through the same update queue RxDb uses. Publication is deferred until the transaction has committed, and only fires on success — so a rolled-back transaction publishes nothing, even though Hibernate's post-event already fired at flush time.

Publication also depends on the process actually running against a real update-queue transport (a genuine multi-process deployment on ZeroMQ, MQTT or JMS) rather than the in-memory queue a standalone or test process falls back to — the same distinction classic RxDb writes already respect. On a process where that isn't the case, JPA writes still land in the database; they simply aren't published anywhere. There's no error or warning-level log for this — a write that "doesn't show up" downstream, with no other symptom, is usually this.

A GenesisJunit-based test (@GenesisTest, @GenesisDatabaseTest, or the Spring-flavoured @GenesisSpringTest) replicates this for test purposes. It will by default provide a local ZeroMQ update queue to the application. See Testing API (Spring) for more details.

Practical implication: a service method that calls repository.save(entity) inside a @Transactional boundary gets platform-wide visibility of that write for free on a real deployment — no manual event publication needed, and no manual rollback handling needed either.

Listening to UpdateQueue changes​

To react to changes on a table from Spring code, annotate a method on a Spring bean with @UpdateQueueListener (global.genesis.spring.data). The method takes exactly one parameter, an UpdateQueueEvent<T> for a generated entity T, and is subscribed to that entity's table on the UpdateQueue:

import global.genesis.spring.data.UpdateQueueEvent
import global.genesis.spring.data.UpdateQueueListener

@Component
class PositionWatcher {

@UpdateQueueListener
fun onAnyChange(event: UpdateQueueEvent<Position>) {
println("${event.type} on ${event.tableName}: ${event.entity.pk}")
}

@UpdateQueueListener
fun onNewPosition(event: UpdateQueueEvent.Insert<Position>) {
println("New position ${event.entity.pk}")
}

@UpdateQueueListener(fields = ["QUANTITY"])
fun onQuantityChange(event: UpdateQueueEvent.Modify<Position>) {
println("Quantity ${event.previous.quantity} -> ${event.current.quantity}")
}
}

UpdateQueueEvent is a sealed type with three variants: Insert, Modify and Delete. Every event carries entity, tableName, recordId, timestamp and type. Modify also carries previous, current and modifiedFields, and its entity is current. Declaring the parameter as one of the variants subscribes the method to that change type only; UpdateQueueEvent<T> receives all three.

AttributeDefaultMeaning
entitytaken from the parameter's type argumentThe entity to listen to. Only needed when the parameter doesn't name it; if both are given they must agree
typesallUpdateQueueEvent.Type values INSERT, MODIFY and/or DELETE. Must agree with the parameter type if that already narrows it
fieldsallDictionary field names (for example "QUANTITY"). Only filters modifies: a modify is delivered only when one of these fields changed. Inserts and deletes are always delivered
delaynoneBatching interval in milliseconds. Updates are collected and delivered every delay ms, so several rapid updates to one record may arrive merged

Things to know when writing a listener:

  • The entity is a detached copy. Each event's entity is a new instance built from the update, not one managed by an EntityManager. Changing it doesn't write anything; save through a repository if you need to.
  • It runs on the update queue's own thread, outside any transaction. The method is called synchronously as updates arrive, so a slow or blocking listener holds up delivery. Hand heavy work off to another thread.
  • Exceptions are logged, not propagated. An exception thrown by the method is logged at ERROR and the update is dropped. There is no retry. The listener stays registered and receives later updates.
  • Only singleton beans. A listener method on a prototype-scoped bean fails at startup. Listeners start receiving updates once the application's singletons have been created.
  • Only generated table entities. The entity must carry @Table(name = ...), and its generated mapper must be registered as a bean. The generated JpaConfiguration class does this for tables, but not for views.

Mistakes in the declaration fail at startup rather than when an update arrives: a method with other than one parameter, an entity that can't be determined, an entity or types value that disagrees with the parameter type, or an entity with no registered mapper.

Listeners receive updates under the same conditions as any other UpdateQueue subscriber, so the rules above for publication apply: a JPA write is only published after its transaction commits, and only on a process running against a real update-queue transport.

In a @GenesisSpringTest, the listener bean must be added to the test context explicitly, because GenesisTestApplication does no component scanning: register it with @Import or a @TestConfiguration (see Testing API (Spring): A simple example).

Auditing​

Independently of UpdateQueue publication, an entity can implement JpaAuditableEntity<A> to get an automatic audit trail. Where a dictionary table has an audit sibling table, the generator makes the source entity implement it in addition to the usual base classes:

class TypedRecord @JvmOverloads constructor(
groupId: String,
itemId: Int,
var name: String? = null,
// ...
) : GenesisJpaEntity.Base<TypedRecord.ByGroupIdItemId>(),
DbRecordProvider,
JpaAuditableEntity<TypedRecordAudit> {

override fun toAuditEntity(
auditEventType: String?,
auditEventDatetime: OffsetDateTime?,
auditEventText: String?,
auditEventUser: String?,
): TypedRecordAudit = TypedRecordDbMapper.toAuditEntity(
this, auditEventType, auditEventDatetime, auditEventText, auditEventUser,
)
}

A second Hibernate integrator persists the audit row, in the same transaction as the source write, whenever an audit context is active around the call. The context — event type, audit text, username — is set by the caller, and is guaranteed to be cleared afterwards even on an exception:

// In TypedRecordService, a Spring bean
@Transactional
fun createTypedRecord(groupId: String, itemId: Int) {
typedRecordRepository.save(TypedRecord(groupId = groupId, itemId = itemId))
}

// In the calling bean: the audit context encloses the whole transaction
fun bookTypedRecord(groupId: String, itemId: Int, userName: String) {
AuditContextHolder.withAuditContext(
AuditContext(userName = userName, eventType = "TYPED_RECORD_INSERT", auditText = "manual booking"),
) {
typedRecordService.createTypedRecord(groupId, itemId)
}
// The transaction committed inside the block, so a TypedRecordAudit row was persisted with it.
}

fun readTypedRecordAudit(typedRecordAuditId: String): TypedRecordAudit? =
typedRecordAuditRepository.findByPk(typedRecordAuditId)

With no context set, the write is still persisted, but no audit row appears — silently, with no error or log. Whether the audit row itself reaches the UpdateQueue follows the same publication rules described above.

The withAuditContext block's placement relative to the @Transactional boundary is also load-bearing, not just whether a context is set at all — see Audit support on the data model page for the placement rule.

Transactions​

GenesisDataConfig registers a plain JpaTransactionManager over the EntityManagerFactory — ordinary Spring @Transactional semantics apply, with no Genesis-specific behaviour layered on top, including the rollback rules: by Spring's standard default, only an unchecked exception triggers a rollback, and a checked exception commits unless the method's @Transactional annotation sets rollbackFor. A repository's own save/delete methods are themselves transactional, so calling more than one from within an outer @Transactional service method joins the same transaction, by Spring's default REQUIRED propagation, rather than opening a nested one. If any step throws an unchecked exception (or a checked one covered by rollbackFor), every write made in that transaction rolls back together, and (per the previous two sections) nothing partial is published to the UpdateQueue or audited.

Without an outer @Transactional boundary, each repository call is its own, independent transaction, so a failure part-way through a multi-step operation leaves earlier writes in place:

// One transaction: if the second save() throws, the first is rolled back too.
@Transactional
fun transferPosition(fromId: String, toId: String, quantity: Int) {
val from = positionRepository.findByPk(fromId)!!
from.quantity -= quantity
positionRepository.save(from)

val to = positionRepository.findByPk(toId)!!
to.quantity += quantity
positionRepository.save(to)
}

// No outer boundary: each save() opens (and commits) its own transaction.
// A failure on the second save leaves the first one committed.
fun transferPositionUnsafe(fromId: String, toId: String, quantity: Int) {
val from = positionRepository.findByPk(fromId)!!
from.quantity -= quantity
positionRepository.save(from)

val to = positionRepository.findByPk(toId)!!
to.quantity += quantity
positionRepository.save(to)
}

To check transaction state programmatically — for example, to assert a method is only ever called within an existing transaction — use Spring's standard TransactionSynchronizationManager.isActualTransactionActive(); this starter adds nothing Genesis-specific on top of it.

Optimistic concurrency​

The Spring JPA layer does no optimistic concurrency checking. It doesn't generate @Version annotations, it doesn't read the DbOptimisticConcurrencyMode setting, and nothing links the two. Those settings apply to the classic Genesis data access APIs and haven't been ported to Spring yet.

See also​

  • Getting Started with Spring — step-by-step tutorial for adding Spring to a Genesis application.
  • Application core — the base Spring Boot starter this module builds on.
  • Data model (Spring) — the entity/repository generator this starter's beans require; generate entities before writing any code here.
  • Spring Boot plugin — the Gradle plugin and KSP setup that drives that generation.
  • Data access APIs — the classic generated-DAO API this module sits alongside.
  • Update Queue — the mechanism JPA writes are published through, and @UpdateQueueListener methods subscribe to.
  • Testing API (Spring) — the @GenesisSpringTest test structure this module's tests build on.