NHibernate Session First-Level Cache Memory Management for Large Batch Processing

Answering the Core Question

What is the optimal strategy for balancing memory reclamation via Session.Clear() without triggering unintended database updates, and how does clearing frequency affect identity‑map lookup performance in NHibernate 5.x?

The key is to flush before you clear for any batch that modifies entities, and to avoid auto‑flushes by setting FlushMode to Commit or Manual. Session.Clear() detaches all instances without flushing, so any dirty state present at the moment of clearing will be lost unless you flush first. After a clear, the identity map is empty, meaning subsequent Session.Get or query loads will hit the database again, incurring a round‑trip and object hydration overhead.

Confirmed Facts (NHibernate 5.x)

• Session is the mandatory first‑level cache (identity map).
• Clearing the session does not trigger updates; it only detaches entities.
• Updates occur on Session.Flush(), transaction commit, or when FlushMode.Auto forces a flush before a query.
• FlushMode.Commit or Manual prevents automatic flushes before queries.
• Clearing removes all entries from the identity map but leaves second‑level cache entries untouched.

Recommended Steps for Long‑Lived Sessions with Batches

1. Set session.FlushMode = FlushMode.Commit (or Manual if you want full control).
2. Process a fixed batch size that fits your memory budget (e.g., 5,000–10,000 entities).
3. For write batches:
   • Modify entities as needed.
   • Call session.Flush() to persist dirty state.
   • Immediately call session.Clear() to detach all instances and free memory.
4. For read‑only batches:
   • Mark entities as read‑only via session.SetReadOnly(entity, true) or use a StatelessSession if no tracking is required.
   • Skip explicit flush; only clear if you want to reset the identity map.
5. Repeat until all batches are processed, then commit the transaction.

Impact of Clearing Frequency

More frequent clears reduce heap usage and the cost of dirty‑checking, but each clear forces the identity map to be rebuilt on subsequent loads, increasing database round‑trips and object hydration time. Less frequent clears keep the identity map populated, improving cache hits, but can lead to high memory consumption and slower flush operations. The sweet spot depends on available memory, transaction size, and the ratio of reads to writes.

What We Still Need to Refine This Advice

Could you confirm whether your batches are primarily read‑only or involve modifications to existing entities? This detail will influence whether explicit flushes before each clear are mandatory.