hibernate-orm/migration-guide.adoc

= 6.3 Migration Guide
:toc:
:toclevels: 4
:docsBase: https://docs.jboss.org/hibernate/orm
:versionDocBase: {docsBase}/6.3
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
:javadocsBase: {versionDocBase}/javadocs


This guide discusses migration to Hibernate ORM version 6.3. For migration from
earlier versions, see any other pertinent migration guides as well.

* link:{docsBase}/6.2/migration-guide/migration-guide.html[6.2 Migration guide]
* link:{docsBase}/6.1/migration-guide/migration-guide.html[6.1 Migration guide]
* link:{docsBase}/6.0/migration-guide/migration-guide.html[6.0 Migration guide]

[[hql-numeric-literal-types]]
== HQL Numeric Literal Types

Version 3.2 of the Jakarta Persistence specification
https://github.com/jakartaee/persistence/issues/423[clarifies] the interpretation of
numeric literals with regard to type, explicitly aligning with the Java specification (as well
as adopting Hibernate's long-standing `BigInteger` and `BigDecimal` suffixes).
HQL and JPQL are domain/object-level queries, so that makes perfect sense.

* `Integer` - 123
* `Long` - 123l, 123L
* `BigInteger` - 123bi, 123BI
* `Double` - 123.4
* `Float` - 123.4f, 123.4F
* `BigDecimal` - 123.4bd, 123.4BD

Hibernate 6.3 aligns with those interpretations, which may lead to different behavior
from prior versions.


[[batch-fetching-changes]]
== Batch Fetching and LockMode

When LockMode is greater than READ Hibernate does not execute the batch fetching so existing uninitialized proxies will not be initialized.
This because the lock mode is different from the one of the proxies in the batch fetch queue.

E.g.

```java
MyEntity proxy = session.getReference( MyEntity.class, 1 );
MyEntity myEntity = session.find(MyEntity.class, 2, LockMode.WRITE);
```

only the entity with id equals to 2 will be loaded but the proxy will not be initialized.

[[metamodel-generation]]
== Integrating Static Metamodel Generation

The integration of static metamodel generation in a project has changed; the recommended way to do this now is by harnessing the annotation processor classpath. This is true for both Gradle and Maven.

Some projects currently integrate with `hibernate-jpamodelgen` with a dependency, like so:

[source,xml]
----
    <dependencies>
        <!-- ... -->
        <!-- THIS IS WRONG! See below -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-jpamodelgen</artifactId>
            <scope>provided</scope>
            <version>6.3.1</version> <!-- Optional, may be managed by a BOM -->
        </dependency>
        <!-- ... -->
    </dependencies>
----

If you are in that case, in previous versions of Hibernate ORM you were leaking dependencies of `hibernate-jpamodelgen` into your compile classpath unknowingly.
With Hibernate ORM 6.3, you may now experience a compilation error during annotation processing related to missing Antlr classes.
To get rid of that error:

1. Check out the specific sections in the User Guide for a guideline on how to properly harness the annotation processor classpath to use `hibernate-jpamodelgen`:
   see {userGuideBase}#tooling-gradle-modelgen[here for Gradle] or {userGuideBase}#tooling-maven-modelgen[here for Maven].
2. If the annotation processor classpath doesn't work in your case (e.g. because you use Maven and need the version of `hibernate-jpamodelgen` managed through a BOM),
   upgrade to a newer version of Hibernate ORM that fixes https://hibernate.atlassian.net/browse/HHH-17362[HHH-17362].

[[hql-null-literal-comparison]]
== HQL null literal comparison

In prior versions of Hibernate it was possible to compare expressions against a `null` literal with the `=` and `<>`/`!=`
operators. This is counter-intuitive as the comparison against a parameter or expression that resolves to a `null` would
always yield `false` i.e. no results.

As of Hibernate ORM 6.3, this special treatment in HQL was removed without a way to retain backwards compatibility.
Users should migrate queries to use the `is null` and `is not null` predicate syntax instead.