Configuration property to work with database schemas generated for Hibernate ORM 5.6

[yrodiere]

Description

Hibernate ORM 6 changes a few defaults regarding database schemas, and that could be a problem for pre-existing applications that migrate to Quarkus 3 + ORM 6.

We need to add a unique, per-PU property that would switch several configuration properties to their "legacy" value so that Hibernate ORM 6 continues to work with those "legacy" database schemas.

Ideally, those configuration properties should be overrideable through quarkus.hibernate-orm.unsupported-properties, so that people can iterate when migrating.

The exact list of properties set by that will be automatically overridden needs to be documented somewhere; though I believe a link to the source would be enough, if the source is a single class that is focused only on this overriding and isn't overly complex.

Implementation ideas

E.g.:

quarkus.hibernate-orm.schema.compatibility = 5.6

Limitations

For now, we will have a global property for all persistence units but that seems like an acceptable limitation.

This compatibility property is specifically about the database schema. It doesn't improve the compatibility for annotations and API changes.

List of compatibility issues

• Sequences: - we need to set it to legacy to use hibernate_sequence by default
• Duration mapping changes
• UUID mapping changes: AND mariadb AND sql-server
• Instant mapping changes
• Basic array/collection mapping: we are still undecided of if we want to do something here. It is not high priority: people can annotate their properties to work around the problem and it should not be very common
• Enum mapping changes - Christian said it should be backward compatible
• Datatype for enums: Christian said it should be backward compatible
• Timezone and offset storage: Apparently not much to do here but might require some clarifications
• Automatic mapping of configured deprecated Hibernate ORM Dialects to the ORM 6 dialect + version #31588

[quarkus-bot]

/cc @Sanne (hibernate-orm), @gsmet (hibernate-orm)

[Sanne]

+1 for the idea, but let's not call it 'quarkus.hibernate-orm.schema.compatibility' as that sets expectations we can't promise.

Regarding the sequence naming approach, for example, there already is a property; we should highlight these in a migration guide. cc/ @beikov

[gsmet]

We had a discussion with Christian and Yoann this morning to discuss all the various schema issues. There are many different quirks and we don't want to support the combination of all of them set to different values. We want to allow users to say "I don't want to update my schema now, please have a best effort approach to support my 5.6 schema".
Thus why we are leaning towards a single property that makes decisions of what we actually decided that could be safe.

As for the name, feel free to suggest a different name for the property but we need to move fast as I want this in before pushing Alpha5.

[Sanne]

What if we simply document which properties they are so that people can use the "unsupported properties" , which makes it clear they are unsupported and best effort.

We also don't want to encourage use of such properties, as the mapping in 6 is arguably better and these capabilities won't be around forever.

[maxandersen]

+1 on the idea, but I don't think having this completely done should stop us from doing Alpha5 IMO. It is and was known there would be breaking changes and we can make it very clear that Alpha5 introduces hibernate 6 and thus is changing the defaults and state we are working on a flag to make migration easier. Many things in alpha5 beyond hibernate 6 to try and those wanting to migrate to hibernate 6 the earlier we can let them the more real feedback we get.

I would much rather have that problem during alphaX's than CR's.