Merge pull request #31701 from yrodiere/i31474-db-min-version

Fix deprecation warnings related to ORM dialects and add `quarkus.datasource.db-version` as a dialect version hint

Author: yrodiere

bom/application/pom.xml

@@ -126,7 +126,7 @@
         <httpasync.version>4.1.5</httpasync.version>
         <cronutils.version>9.2.0</cronutils.version>
         <quartz.version>2.3.2</quartz.version>
-        <h2.version>2.1.214</h2.version> <!-- When updating, needs to be matched in io.quarkus.hibernate.orm.runtime.dialect.QuarkusH2Dialect -->
+        <h2.version>2.1.214</h2.version> <!-- When updating, needs to be matched in io.quarkus.hibernate.orm.runtime.config.DialectVersions -->
         <postgresql-jdbc.version>42.5.4</postgresql-jdbc.version>
         <mariadb-jdbc.version>3.1.2</mariadb-jdbc.version>
         <mysql-jdbc.version>8.0.30</mysql-jdbc.version>

docs/src/main/asciidoc/hibernate-orm.adoc

@@ -102,7 +102,8 @@ For a list of the items that you can set in `{config-file}`, see xref:hibernate-
 
 An `EntityManagerFactory` will be created based on the Quarkus `datasource` configuration as long as the Hibernate ORM extension is listed among your project dependencies.
 
-Unless you set one explicitly, the dialect will be selected based on the JDBC driver.
+The dialect will be selected and configured automatically based on your datasource;
+you may want to <<hibernate-dialect,configure it to more precisely match your database>>.
 
 You can then happily inject your `EntityManager`:
 
@@ -165,6 +166,93 @@ WARNING: Make sure to wrap methods modifying your database (e.g. `entity.persist
 CDI bean method `@Transactional` will do that for you and make that method a transaction boundary. We recommend doing
 so at your application entry point boundaries like your REST endpoint controllers.
 
+[[hibernate-dialect]]
+=== Dialect
+
+[[hibernate-dialect-supported-databases]]
+==== Supported databases
+
+For xref:datasource.adoc#default-datasource[supported databases],
+the link:{orm-doc-url-prefix}##database-dialect[Hibernate ORM dialect]
+does not need to be set explicitly:
+it is selected automatically based on the datasource.
+
+By default, the dialect is configured to target the minimum supported version of the database.
+
+In order for Hibernate ORM to generate more efficient SQL,
+to avoid workarounds and to take advantage of more database features,
+you can set the database version explicitly:
+
+[source,properties]
+.`{config-file}` with an explicit `db-version`
+----
+quarkus.datasource.db-kind = postgresql
+quarkus.datasource.db-version = 14.0 <1>
+quarkus.datasource.username = hibernate
+quarkus.datasource.password = hibernate
+quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/hibernate_db
+----
+<1> Set the database version. The Hibernate ORM dialect will target that version.
+
+As a rule, the version set here should be as high as possible,
+but must be lower than or equal to the version of any database your application will connect to.
+
+[NOTE]
+====
+When a version is set explicitly,
+Quarkus will try to check this version against the actual database version on startup,
+leading to a startup failure when the actual version is lower.
+
+This is because Hibernate ORM may generate SQL that is invalid
+for versions of the database older than what is configured,
+which would lead to runtime exceptions.
+
+If the database cannot be reached, a warning will be logged but startup will proceed.
+====
+
+[[hibernate-dialect-other-databases]]
+==== Other databases
+
+If xref:datasource.adoc#other-databases[your database does not have a corresponding Quarkus extension],
+or if the defaults do not match your needs for some reason,
+you will need to set the link:{orm-doc-url-prefix}##database-dialect[Hibernate ORM dialect] explicitly:
+
+[source,properties]
+.`{config-file}` with an explicit `dialect`
+----
+quarkus.datasource.db-kind = postgresql
+quarkus.datasource.username = hibernate
+quarkus.datasource.password = hibernate
+quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:26257/hibernate_db
+
+quarkus.hibernate-orm.dialect=org.hibernate.dialect.CockroachDialect <1>
+----
+<1> Set the Hibernate ORM dialect.
+
+[WARNING]
+====
+In that case, keep in mind that the JDBC driver or Hibernate ORM dialect
+may not work properly in GraalVM native executables.
+====
+
+As with <<hibernate-dialect-supported-databases,supported databases>>,
+you can configure the DB version explicitly to get the most out of Hibernate ORM:
+
+[source,properties]
+.`{config-file}` with an explicit `dialect` and `db-version`
+----
+quarkus.datasource.db-kind = postgresql
+quarkus.datasource.db-version = 22.2 <1>
+quarkus.datasource.username = hibernate
+quarkus.datasource.password = hibernate
+quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:26257/hibernate_db
+
+quarkus.hibernate-orm.dialect=org.hibernate.dialect.CockroachDialect <2>
+----
+<1> Set the database version. The Hibernate ORM dialect will target that version.
+Since we're targeting CockroachDB here, we're passing the CockroachDB version, not the PostgreSQL version.
+<2> Set the Hibernate ORM dialect.
+
 [[hibernate-configuration-properties]]
 === Hibernate ORM configuration properties
 
@@ -417,7 +505,7 @@ difference is that you would specify your Hibernate ORM configuration in `META-I
 
         <properties>
             <!-- Connection specific -->
-            <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQL95Dialect"/>
+            <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>
 
             <property name="hibernate.show_sql" value="true"/>
             <property name="hibernate.format_sql" value="true"/>

extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/AgroalProcessor.java

@@ -186,6 +186,7 @@ private DataSourceSupport getDataSourceSupport(
             String dataSourceName = aggregatedDataSourceBuildTimeConfig.getName();
             dataSourceSupportEntries.put(dataSourceName,
                     new DataSourceSupport.Entry(dataSourceName, aggregatedDataSourceBuildTimeConfig.getDbKind(),
+                            aggregatedDataSourceBuildTimeConfig.getDataSourceConfig().dbVersion,
                             aggregatedDataSourceBuildTimeConfig.getResolvedDriverClass(),
                             aggregatedDataSourceBuildTimeConfig.isDefault()));
         }
@@ -274,6 +275,7 @@ void generateDataSourceBeans(AgroalRecorder recorder,
 
             jdbcDataSource.produce(new JdbcDataSourceBuildItem(dataSourceName,
                     entry.getValue().resolvedDbKind,
+                    entry.getValue().dbVersion,
                     entry.getValue().isDefault));
         }
     }

extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSourceSupport.java

@@ -1,6 +1,7 @@
 package io.quarkus.agroal.runtime;
 
 import java.util.Map;
+import java.util.Optional;
 
 public class DataSourceSupport {
 
@@ -17,13 +18,16 @@ public DataSourceSupport(boolean disableSslSupport, boolean mpMetricsPresent, Ma
     public static class Entry {
         public final String dataSourceName;
         public final String resolvedDbKind;
+        public final Optional<String> dbVersion;
         public final String resolvedDriverClass;
         public final boolean isDefault;
 
-        public Entry(String dataSourceName, String resolvedDbKind, String resolvedDriverClass,
+        public Entry(String dataSourceName, String resolvedDbKind, Optional<String> dbVersion,
+                String resolvedDriverClass,
                 boolean isDefault) {
             this.dataSourceName = dataSourceName;
             this.resolvedDbKind = resolvedDbKind;
+            this.dbVersion = dbVersion;
             this.resolvedDriverClass = resolvedDriverClass;
             this.isDefault = isDefault;
         }

extensions/agroal/spi/src/main/java/io/quarkus/agroal/spi/JdbcDataSourceBuildItem.java

@@ -1,5 +1,7 @@
 package io.quarkus.agroal.spi;
 
+import java.util.Optional;
+
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
@@ -14,11 +16,13 @@ public final class JdbcDataSourceBuildItem extends MultiBuildItem {
 
     private final String dbKind;
 
+    private final Optional<String> dbVersion;
     private final boolean isDefault;
 
-    public JdbcDataSourceBuildItem(String name, String kind, boolean isDefault) {
+    public JdbcDataSourceBuildItem(String name, String kind, Optional<String> dbVersion, boolean isDefault) {
         this.name = name;
         this.dbKind = kind;
+        this.dbVersion = dbVersion;
         this.isDefault = isDefault;
     }
 
@@ -30,6 +34,10 @@ public String getDbKind() {
         return dbKind;
     }
 
+    public Optional<String> getDbVersion() {
+        return dbVersion;
+    }
+
     public boolean isDefault() {
         return isDefault;
     }

extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceBuildTimeConfig.java

@@ -16,6 +16,38 @@ public class DataSourceBuildTimeConfig {
     @ConvertWith(DatabaseKindConverter.class)
     public Optional<String> dbKind = Optional.empty();
 
+    /**
+     * The version of the database we will connect to (e.g. '10.0').
+     *
+     * CAUTION: The version number set here should follow the same numbering scheme
+     * as the string returned by `java.sql.DatabaseMetaData#getDatabaseProductVersion()`
+     * for your database's JDBC driver.
+     * This numbering scheme may be different from the most popular one for your database;
+     * for example Microsoft SQL Server 2016 would be version `13`.
+     *
+     * As a rule, the version set here should be as high as possible,
+     * but must be lower than or equal to the version of any database your application will connect to.
+     *
+     * A high version will allow better performance and using more features
+     * (e.g. Hibernate ORM may generate more efficient SQL,
+     * avoid workarounds and take advantage of more database features),
+     * but if it is higher than the version of the database you want to connect to,
+     * it may lead to runtime exceptions
+     * (e.g. Hibernate ORM may generate invalid SQL that your database will reject).
+     *
+     * Some extensions (like the Hibernate ORM extension)
+     * will try to check this version against the actual database version on startup,
+     * leading to a startup failure when the actual version is lower
+     * or simply a warning in case the database cannot be reached.
+     *
+     * The default for this property is specific to each extension;
+     * the Hibernate ORM extension will default to the oldest version it supports.
+     *
+     * @asciidoclet
+     */
+    @ConfigItem
+    public Optional<String> dbVersion = Optional.empty();
+
     /**
      * Configuration for DevServices. DevServices allows Quarkus to automatically start a database in dev and test mode.
      */

extensions/hibernate-orm/deployment-spi/src/main/java/io/quarkus/hibernate/orm/deployment/spi/DatabaseKindDialectBuildItem.java

@@ -1,5 +1,7 @@
 package io.quarkus.hibernate.orm.deployment.spi;
 
+import java.util.Optional;
+
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
@@ -8,10 +10,33 @@
 public final class DatabaseKindDialectBuildItem extends MultiBuildItem {
     private final String dbKind;
     private final String dialect;
+    private final Optional<String> defaultDatabaseProductVersion;
 
+    /**
+     * @param dbKind The DB Kind set through {@code quarkus.datasource.db-kind}
+     * @param dialect The corresponding dialect to set in Hibernate ORM.
+     */
     public DatabaseKindDialectBuildItem(String dbKind, String dialect) {
+        this(dbKind, dialect, Optional.empty());
+    }
+
+    /**
+     * @param dbKind The DB Kind set through {@code quarkus.datasource.db-kind}
+     * @param dialect The corresponding dialect to set in Hibernate ORM.
+     *        See {@code org.hibernate.dialect.Database} for information on how this name is resolved to a dialect.
+     * @param defaultDatabaseProductVersion The default database-product-version to set in Hibernate ORM.
+     *        This is useful when the default version of the dialect in Hibernate ORM
+     *        is lower than what we expect in Quarkus.
+     */
+    public DatabaseKindDialectBuildItem(String dbKind, String dialect, String defaultDatabaseProductVersion) {
+        this(dbKind, dialect, Optional.of(defaultDatabaseProductVersion));
+    }
+
+    private DatabaseKindDialectBuildItem(String dbKind, String dialect,
+            Optional<String> defaultDatabaseProductVersion) {
         this.dbKind = dbKind;
         this.dialect = dialect;
+        this.defaultDatabaseProductVersion = defaultDatabaseProductVersion;
     }
 
     public String getDbKind() {
@@ -21,4 +46,8 @@ public String getDbKind() {
     public String getDialect() {
         return dialect;
     }
+
+    public Optional<String> getDefaultDatabaseProductVersion() {
+        return defaultDatabaseProductVersion;
+    }
 }

extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/Dialects.java

@@ -282,22 +282,29 @@ public boolean isAnyPropertySet() {
     public static class HibernateOrmConfigPersistenceUnitDialect {
 
         /**
-         * Class name of the Hibernate ORM dialect. The complete list of bundled dialects is available in the
+         * Class name of the Hibernate ORM dialect.
+         *
+         * The complete list of bundled dialects is available in the
          * https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/dialect/package-summary.html[Hibernate ORM
          * JavaDoc].
          *
-         * [NOTE]
-         * ====
-         * Not all the dialects are supported in GraalVM native executables: we currently provide driver extensions for
-         * PostgreSQL,
-         * MariaDB, Microsoft SQL Server and H2.
-         * ====
+         * Setting the dialect directly is only recommended as a last resort:
+         * most popular databases have a corresponding Quarkus extension,
+         * allowing Quarkus to select the dialect automatically,
+         * in which case you do not need to set the dialect at all,
+         * though you may want to set
+         * xref:datasource.adoc#quarkus-datasource_quarkus.datasource.db-version[`quarkus.datasource.db-version`] as
+         * high as possible
+         * to benefit from the best performance and latest features.
+         *
+         * If your database does not have a corresponding Quarkus extension,
+         * you will need to set the dialect directly.
+         * In that case, keep in mind that the JDBC driver and Hibernate ORM dialect
+         * may not work properly in GraalVM native executables.
          *
          * @asciidoclet
          */
-        // TODO should it be dialects
-        //TODO should it be shortcuts like "postgresql" "h2" etc
-        @ConfigItem(name = ConfigItem.PARENT)
+        @ConfigItem(name = ConfigItem.PARENT, defaultValueDocumentation = "selected automatically for most popular databases")
         @ConvertWith(TrimmedStringConverter.class)
         public Optional<String> dialect;