Lucee Hibernate Extension 5.6.15.10-SNAPSHOT

hacking extensions
, , ,
1

We’re pleased to announce the first snapshot of the Lucee Hibernate Extension 5.6.

This is a massive update — Hibernate 5.4 to 5.6, a ground-up rewrite of logging, transaction handling, and connection management, plus over 20 bug fixes. It incorporates and builds on the work done by Ortus Solutions on their Hibernate extension fork.

History

ORM was originally part of Lucee core (Hibernate 3.5), then extracted into a standalone extension. The upgrade to Hibernate 5.4 started but only reached beta. Ortus Solutions forked the extension, completed the 5.4 upgrade, and maintained it. With 5.6, Lucee has resumed active development — merging the Ortus work and pushing forward with Hibernate 5.6, native logging, real transaction integration, and comprehensive test coverage.

There will be a upcoming Hibernate 7.2 Version for Lucee 7.1+

What’s New

Native Logging

ORM logging now routes through Lucee’s native log system — no more log4j/SLF4J configuration. New ormSettings: logSQL, logParams, logCache, logVerbose, formatSQL. Configure everything from Application.cfc, output goes to orm.log.

Real Transaction Integration

cftransaction now manages real Hibernate transactions. Commit flushes and commits, rollback rolls back. Mixed ORM + raw SQL in the same transaction share a single connection (previously caused silent failures). New BIFs: IsWithinORMTransaction() and GetORMTransactionIsolation().

New dbcreate Modes (Lucee 7.0.4+)

  • "create" — creates tables if they don’t exist, ignores existing
  • "create-drop" — creates on startup, drops on shutdown
  • "validate" — checks every mapped table exists, throws on mismatch

Connection & Session Fixes

  • Fixed connection leak: removed dead reconnect code that borrowed a second connection per session (LDEV-6156)
  • Sessions now open lazily per datasource instead of eagerly for all datasources on every request
  • ORMReload() no longer leaks connections or NPEs under concurrent load (LDEV-119)

Bug Fixes

  • Entity events now fire before global handler, matching ACF (LDEV-4561)
  • Property defaults apply when loading NULL from DB, matching ACF (LDEV-4121)
  • ORMEvictEntity()/ORMEvictCollection() fixed for multiple datasources (LDEV-2092)
  • persistent="false" correctly excludes inherited MappedSuperClass properties (LDEV-87)
  • DDL errors now throw at startup instead of being silently swallowed
  • sqlScript seed data no longer wiped by dropcreate
  • Invalid collectionType and ormtype values validated at ORM init with clear error messages
  • Wrong-case HQL column names throw helpful error instead of NPE (LDEV-3768)

See CHANGELOG.md and BREAKING-CHANGES.md for the complete list.

Lucee Compatibility

  • Lucee 6.2+ — full support for core ORM functionality
  • Lucee 7.0.4+ — adds dbcreate modes: create, create-drop, validate
  • Lucee 7.1+ — adds cftransaction isolation level support for ORM

Performance

We benchmarked the new extension against the Ortus extension across Lucee 7.0 and 7.1, using 32-thread parallel workloads against MySQL 8.

Upgrading from 7.0 + Ortus extension to 7.1 + Lucee extension:

Test 7.0+Ortus (ops/s) 7.1+Lucee (ops/s) Change GC delta
orm-entitynew 65,895 90,177 +37% -7.5
orm-entitynew-10 65,683 77,789 +18% -5
orm-entityload-pk 38,254 41,187 +8% -7.5
orm-hql 34,696 37,514 +8% -4.5
orm-entityload-filter 21,953 23,537 +7% -7
orm-entityload-10 15,354 15,854 +3% -12
orm-entitysave 7,402 7,534 +2% -9.5
orm-session-cycle 7,469 7,762 +4% -10.5

Even where throughput barely moves, GC pressure is cut roughly in half. The GC improvement is the bigger story for production workloads — fewer stop-the-world pauses under load.

Lucee extension vs Ortus extension (both on 7.1):

Test Ortus (ops/s) Lucee (ops/s) Lucee vs Ortus
orm-entitynew 73,736 90,177 +22%
orm-entitynew-10 66,464 77,789 +17%
orm-entityload-pk 39,861 41,187 +3%
orm-hql 37,539 37,514 flat
orm-entityload-filter 22,099 23,537 +7%
orm-entityload-10 15,935 15,854 flat
orm-entitysave 7,484 7,534 flat
orm-session-cycle 7,447 7,762 +4%

The Lucee extension is notably faster for entity creation (+17-22%) thanks to a leaner entity wrapping/instantiation path. Heavy Hibernate operations (save, session-cycle, HQL) are essentially identical — the extension overhead is negligible compared to Hibernate itself.

All benchmarks: 32 threads, MySQL 8 on localhost, Java 21, ABBA pattern to eliminate warmup bias. See the full benchmark writeup for methodology.

Documentation

We’ve also published comprehensive ORM documentation on docs.lucee.org — 11 recipe pages covering everything from getting started to troubleshooting:

Breaking Changes

If you’re upgrading from the 5.4 extension, please review BREAKING-CHANGES.md. Key changes:

  • Entity events fire before global handler (was the opposite)
  • Property defaults applied on entity load — NULL columns now get the CFC default value
  • DDL errors throw at startup — previously silently swallowed
  • Stricter HQL parsing — Hibernate 5.6 is stricter than 5.4
  • Lazy session opening — sessions open per-datasource on first use, not eagerly

Source & Issues

Feedback and bug reports welcome!

3 Likes