> For the complete documentation index, see [llms.txt](https://bxorm.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bxorm.ortusbooks.com/release-history/1x.md).

# 1.x

## 1.6.5 - 2026-05-26

### ⭐ Added

* New AI skills under `.agents/skills` and custom skills under `.agents/skills-custom`
* New Custom Skills for AI agents under `.agents/skills-custom` for ORM configuration and troubleshooting.
* Consolidation of AI instruction files to `AGENTS.md` with a pointer from `CLAUDE.md`

### ⚡ Updates

* Updated readme with AI skills information and setup.
* Dependabot quarterly
* Updated BoxLang testing to v1.13.0

### 🐛 Fixed

* Fix `ClassCastException` when saving entities with `ormtype="float"` properties containing Integer values (e.g., `default="0"`). Added missing `FloatConverter` and registered it in `HibernateXMLWriter`.

See [v1.6.5 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.6.4...v1.6.5)

## 1.6.4 - 2026-05-13

### ⭐ Added

* Added debug logging for ORM startup metrics, including entity metadata parsing and Hibernate SessionFactory build times.

### 🐛 Fixed

* [BLMODULES-191](https://ortussolutions.atlassian.net/browse/BLMODULES-191) - Defensive code against disabled ORM logging causing boxlang cli startup failure.
* [BLMODULES-198](https://ortussolutions.atlassian.net/browse/BLMODULES-198) - Fix `missingRowIgnored` annotation not being applied to collection relationships.
* [BLMODULES-204](https://ortussolutions.atlassian.net/browse/BLMODULES-204) - Ensure transaction open only flushes session if `autoManageSession` is enabled.

See [v1.6.4 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.6.3...v1.6.4)

## 1.6.3 - 2026-04-29

### 🐛 Fixed

* [BLMODULES-190](https://ortussolutions.atlassian.net/browse/BLMODULES-190) - Fix error on `one-to-many` associations when `inversejoincolumn` attribute is specified

See [v1.6.3 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.6.2...v1.6.3)

## 1.6.2 - 2026-04-09

### 🐛 Fixed

* [BLMODULES-173](https://ortussolutions.atlassian.net/browse/BLMODULES-173) - Fixed issue with mutated entity metadata leaking across BoxLang applications.

See [v1.6.2 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.6.1...v1.6.2)

## 1.6.1 - 2026-04-09

### 🐛 Fixed

* Fixed issue with `scale` annotation not properly cast to a string in `ClassicPropertyMeta`.
*

See [v1.6.1 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.6.0...v1.6.1)

## 1.6.0 - 2026-04-02

### ⭐ Added

* Adds support for composite IDs.

### 🐛 Fixed

* Fixes an issue of lost mappings on entity discoveries, due to wrong parent context being sent.

See [v1.6.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.5.0...v1.6.0)

## 1.5.0 - 2026-03-27

### 🐛 Fixed

* **Memory leak on ORM reload** — all open Hibernate sessions are now closed before tearing down `SessionFactory` instances, preventing stale session/factory references from blocking garbage collection after every `ORMReload()`.
* **Memory leak on session factory build failure** — `SessionFactoryBuilder` now wipes the `BootstrapServiceRegistry` when `buildSessionFactory()` throws, so the registry is not orphaned on the failure path.
* **Stale ORM context after reload** — the old `ORMContext` is removed from the JDBC context before rebuilding, and a fresh one is eagerly installed after the new app is live, eliminating null-window races for concurrent callers.
* **Null context in threaded scenarios** — `EntityTuplizer` and related components now obtain the box context safely when executing in a non-request thread.
* **Null pointer when the method does not exist on a tuplizer call** — added an existence check before invoking optional methods.
* Improved exception logging to include full stack traces throughout the ORM lifecycle.
* Fixed issue with `dbdefault` annotation not properly cast to a string in `ClassicPropertyMeta`.

### ⭐ Added

* Use a deterministic directory name based on config content rather than a hashcode of the config file path for generated mapping files, ensuring consistent mapping file usage across different environments and absolute paths.

### ⚡ Changed

* **Hot-path interception performance** — all `interceptorService.announce()` calls on hot code paths (entity instantiation, config load) are now guarded with `hasState()` checks and use lazy `Struct` suppliers, avoiding unnecessary struct allocation when no listeners are registered.
* `ORMConfig` now receives and threads the `IBoxContext` through `process()` and `getAppDefaultDatasource()` so the correct application datasource is resolved in all execution contexts.
* `ORMService.reloadApp()` now performs an atomic put-and-swap of the new/old `ORMApp` in the registry to minimize the disruption window for requests running concurrently with a reload.

See [v1.5.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.4.1...v1.5.0)

## 1.4.1 - 2026-03-23

### ⛓️‍💥 Changed

* This version requires Boxlang Runtime `v1.11.x` and above

### 🗑 Deprecated

* The `autoGenMap` configuration setting is now deprecated in favor of `generateMappings`. Same function, different name. See [BLMODULES-119](https://ortussolutions.atlassian.net/browse/BLMODULES-119) for details.

### ⭐ Added

* [BLMODULES-119](https://ortussolutions.atlassian.net/browse/BLMODULES-119) - Add support for `generateMappings=false` (aliased as `autoGenMap` for backwards compatibility) to disable automatic mapping generation and require manual mapping files.

### 🐛 Fixed

* [BLMODULES-136](https://ortussolutions.atlassian.net/browse/BLMODULES-136) - Fix issue with naming strategy being double-applied on table and column identifiers.
* [BLMODULES-146](https://ortussolutions.atlassian.net/browse/BLMODULES-146) - Fix issue where rollbacks, commits, etc. inside a transaction block were not properly scoped to the transaction block and could affect the entire session.

See [v1.4.1 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.4.0...v1.4.1)

## 1.4.0 - 2026-02-06

### ⛓️‍💥 Changed

* This version is now only compatible with Boxlang Runtime `v1.10.x` and above

### 🐛 Fixed

* [BLMODULES-120](https://ortussolutions.atlassian.net/browse/BLMODULES-120) - Add new settings for `lazy` and `defaultBatchSize` to provide compat implementations
* [BLMODULES-130](https://ortussolutions.atlassian.net/browse/BLMODULES-130) - Fix collection handling for java List objects - which hibernate returns
* Transaction management udpates to deal with complex nested transactions
* Ensure manual flush mode when `autoManageSession` is `false`
* Add savepoint interception for nested transactions and flush

See [v1.4.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.3.0...v1.4.0)

## 1.3.0 - 2026-01-07

### 🐛 Fixed

* [BLMODULES-110](https://ortussolutions.atlassian.net/browse/BLMODULES-110) - Implement `EntityTuplizer.getEntityMode()` for relationship getters
* [BLMODULES-113](https://ortussolutions.atlassian.net/browse/BLMODULES-113) - Drop unnecessary logging on request end for non-ORM requests
* [BLMODULES-117](https://ortussolutions.atlassian.net/browse/BLMODULES-117) - Resolve transaction interception error when no ORM App is present
* [BL-2039](https://ortussolutions.atlassian.net/browse/BL-2039) - Fix "Datasource with name ... not found" in empty transactions on subsequent requests

### ⭐ Added

* [BLMODULES-118](https://ortussolutions.atlassian.net/browse/BLMODULES-118) - Enable `table`, `schema`, and `catalog` annotations for joined subclasses.
* [BL-2052](https://ortussolutions.atlassian.net/browse/BL-2052) - Move ORM context removal to shutdown listener for improved datasource cleanup on request end.

See [v1.3.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.2.0...v1.3.0)

## 1.2.0 - 2025-12-05

### 🐛 Fixed

* [BLMODULES-102](https://ortussolutions.atlassian.net/browse/BLMODULES-102) - Fix ORM usage in threads causing ConcurrentModificationException

See [v1.2.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.1.1...v1.2.0)

## 1.2.0 - 2025-12-05

### 🐛 Fixed

* [BLMODULES-102](https://ortussolutions.atlassian.net/browse/BLMODULES-102) - Fix ORM usage in threads causing ConcurrentModificationException

See [v1.2.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.1.3...v1.2.0)

## 1.1.2 - 2025-09-06

### 🐛Fixed

* [BLMODULES-84](https://ortussolutions.atlassian.net/browse/BLMODULES-84) - Resolved incorrect location of many-to-one on discriminated child
* [BLMODULES-85](https://ortussolutions.atlassian.net/browse/BLMODULES-85) - Resolved an issue where transaction interception points would throw an error on non-orm-enabled applications
* [BLMODULES-88](https://ortussolutions.atlassian.net/browse/BLMODULES-88) - Resolved an issue where entity modifications during orm events were not persisting correctly to the database
* [BLMODULES-90](https://ortussolutions.atlassian.net/browse/BLMODULES-90) - Resolved an issue where numerics were not being coerced correctly to strings on applicable properties when used in ORMExecuteQuery

See [v1.1.2 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.1.1...v1.1.2)

## 1.1.1 - 2025-08-27

### 🐛 Fixed

* Changed Array.fromString usage to use ListUtil as the method was removed from the Array class in v1.5.0 of the core
* [BLMODULES-83](https://ortussolutions.atlassian.net/browse/BLMODULES-83) - Resolved inheritiance and `mappedSuperClass` issues with 3+ levels
* [BLMODULES-80](https://ortussolutions.atlassian.net/browse/BLMODULES-80) - Fix for class relationships not being found due to core compiler casing changes

See [v1.1.1 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.1.0...v1.1.1).

## 1.1.0 - 2025-08-04

### ⛓️‍💥 Changed

* This new version only works with the fixes on [BoxLang v1.4.0](https://boxlang.ortusbooks.com/readme/release-history/1.4.0)

### 🐛 Fixed

* Updates to Request Context based on BoxLang v1.4.0 updates
* Lots of dependency updates

See [v1.1.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.11...v1.1.0).

## 1.0.11 - 2025-06-10

### 🐛 Fixed

* Fixed issue with default cache not being created when cache provider was empty - Resolves [BLMODULES-53](https://ortussolutions.atlassian.net/browse/BLMODULES-53)
* Fix error starting up on non-ORM apps - Resolves [BLMODULES-49](https://ortussolutions.atlassian.net/browse/BLMODULES-49)
* Add support for `tinyint` and `tinyinteger` ORM types - Resolves [BLMODULES-59](https://ortussolutions.atlassian.net/browse/BLMODULES-59)
* Skip type conversion on version properties - Resolves [BLMODULES-45](https://ortussolutions.atlassian.net/browse/BLMODULES-45)
* Drop ormApp instantiation in baseORMBIF - Fixes [BLMODULES-54](https://ortussolutions.atlassian.net/browse/BLMODULES-54)
* Improve default datasource look up and throw error if empty - See [BLMODULES-56](https://ortussolutions.atlassian.net/browse/BLMODULES-56)

See [v1.0.11 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.10...v1.0.11).

## 1.0.10 - 2025-05-03

### 🐛 Fixed

* Throw or log an error when class annotation on association is an empty string - Resolves [BLMODULES-50](https://ortussolutions.atlassian.net/browse/BLMODULES-50)
* Fix support for `dataType` annotation on version properties - Resolves [BLMODULES-51](https://ortussolutions.atlassian.net/browse/BLMODULES-51)

### ⭐ Added

* Implement 'index' annotation - Resolves [BLMODULES-47](https://ortussolutions.atlassian.net/browse/BLMODULES-47)
* Implement multi-column support in `column` and `fkcolumn` - Resolves [BLMODULES-48](https://ortussolutions.atlassian.net/browse/BLMODULES-48)
* Implement cache support at the property level - Resolves [BLMODULES-52](https://ortussolutions.atlassian.net/browse/BLMODULES-52)

See [v1.0.10 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.9...v1.0.10).

## 1.0.9 - 2025-04-29

### 🐛 Fixed

* Implement `elementType`,`elementColumn` annotations - Resolves [BLMODULES-46](https://ortussolutions.atlassian.net/browse/BLMODULES-46)
* Fixes for map collection when `structkeytype` or `structkeycolumn` are ignored - Resolves [BLMODULES-45](https://ortussolutions.atlassian.net/browse/BLMODULES-45)
* Skip usage of `AttributeConverter` on identifier properties - Resolves [BLMODULES-44](https://ortussolutions.atlassian.net/browse/BLMODULES-44)

See [v1.0.9 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.8...v1.0.9).

## 1.0.8 - 2025-04-25

### ⭐ Added

* Set hibernate version in build so `ORMGetHibernateVersion()` stays accurate - See [a8c7c16](https://github.com/ortus-boxlang/bx-orm/commit/a8c7c16d8b3ee766ab182aad490909a5509f10e4)

### 🐛 Fixed

* Foreign key must have same number of columns as the referenced primary key - Resolves [BLMODULES-41](https://ortussolutions.atlassian.net/browse/BLMODULES-41)
* Missing FKColumn on To-Many Relationship Should Check the Inverse Relationship for Column data - Resolves [BLMODULES-42](https://ortussolutions.atlassian.net/browse/BLMODULES-42)
* XMLWriter - Skip id,composite-id XML rendering on subclasses - Resolves [BLMODULES-38](https://ortussolutions.atlassian.net/browse/BLMODULES-38)
* XML Writer - Skip generator on composite keys - Resolves [BLMODULES-40](https://ortussolutions.atlassian.net/browse/BLMODULES-40)
* XMLWriter - Don't set insert or update on one-to-one elements - Resolves [BLMODULES-39](https://ortussolutions.atlassian.net/browse/BLMODULES-39)
* Fix support for 'params' attribute string notation - See [BLMODULES-40](https://ortussolutions.atlassian.net/browse/BLMODULES-40)

See [v1.0.8 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.7...v1.0.8).

## 1.0.7 - 2025-04-14

### 🐛 Fixed

* Fix string casting error on `lazy` property annotation

See [v1.0.7 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.6...v1.0.7).

## 1.0.6 - 2025-04-14

### 🐛 Fixed

* Fixed support for custom naming strategies - See [8e68206](https://github.com/ortus-boxlang/bx-orm/commit/8e68206e3d3f197a69fc12467c42c7c5de1c7eac)
* Fixed "smart" naming strategy when entity name begins with an uppercase character - See [b47b512](https://github.com/ortus-boxlang/bx-orm/commit/b47b51239a15530df245c5e12c36c48e10b09266)
* Move compat configuration to bx-compat-cfml - See [c8b7173](https://github.com/ortus-boxlang/bx-orm/commit/c8b7173f1c0fc01646d3b3d980d9d889ab8c7686)
* Fixed the two types of discriminator generation order - See [ea62a62](https://github.com/ortus-boxlang/bx-orm/commit/ea62a62fe1f4fe66bce58b4e27659b60faccb1aa)
* fix bag element being appended to wrong node on subclasses - See [f82b2ac](https://github.com/ortus-boxlang/bx-orm/commit/f82b2ac24e5d9cf1f43da5a8437c481be5e4f0c5)
* change to use caster so that lazy=true does not error - See [0096387](https://github.com/ortus-boxlang/bx-orm/commit/00963873c44480e6597ac0e3962d66244c42c865)

### ⭐ Added

* Add missing `date` property type - See [c6ec8a2](https://github.com/ortus-boxlang/bx-orm/commit/c6ec8a2e2dadfb344deb93edb7a1a2ccf8d0fb46)
* Add alternate spellings for big decimal and big integer - See [5e199f9](https://github.com/ortus-boxlang/bx-orm/commit/5e199f9e5674c3a3802a5e225d45f187b0724e23)
* Add flush after commit on transaction end - See [e2df378](https://github.com/ortus-boxlang/bx-orm/commit/e2df378c261a2c0aea99749d7bf04cd688d57658)

See [v1.0.6 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.5...v1.0.6).

## 1.0.5 - 2025-04-07

### 🐛 Fixed

* Removed debugging code

See [v1.0.5 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.4...v1.0.5).

## 1.0.4 - 2025-04-06

### 🐛 Fixed

* Metadata parsing throws error on empty class despite `skipCFCWithError` setting - Resolves [BLMODULES-37](https://ortussolutions.atlassian.net/browse/BLMODULES-37)

See [v1.0.4 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.3...v1.0.4).

## 1.0.3 - 2025-04-06

### 🐛 Fixed

* EntityLoad returning incorrect results with criteria struct filter on parent properties - Resolves [BLMODULES-36](https://ortussolutions.atlassian.net/browse/BLMODULES-36)
* Hibernate Criteria Querys using `get` are returning proxies instead of the entity - Resolves [BLMODULES-35](https://ortussolutions.atlassian.net/browse/BLMODULES-35)
* ensure proxies in session are expanded when a load is requested - See [5b07e2c](https://github.com/ortus-boxlang/bx-orm/commit/5b07e2c1f0bf2bb4f3cb3c5fd15f15cee9bfd01d)
* Error on first ORM request after Application Timeout - Resolves [BLMODULES-30](https://ortussolutions.atlassian.net/browse/BLMODULES-30)
* BoxProxy Struct Implementation causes validation exceptions - Resolves [BLMODULES-33](https://ortussolutions.atlassian.net/browse/BLMODULES-33)

See [v1.0.3 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.2...v1.0.3).

## 1.0.2 - 2025-04-04

No significant changes.

See [v1.0.2 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.1...v1.0.2).

## 1.0.1 - 2025-04-04

### ⭐ Added

* Allow options as third arg to ORMExecuteQuery - See [b5efc84](https://github.com/ortus-boxlang/bx-orm/commit/b5efc840df6ddc96e87dd2d18b1bd3acd4de6002)
* Add handling for not null on to-one relationship - See [6792fb0](https://github.com/ortus-boxlang/bx-orm/commit/6792fb0e81a11105ce056803f2b28b873546ec02)

### 🐛 Fixed

* Attempt casting `uniqueOrOrder` to string in EntityLoad BIF - See [98f6734](https://github.com/ortus-boxlang/bx-orm/commit/98f67344e0df0d808f6bb749b4ae20b2cc8c9734)
* Ignore null `uniqueOrOrder` argument in EntityLoad BIF - See [394d9ba](https://github.com/ortus-boxlang/bx-orm/commit/394d9ba907a016103949da5a5d157ffb14672d61)
* Fix chicken/egg issues with app startup by lazy-initializing the EventHandler - See [699f15b](https://github.com/ortus-boxlang/bx-orm/commit/699f15b8c82704f8e101d1d1ee38be541e5ae618)
* WrongClassException when re-querying for the same object in a session - Resolves [BLMODULES-12](https://ortussolutions.atlassian.net/browse/BLMODULES-12)
* Disable `not-null` annotation usage on one-to-one relationships - See [c512848](https://github.com/ortus-boxlang/bx-orm/commit/c512848bba331c6282a5a5c5c2b99271b3f28863)
* fix explicit nulls on setters - See [819fffb](https://github.com/ortus-boxlang/bx-orm/commit/819fffbe58fb576e630f29d001aec5a38d8bf1b4)
* Auto-generated `has` methods are overriding declared methods in ORM entities - Resolves [BLMODULES-31](https://ortussolutions.atlassian.net/browse/BLMODULES-31)
* `x-to-one` generated `hasX()` methods are not returning the correct values - Resolves [BLMODULES-32](https://ortussolutions.atlassian.net/browse/BLMODULES-32)

See [v1.0.1 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/v1.0.0...v1.0.1).

## 1.0.0 - 2025-03-26

* First iteration of this module

See [v1.0.0 commit history on github](https://github.com/ortus-boxlang/bx-orm/compare/2fe797c6330a5d110f3bfbc5ead058df9bdbe89e...v1.0.0)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bxorm.ortusbooks.com/release-history/1x.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.