hibernate-orm/migration-guide.adoc

= 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


== 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 JPA specifications, the value stored by Hibernate 5.3 in the Table used by the `javax.persistence.TableGenerator` is the last value generated.
Previous versions of Hibernate instead stored the next value to be used.

For backward compatibility a new setting, `hibernate.id.generator.stored_last_used`, has been introduced that gives the opportunity to fall back to the old Hibernate behaviour.
Existing applications migrating to 5.3 and using @TableGenerator have to set `hibernate.id.generator.stored_last_used` to `false`.