Offline startup mode and dialect configuration for Hibernate ORM and Hibernate Reactive quarkusio#48130

Added a `quarkus.hibernate-orm.database.start-offline` to avoid connecting to the database

* Disable schema validation
* Disable temporary table creation at startup, gives precedence to local temporary tables using Hibernate 7.1 local mutation strategies
* Disable schema management in offline mode for DevServices as well

New way to handle storage engine from both mysql and mariadb

Added tests for specific override of Dialect Settings

Removed unused hack MultiplePersistenceUnitsInconsistentStorageEnginesTest$H2DialectWithMySQLInTheName

Included initial draft by Steve Ebersole <[email protected]> quarkusio#43396

Co-authored-by: Steve Ebersole <[email protected]>
Co-authored-by: Yoann Rodière <[email protected]>

Author: 3 people

docs/src/main/asciidoc/_attributes.adoc

@@ -54,6 +54,7 @@
 :quickstarts-tree-url: ${quickstarts-base-url}/tree/main
 // .
 :hibernate-orm-docs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/userguide/html_single/Hibernate_User_Guide.html
+:hibernate-orm-javadocs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/javadocs/
 :hibernate-orm-dialect-docs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/dialect/dialect.html
 :hibernate-search-docs-url: https://docs.jboss.org/hibernate/search/{hibernate-search-version-major-minor}/reference/en-US/html_single/
 :hibernate-validator-docs-url: https://docs.jboss.org/hibernate/validator/{hibernate-validator-version-major-minor}/reference/en-US/html_single/

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

@@ -864,6 +864,46 @@ link in the Flyway pane. Hit the `Create Initial Migration` button and the follo
 WARNING: This button is simply a convenience to quickly get you started with Flyway, it is up to you to determine how you want to
 manage your database schemas in production. In particular the `migrate-at-start` setting may not be right for all environments.
 
+[[offline]]
+== Offline startup
+
+By default, Hibernate attempts to connect to the database at startup to fetch metadata. This is useful for example to validate the schema or create some temporary tables, making the startup process smoother and more user-friendly.
+
+However, in certain environments, such as when running a Quarkus application in a container within a Kubernetes
+cluster, this connection might not be possible. For example, if the application runs in one pod and the database
+in another, the database may not be reachable at startup time.
+To address this, Quarkus provides an _offline startup_ mode, which allows Hibernate to skip connecting to the database
+during application startup.
+
+When using offline startup, it's important to ensure that the database schema has already been created correctly before
+the application starts.
+
+You can rely on xref:flyway.adoc[Flyway] or custom setups to create/migrate your database schema,
+though obviously at a time where the database _is_ accessible --
+Flyway's `migrate-at-start` option in particular will just fail at application startup
+if the database is not reachable.
+
+To enable offline startup, set the following configuration property:
+
+[source,properties]
+.application.properties
+----
+quarkus.hibernate-orm.database.start-offline=true
+----
+
+
+You can also fine-tune dialect behavior for specific databases using additional properties, such as:
+
+[source,properties]
+.application.properties
+----
+quarkus.hibernate-orm."offline".dialect.mariadb.bytes-per-character=1
+quarkus.hibernate-orm."offline".dialect.mariadb.no-backslash-escapes=true
+----
+
+Refer to the <<hibernate-configuration-properties,Hibernate ORM configuration properties>> section for more details on the available properties.
+
+
 [[caching]]
 == Caching
 

extensions/datasource/common/src/main/java/io/quarkus/datasource/common/runtime/DatabaseKind.java

@@ -6,6 +6,7 @@
 import java.util.HashSet;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Set;
 
 /**
@@ -97,7 +98,7 @@ public static boolean is(String value, String mainName) {
     private DatabaseKind() {
     }
 
-    private enum SupportedDatabaseKind {
+    public enum SupportedDatabaseKind {
         DB2(DatabaseKind.DB2),
         DERBY(DatabaseKind.DERBY),
         H2(DatabaseKind.H2),
@@ -110,16 +111,30 @@ private enum SupportedDatabaseKind {
         private final String mainName;
         private final Set<String> aliases;
 
-        private SupportedDatabaseKind(String mainName) {
+        SupportedDatabaseKind(String mainName) {
             this.mainName = mainName;
             this.aliases = Collections.singleton(mainName);
         }
 
-        private SupportedDatabaseKind(String mainName, String... aliases) {
+        SupportedDatabaseKind(String mainName, String... aliases) {
             this.mainName = mainName;
             this.aliases = new HashSet<>();
             this.aliases.add(mainName);
             this.aliases.addAll(Arrays.asList(aliases));
         }
+
+        public String getMainName() {
+            return mainName;
+        }
+
+        public static Optional<SupportedDatabaseKind> from(String name) {
+            String normalizedName = normalize(name);
+            for (SupportedDatabaseKind kind : values()) {
+                if (kind.getMainName().equals(normalizedName)) {
+                    return Optional.of(kind);
+                }
+            }
+            return Optional.empty();
+        }
     }
 }

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

@@ -304,12 +304,41 @@ interface HibernateOrmConfigPersistenceUnitDialect {
          *
          * E.g. `MyISAM` or `InnoDB` for MySQL.
          *
+         * @deprecated Use {@code mysql.}{@linkplain MySQLDialectConfig#storageEngine storage-engine}
+         *             or {@code mariadb.}{@linkplain MySQLDialectConfig#storageEngine storage-engine} instead
+         *
          * @asciidoclet
          */
-        Optional<@WithConverter(TrimmedStringConverter.class) String> storageEngine();
+        @WithConverter(TrimmedStringConverter.class)
+        @Deprecated
+        Optional<String> storageEngine();
+
+        /**
+         * Configuration specific to Hibernate's Dialect for MariaDB
+         */
+        MySQLDialectConfig mariadb();
+
+        /**
+         * Configuration specific to Hibernate's Dialect for MySQL
+         */
+        MySQLDialectConfig mysql();
+
+        /**
+         * Configuration specific to Hibernate's Dialect for Oracle
+         */
+        OracleDialectConfig oracle();
+
+        /**
+         * Configuration specific to Hibernate's Dialect for Microsoft SQLServer
+         */
+        SqlServerDialectConfig mssql();
 
         default boolean isAnyPropertySet() {
-            return dialect().isPresent() || storageEngine().isPresent();
+            return dialect().isPresent() || storageEngine().isPresent()
+                    || mysql().isAnyPropertySet()
+                    || oracle().isAnyPropertySet()
+                    || mssql().isAnyPropertySet()
+                    || mariadb().isAnyPropertySet();
         }
     }
 

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

@@ -340,6 +340,7 @@ public void configurationDescriptorBuilding(
                             new RecordedConfig(
                                     Optional.of(DataSourceUtil.DEFAULT_DATASOURCE_NAME),
                                     jdbcDataSource.map(JdbcDataSourceBuildItem::getDbKind),
+                                    Optional.empty(),
                                     jdbcDataSource.flatMap(JdbcDataSourceBuildItem::getDbVersion),
                                     Optional.ofNullable(xmlDescriptor.getProperties().getProperty(AvailableSettings.DIALECT)),
                                     getMultiTenancyStrategy(
@@ -950,7 +951,8 @@ private static void producePersistenceUnitDescriptorFromConfig(
 
         MultiTenancyStrategy multiTenancyStrategy = getMultiTenancyStrategy(persistenceUnitConfig.multitenant());
 
-        collectDialectConfig(persistenceUnitName, persistenceUnitConfig,
+        Optional<DatabaseKind.SupportedDatabaseKind> supportedDatabaseKind = collectDialectConfig(persistenceUnitName,
+                persistenceUnitConfig,
                 dbKindMetadataBuildItems, jdbcDataSource, multiTenancyStrategy,
                 systemProperties, reflectiveMethods, descriptor.getProperties()::setProperty, storageEngineCollector);
 
@@ -972,6 +974,7 @@ private static void producePersistenceUnitDescriptorFromConfig(
                         new RecordedConfig(
                                 jdbcDataSource.map(JdbcDataSourceBuildItem::getName),
                                 jdbcDataSource.map(JdbcDataSourceBuildItem::getDbKind),
+                                supportedDatabaseKind.map(DatabaseKind.SupportedDatabaseKind::getMainName),
                                 jdbcDataSource.flatMap(JdbcDataSourceBuildItem::getDbVersion),
                                 persistenceUnitConfig.dialect().dialect(),
                                 multiTenancyStrategy,
@@ -985,7 +988,7 @@ private static void producePersistenceUnitDescriptorFromConfig(
                         isHibernateValidatorPresent(capabilities), jsonMapper, xmlMapper));
     }
 
-    private static void collectDialectConfig(String persistenceUnitName,
+    private static Optional<DatabaseKind.SupportedDatabaseKind> collectDialectConfig(String persistenceUnitName,
             HibernateOrmConfigPersistenceUnit persistenceUnitConfig,
             List<DatabaseKindDialectBuildItem> dbKindMetadataBuildItems,
             Optional<JdbcDataSourceBuildItem> jdbcDataSource,
@@ -994,7 +997,10 @@ private static void collectDialectConfig(String persistenceUnitName,
             BuildProducer<ReflectiveMethodBuildItem> reflectiveMethods,
             BiConsumer<String, String> puPropertiesCollector,
             Set<String> storageEngineCollector) {
-        Optional<String> dialect = persistenceUnitConfig.dialect().dialect();
+        final HibernateOrmConfigPersistenceUnit.HibernateOrmConfigPersistenceUnitDialect dialectConfig = persistenceUnitConfig
+                .dialect();
+
+        Optional<String> dialect = dialectConfig.dialect();
         Optional<String> dbKind = jdbcDataSource.map(JdbcDataSourceBuildItem::getDbKind);
         Optional<String> explicitDbMinVersion = jdbcDataSource.flatMap(JdbcDataSourceBuildItem::getDbVersion);
         if (multiTenancyStrategy != MultiTenancyStrategy.DATABASE && jdbcDataSource.isEmpty()) {
@@ -1007,11 +1013,12 @@ private static void collectDialectConfig(String persistenceUnitName,
                             "quarkus.datasource.password", "quarkus.datasource.jdbc.url")));
         }
 
-        setDialectAndStorageEngine(
+        Optional<DatabaseKind.SupportedDatabaseKind> supportedDatabaseKind = setDialectAndStorageEngine(
                 persistenceUnitName,
                 dbKind,
                 dialect,
                 explicitDbMinVersion,
+                dialectConfig,
                 dbKindMetadataBuildItems,
                 persistenceUnitConfig.dialect().storageEngine(),
                 systemProperties,
@@ -1025,6 +1032,8 @@ private static void collectDialectConfig(String persistenceUnitName,
                     "Accessed in org.hibernate.engine.jdbc.env.internal.DefaultSchemaNameResolver.determineAppropriateResolverDelegate",
                     true, "org.postgresql.jdbc.PgConnection", "getSchema"));
         }
+
+        return supportedDatabaseKind;
     }
 
     private static void collectDialectConfigForPersistenceXml(String persistenceUnitName,

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

@@ -0,0 +1,46 @@
+package io.quarkus.hibernate.orm.deployment;
+
+import java.util.Optional;
+
+import io.quarkus.runtime.annotations.ConfigDocDefault;
+import io.quarkus.runtime.annotations.ConfigGroup;
+import io.quarkus.runtime.configuration.TrimmedStringConverter;
+import io.smallrye.config.WithConverter;
+
+/**
+ * Configuration specific to the Hibernate ORM {@linkplain org.hibernate.dialect.MySQLDialect},
+ * though may also affect other dialects such as {@linkplain org.hibernate.dialect.MariaDBDialect}.
+ *
+ * @author Steve Ebersole
+ */
+@ConfigGroup
+public interface MySQLDialectConfig {
+    /**
+     * Specifies the bytes per character to use based on the database's configured
+     * <a href="https://dev.mysql.com/doc/refman/8.0/en/charset-charsets.html">charset</a>.
+     *
+     * @see org.hibernate.cfg.DialectSpecificSettings#MYSQL_BYTES_PER_CHARACTER
+     */
+    @ConfigDocDefault("4")
+    Optional<Integer> bytesPerCharacter();
+
+    /**
+     * Specifies whether the {@code NO_BACKSLASH_ESCAPES} sql mode is enabled.
+     *
+     * @see org.hibernate.cfg.DialectSpecificSettings#MYSQL_NO_BACKSLASH_ESCAPES
+     */
+    @ConfigDocDefault("false")
+    Optional<Boolean> noBackslashEscapes();
+
+    /**
+     * The storage engine to use.
+     */
+    @WithConverter(TrimmedStringConverter.class)
+    Optional<String> storageEngine();
+
+    default boolean isAnyPropertySet() {
+        return bytesPerCharacter().isPresent()
+                || noBackslashEscapes().isPresent()
+                || storageEngine().isPresent();
+    }
+}

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

@@ -0,0 +1,45 @@
+package io.quarkus.hibernate.orm.deployment;
+
+import java.util.Optional;
+
+import io.quarkus.runtime.annotations.ConfigDocDefault;
+import io.quarkus.runtime.annotations.ConfigGroup;
+
+/**
+ * Configuration specific to the Hibernate ORM {@linkplain org.hibernate.dialect.OracleDialect}
+ *
+ * @author Steve Ebersole
+ */
+@ConfigGroup
+public interface OracleDialectConfig {
+
+    /**
+     * Support for Oracle's MAX_STRING_SIZE = EXTENDED.
+     *
+     * @see org.hibernate.cfg.DialectSpecificSettings#ORACLE_EXTENDED_STRING_SIZE
+     */
+    @ConfigDocDefault("false")
+    Optional<Boolean> extended();
+
+    /**
+     * Specifies whether this database is running on an Autonomous Database Cloud Service.
+     *
+     * @see org.hibernate.cfg.DialectSpecificSettings#ORACLE_AUTONOMOUS_DATABASE
+     */
+    @ConfigDocDefault("false")
+    Optional<Boolean> autonomous();
+
+    /**
+     * Specifies whether this database is accessed using a database service protected by Application Continuity.
+     *
+     * @see org.hibernate.cfg.DialectSpecificSettings#ORACLE_APPLICATION_CONTINUITY
+     */
+    @ConfigDocDefault("false")
+    Optional<Boolean> applicationContinuity();
+
+    default boolean isAnyPropertySet() {
+        return extended().isPresent()
+                || autonomous().isPresent()
+                || applicationContinuity().isPresent();
+    }
+}

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

@@ -0,0 +1,27 @@
+package io.quarkus.hibernate.orm.deployment;
+
+import java.util.Optional;
+
+import io.quarkus.runtime.annotations.ConfigGroup;
+import io.quarkus.runtime.configuration.TrimmedStringConverter;
+import io.smallrye.config.WithConverter;
+
+/**
+ * Configuration specific to the Hibernate ORM {@linkplain org.hibernate.dialect.SQLServerDialect}
+ *
+ * @author Steve Ebersole
+ */
+@ConfigGroup
+public interface SqlServerDialectConfig {
+    /**
+     * The {@code compatibility_level} as defined in {@code sys.databases}.
+     *
+     * @see org.hibernate.cfg.DialectSpecificSettings#SQL_SERVER_COMPATIBILITY_LEVEL
+     */
+    @WithConverter(TrimmedStringConverter.class)
+    Optional<String> compatibilityLevel();
+
+    default boolean isAnyPropertySet() {
+        return compatibilityLevel().isPresent();
+    }
+}

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

@@ -1,6 +1,7 @@
 package io.quarkus.hibernate.orm.deployment.dev;
 
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
@@ -55,10 +56,21 @@ void devServicesAutoGenerateByDefault(List<JdbcDataSourceSchemaReadyBuildItem> s
                                 // Only force DB generation if the datasource is configured through dev services
                                 if (propertyKeysIndicatingDataSourceConfigured.stream()
                                         .anyMatch(devServicesConfig::containsKey)) {
-                                    String forcedValue = "drop-and-create";
-                                    LOG.infof("Setting %s=%s to initialize Dev Services managed database",
-                                            schemaManagementStrategyPropertyKey, forcedValue);
-                                    return Map.of(schemaManagementStrategyPropertyKey, forcedValue);
+                                    String offlineStartKey = HibernateOrmRuntimeConfig.puPropertyKey(entry.getKey(),
+                                            "database.start-offline");
+                                    Optional<Boolean> offlineStart = ConfigUtils
+                                            .getFirstOptionalValue(Collections.singletonList(offlineStartKey), Boolean.class);
+
+                                    String forcedValue;
+                                    if (offlineStart.isEmpty() || !offlineStart.get()) {
+                                        forcedValue = "drop-and-create";
+                                        LOG.infof("Setting %s=%s to initialize Dev Services managed database",
+                                                schemaManagementStrategyPropertyKey, forcedValue);
+                                        return Map.of(schemaManagementStrategyPropertyKey, forcedValue);
+                                    } else {
+                                        return Map.of();
+                                    }
+
                                 } else {
                                     return Map.of();
                                 }