2.6 KiB
JPA batch write configuration
HibernateJpaBatchExecutor is an advanced opt-in. The template does not enable Hibernate batch
write settings globally because statistics and statement reordering add runtime cost even in
applications that never perform bulk writes.
What the executor owns
A JpaBatchProfile owns the JDBC batch size for one batch run. Before the first item is written,
the executor applies profile.jdbcBatchSize() to the current Hibernate Session. The previous
Session value is restored in finally, including failed runs.
The executor does not open a transaction. The application service must enter a
TransactionPort.inWrite(...) boundary first.
What the application must configure
If a profile requests insert or update ordering, the matching Hibernate setting must already be enabled on the SessionFactory:
spring:
jpa:
properties:
hibernate:
order_inserts: true
order_updates: true
generate_statistics: true
hibernate.generate_statistics=true is required because BatchExecutionResult reports measured
flush and prepared-statement deltas. A disabled statistics registry would turn those values into
convincing zeros.
The HibernateStatisticsCollector must also receive an instrumented JdbcBatchCounter.
HibernateStatisticsCollector.of(sessionFactory) is intentionally insufficient for this executor:
Hibernate statistics do not expose actual JDBC batch executions.
hibernate.default_batch_fetch_size is unrelated to this write executor. It affects association
fetching and belongs to query/fetch tuning instead.
Entity identifier constraint
When JpaBatchProfile.batchingRequired() is true, an entity using
GenerationType.IDENTITY is rejected by HibernateBatchConfigurationGuard. Hibernate must issue
each INSERT immediately to obtain the generated identifier, so JDBC insert batching cannot satisfy
that profile.
Prefer a sequence-based identifier when a workload requires insert batching. Keep the sequence allocation size aligned with the database migration.
Failure behavior
Configuration is checked before the persister receives the first item:
- missing
hibernate.order_inserts=truewhen the profile requests insert ordering: fail; - missing
hibernate.order_updates=truewhen the profile requests update ordering: fail; - disabled Hibernate statistics: fail;
- missing JDBC batch instrumentation: fail;
- no caller-owned transaction: fail.
These failures are deliberate. A batch API that silently degrades to one statement per row produces correct data but false performance evidence, which is harder to detect than a startup or invocation failure.