HHH-11808 - Update migration guide and documentation

documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc

@@ -708,7 +708,7 @@ Used to specify the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/jav
 Setting to choose the strategy used to access the JDBC Metadata.
 Valid options are defined by the `strategy` value of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/JdbcMetadaAccessStrategy.html[`JdbcMetadaAccessStrategy`] enum:
 
-`grouped`:: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaMigrator.html[`SchemaMigrator`] and https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaValidator.html[`SchemaValidator`] execute a single `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call to retrieve all the database table in order to determine if all the `javax.persistence.Entity` have a corresponding mapped database tables.
+`grouped`:: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaMigrator.html[`SchemaMigrator`] and https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaValidator.html[`SchemaValidator`] execute a single `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call to retrieve all the database table in order to determine if all the `javax.persistence.Entity` have a corresponding mapped database tables.This strategy may require `hibernate.default_schema` and/or `hibernate.default_catalog` to be provided.
 `individually`:: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaMigrator.html[`SchemaMigrator`] and https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaValidator.html[`SchemaValidator`] execute one `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call for each `javax.persistence.Entity` in order to determine if a corresponding database table exists.
 
 |`hibernate.hbm2ddl.delimiter` | `;` |Identifies the delimiter to use to separate schema management statements in script outputs.

hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java

@@ -1362,6 +1362,8 @@ public interface AvailableSettings {
 	 *
 	 * Valid options are defined by the {@link JdbcMetadaAccessStrategy} enum.
 	 *
+	 * {@link JdbcMetadaAccessStrategy#GROUPED} is the default value.
+	 *
 	 * @see JdbcMetadaAccessStrategy
 	 */
 	String HBM2DDL_JDBC_METADATA_EXTRACTOR_STRATEGY = "hibernate.hbm2ddl.jdbc_metadata_extraction_strategy";

hibernate-core/src/main/java/org/hibernate/tool/schema/JdbcMetadaAccessStrategy.java

@@ -24,6 +24,9 @@ public enum JdbcMetadaAccessStrategy {
 	 * The {@link org.hibernate.tool.schema.spi.SchemaMigrator} and {@link org.hibernate.tool.schema.spi.SchemaValidator}
 	 * execute a single {@link java.sql.DatabaseMetaData#getTables(String, String, String, String[])} call
 	 * to retrieve all the database table in order to determine all the {@link javax.persistence.Entity} have a mapped database tables.
+	 *
+	 * This strategy is the default one and it may require {@link AvailableSettings#DEFAULT_CATALOG} and/or
+	 * {@link AvailableSettings#DEFAULT_SCHEMA} values to be provided.
 	 */
 	GROUPED( "grouped" );
 

migration-guide.adoc

@@ -83,6 +83,17 @@ The specific dialects impacted by this change are restricted to the following.
 NOTE: If a dialect that extends any in the above list but overrides the limit handler implementation, then those
 dialects remain unchanged, e.g. SQLServer2005Dialect.
 
+== Changes to schema management tooling
+
+In 5.2.3, a new strategy for retrieving database tables was introduced that improves SchemaMigrator and SchemaValidator
+performance. This strategy executes a single `java.sql.DatabaseMetaData#getTables(String, String, String, String[])`
+call to determine if each `javax.persistence.Entity` has a mapped database table.
+This strategy is the default, and uses the property setting `hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped`.
+This strategy may require `hibernate.default_schema` and/or `hibernate.default_catalog` to be provided.
+
+To use the old strategy, which executes a `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call for
+each javax.persistence.Entity, use the property setting `hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually`.
+
 
 == Misc