= 5.3 Migration Guide
:toc:

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

== Background

5.3 represents a JPA 2.2 compatible version on top of 5.2


== Known changes

=== Changes to positional query parameter handling

This really breaks down into 2 related changes:

* Support for JDBC-style parameter declarations in HQL/JPQL queries has been removed.  This feature
    has been deprecated since 4.1 and removing it made implementing the second change, so we decided
    to remove that support.  JDBC-style parameter declaration is still supported in native-queries.
* Since JPA positional parameters really behave more like named parameters (they can be repeated,
    declared in any order, etc.) Hibernate used to treat them as named parameters - it relied on
    Hibernate's JPA wrapper to interpret the JPA setParameter calls and properly handle delegating to
    the named variant.  This is actually a regression in 5.2 as it causes
    `javax.persistence.Parameter#getPosition` to report `null`.

For JDBC-style parameter declarations in native queries, we have also moved to using one-based
instead of zero-bade parameter binding to be consistent with JPA.  That can temporarily be
reverted by setting the `hibernate.query.sql.jdbc_style_params_base` setting to `true` which
reverts to expecting zero-based binding.


=== Change in the `@TableGenerator` stored value

In order to be compliant with the JPA specification, the sequence value stored by Hibernate 5.3 in the database table used by the `javax.persistence.TableGenerator`
is the *last* generated value. Previously, Hibernate stored the *next* sequence value.

For backward compatibility, a new setting called `hibernate.id.generator.stored_last_used` was introduced, which gives you the opportunity to fall back to the old Hibernate behavior.

[NOTE]
====
Existing applications migrating to 5.3 and using the `@TableGenerator` have to set the `hibernate.id.generator.stored_last_used` configuration property to `false`.
====

=== Change in the `@TableGenerator` and `@SequenceGenerator` name scope

In order to be compliant with the JPA specification, generators names are now considered global (e.g. https://hibernate.atlassian.net/browse/HHH-12157[HHH-12157]) .
Configuring two generators, even if with different types but with the same name will now cause a `java.lang.IllegalArgumentException' to be thrown at boot time.

For example, the following mappings are no longer valid:

[source,java]
----
@Entity
@TableGenerator(name = "ID_GENERATOR", ... )
public class FirstEntity {
    ....
}

@Entity
@TableGenerator(name = "ID_GENERATOR", ... )
public class SecondEntity {
    ....
}
----

or

[source,java]
----
@Entity
@TableGenerator(name = "ID_GENERATOR", ... )
public class FirstEntity {
    ....
}

@Entity
@SequenceGenerator(name="ID_GENERATOR", ... )
public class SecondEntity {
    ....
}
----

The solution is to make all generators unique so that there are no two generators with the same name.


=== Drop hibernate-infinispan module

Support for using Infinispan as a Hibernate 2nd-level cache provider has been moved to the Infinispan project so
the `hibernate-infinispan` module has been dropped.

A relocation pom which is pointing to `org.infinispan:infinispan-hibernate-cache` dependency is still generated,
therefore, avoiding the need of updating any library dependency.

[WARN]
====
The relocation pom may be dropped in a future release.
====