When would you deliberately write code against Hibernate's native API instead of staying on the portable JPA API, and how do you stop that decision from spreading uncontrolled through a codebase?

## Be honest about what portability buys JPA's promise is that you can swap providers. In practice teams almost never do, and when they do, the JPA-level code is the easy part: what actually breaks is generated SQL, identifier generation behaviour, second-level cache configuration, HQL/JPQL dialect edges and mapping annotations. Treating `unwrap(Session.class)` as the boundary between 'portable' and 'locked in' misreads where the coupling lives — `@Filter`, `@Type`, `@BatchSize`, `@SQLRestriction`, `@NaturalId` and Hibernate-specific `@GenericGenerator` usage are all provider-specific, and they sit in your domain classes. The useful question is therefore: **for this capability, what is the cost of using the native API versus the cost of the workaround?** ## Cases where native usually wins **Bulk work.** `StatelessSession` has no persistence context, no dirty checking, no cascades and no first-level cache. For an import writing millions of rows it removes both the memory growth and the flush cost that make a normal session degrade. The JPA alternative — flush/clear batching — works but is slower and easy to get wrong. Hibernate 6.5+ also exposes `upsert` there. **Loading many ids.** `session.byMultipleIds(Entity.class).multiLoad(ids)` batches into IN-lists and consults the caches. Hand-rolling it in JPQL is possible but loses cache integration and parameter-batching subtleties. **Natural-id access.** `bySimpleNaturalId` has its own resolution cache mapping the business key to a primary key, which a plain query cannot use. **Cross-cutting predicates.** A mapped `@Filter` enabled per session applies to queries *and* collection loads, which is exactly what soft-delete and per-tenant scoping need. Emulating it by putting a condition in every query is a correctness risk — one missed query leaks rows. **Locking beyond the standard set.** JPA defines `PESSIMISTIC_READ`/`WRITE`; Hibernate adds `UPGRADE_NOWAIT` and `UPGRADE_SKIPLOCKED`. A work-queue implementation that must skip already-claimed rows has no portable equivalent worth writing. **Custom column mapping** via `UserType` / `@Type`, and **diagnostics** via `SessionFactory.getStatistics()` (query counts, cache hit ratios, session open/close counts) which has no JPA analogue and is invaluable in production triage. ## Cases where staying portable is the better call When JPA already covers it, use the standard form: `find`, `merge`, `remove`, JPQL, the Criteria API, `@EntityGraph`-style fetch planning, `LockModeType`, `EntityManager.detach`, JPA flush modes. Standard APIs are better documented, more familiar to new hires, easier to teach, and less likely to be removed in a major version — as `Session.save/update/saveOrUpdate` were, deprecated in Hibernate 6 and removed in 7. Provider-specific surface is exactly the surface that disappears. A second, quieter cost: HQL is a superset of JPQL and the same parser accepts both, so provider-specific syntax slips into code that *looks* standard. If portability matters to you at all, that drift needs a linting or review answer, not good intentions. ## Containment: what 'fenced' actually means 1. **One layer.** Native calls live in the persistence layer. Services receive intent-named operations (`claimNextBatch(...)`), never a `Session`. 2. **Unwrap at a single point per use case**, not sprinkled. If several methods need a `Session`, give the class one accessor. 3. **Name the seam.** A tiny interface per capability — bulk writer, queue claimer — with the Hibernate implementation behind it. That is a boundary you could reimplement, not a full ORM abstraction (writing your own generic ORM facade is a well-known way to build a worse ORM). 4. **Write it down.** A short decision record listing the native features relied on turns a future upgrade from archaeology into a checklist. 5. **Pin the risk to versions.** Native APIs change across major versions; keep them where an integration test will catch a behaviour change, and keep those tests fast enough that people run them. ## The judgement to voice The principal-level answer is not 'always JPA' or 'Hibernate is fine, use it all'. It is: portability is a *cost centre* unless someone can name the migration it protects; the real risks are major-version removals and team unfamiliarity; therefore prefer the standard API by default because it is the better-known and more stable one, use native features where they solve a problem the standard cannot, and make each such use visible and local so the bill is legible later.