Sync documentation of main branch

_generated-doc/main/config/quarkus-all-config.adoc

@@ -19610,6 +19610,36 @@ endif::add-copy-button-to-env-var[]
 |
 
 
+h|[[quarkus-hibernate-orm_section_quarkus-hibernate-orm-flush]] [.section-name.section-level0]##Flush configuration##
+h|Type
+h|Default
+
+a| [[quarkus-hibernate-orm_quarkus-hibernate-orm-flush-mode]] [.property-path]##`quarkus.hibernate-orm.flush.mode`##
+
+`quarkus.hibernate-orm."persistence-unit-name".flush.mode`
+
+[.description]
+--
+The default flushing strategy, or when to flush entities to the database in a Hibernate session:
+before every query, on commit, ...
+
+This default can be overridden on a per-session basis with `Session#setHibernateFlushMode()`
+or on a per-query basis with the hint `HibernateHints#HINT_FLUSH_MODE`.
+
+See the javadoc of `org.hibernate.FlushMode` for details.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HIBERNATE_ORM_FLUSH_MODE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HIBERNATE_ORM_FLUSH_MODE+++`
+endif::add-copy-button-to-env-var[]
+--
+a|`manual`, `commit`, `auto`, `always`
+|`auto`
+
+
 
 h|[.extension-name]##Hibernate Search + Elasticsearch##
 h|Type

_generated-doc/main/config/quarkus-hibernate-orm.adoc

@@ -1170,6 +1170,36 @@ endif::add-copy-button-to-env-var[]
 |
 
 
+h|[[quarkus-hibernate-orm_section_quarkus-hibernate-orm-flush]] [.section-name.section-level0]##Flush configuration##
+h|Type
+h|Default
+
+a| [[quarkus-hibernate-orm_quarkus-hibernate-orm-flush-mode]] [.property-path]##`quarkus.hibernate-orm.flush.mode`##
+
+`quarkus.hibernate-orm."persistence-unit-name".flush.mode`
+
+[.description]
+--
+The default flushing strategy, or when to flush entities to the database in a Hibernate session:
+before every query, on commit, ...
+
+This default can be overridden on a per-session basis with `Session#setHibernateFlushMode()`
+or on a per-query basis with the hint `HibernateHints#HINT_FLUSH_MODE`.
+
+See the javadoc of `org.hibernate.FlushMode` for details.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HIBERNATE_ORM_FLUSH_MODE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HIBERNATE_ORM_FLUSH_MODE+++`
+endif::add-copy-button-to-env-var[]
+--
+a|`manual`, `commit`, `auto`, `always`
+|`auto`
+
+
 |===
 
 ifndef::no-duration-note[]

_generated-doc/main/config/quarkus-hibernate-orm_quarkus.hibernate-orm.adoc

@@ -1170,6 +1170,36 @@ endif::add-copy-button-to-env-var[]
 |
 
 
+h|[[quarkus-hibernate-orm_section_quarkus-hibernate-orm-flush]] [.section-name.section-level0]##Flush configuration##
+h|Type
+h|Default
+
+a| [[quarkus-hibernate-orm_quarkus-hibernate-orm-flush-mode]] [.property-path]##`quarkus.hibernate-orm.flush.mode`##
+
+`quarkus.hibernate-orm."persistence-unit-name".flush.mode`
+
+[.description]
+--
+The default flushing strategy, or when to flush entities to the database in a Hibernate session:
+before every query, on commit, ...
+
+This default can be overridden on a per-session basis with `Session#setHibernateFlushMode()`
+or on a per-query basis with the hint `HibernateHints#HINT_FLUSH_MODE`.
+
+See the javadoc of `org.hibernate.FlushMode` for details.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HIBERNATE_ORM_FLUSH_MODE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HIBERNATE_ORM_FLUSH_MODE+++`
+endif::add-copy-button-to-env-var[]
+--
+a|`manual`, `commit`, `auto`, `always`
+|`auto`
+
+
 |===
 
 ifndef::no-duration-note[]

_versions/main/guides/datasource.adoc

@@ -128,6 +128,7 @@ quarkus.datasource.reactive.max-size=20
 The following section describes the configuration for single or multiple datasources.
 For simplicity, we will reference a single datasource as the default (unnamed) datasource.
 
+[[configure-a-single-datasource]]
 === Configure a single datasource
 
 A datasource can be either a JDBC datasource, reactive, or both.

_versions/main/guides/hibernate-orm.adoc

@@ -584,17 +584,29 @@ public class MyProducer {
 [[persistence-xml]]
 == Setting up and configuring Hibernate ORM with a `persistence.xml`
 
-Alternatively, you can use a `META-INF/persistence.xml` to set up Hibernate ORM.
-This is useful for:
+To set up and configure Hibernate ORM, <<hibernate-configuration-properties,using `application.properties`>> is recommended,
+but you can alternatively use a `META-INF/persistence.xml` file.
+This is mainly useful for migrating existing code to Quarkus.
 
-* migrating existing code
-* when you have relatively complex settings requiring the full flexibility of the configuration
-* or if you like it the good old way
-
-[NOTE]
+[WARNING]
 ====
-If you use a `persistence.xml`, then you cannot use the `quarkus.hibernate-orm.*` properties
-and only persistence units defined in `persistence.xml` will be taken into account.
+Using a `persistence.xml` file implies a few constraints:
+
+* Persistence units defined in `persistence.xml` always use the xref:datasource.adoc#configure-a-single-datasource[default datasource].
+* Persistence units defined in `persistence.xml` must be configured explicitly:
+Quarkus will keep injection of environment-related configuration to a minimum.
++
+In particular, Quarkus will not configure the dialect or database version automatically based on the datasource,
+so if the default configuration of Hibernate ORM doesn't suit your needs,
+you will need to include in `persistence.xml` configuration such as
+link:{hibernate-orm-docs-url}#settings-hibernate.dialect[`hibernate.dialect`]/link:{hibernate-orm-docs-url}#settings-jakarta.persistence.database-product-name[`jakarta.persistence.database-product-name`]
+and possibly link:{hibernate-orm-docs-url}#settings-jakarta.persistence.database-product-version[`jakarta.persistence.database-product-version`].
+* Using `persistence.xml` is incompatible with using `quarkus.hibernate-orm.*` properties  in `{config-file}`:
+if you mix them, Quarkus will raise an exception.
+* Developer experience may be impacted negatively when using `persistence.xml`
+compared to when <<hibernate-configuration-properties,using `application.properties`>>,
+due to unavailable features, limited guidance in the Quarkus documentation,
+and error messages providing resolution hints that cannot be applied (e.g. using `quarkus.hibernate-orm.*` properties).
 
 If your classpath contains a `persistence.xml` that you want to ignore,
 set the following configuration property:
@@ -1395,6 +1407,9 @@ and annotating the implementation with the appropriate qualifiers:
 
 [source,java]
 ----
+import io.quarkus.hibernate.orm.JsonFormat;
+import org.hibernate.type.format.FormatMapper;
+
 @JsonFormat // <1>
 @PersistenceUnitExtension // <2>
 public class MyJsonFormatMapper implements FormatMapper { // <3>
@@ -1412,6 +1427,9 @@ public class MyJsonFormatMapper implements FormatMapper { // <3>
 <1> Annotate the format mapper implementation with the `@JsonFormat` qualifier
 to tell Quarkus that this mapper is specific to JSON serialization/deserialization.
 +
+WARNING: Make sure the Quarkus-specific `@io.quarkus.hibernate.orm.JsonFormat` annotation is used
+and not the one from Jackson.
++
 <2> Annotate the format mapper implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
@@ -1422,6 +1440,9 @@ In case of a custom XML format mapper, a different CDI qualifier must be applied
 
 [source,java]
 ----
+import io.quarkus.hibernate.orm.XmlFormat;
+import org.hibernate.type.format.FormatMapper;
+
 @XmlFormat // <1>
 @PersistenceUnitExtension // <2>
 public class MyJsonFormatMapper implements FormatMapper { // <3>

_versions/main/guides/security-openid-connect-client-registration.adoc

@@ -233,8 +233,6 @@ public class CustomTenantConfigResolver implements TenantConfigResolver {
 
 Alternatively, you can use `OidcClientRegistrations` to prepare a new `OidcClientRegistration` and use `OidcClientRegistration` to register a client. For example:
 
-The above configuration is sufficient for registering new clients using this configuration. For example:
-
 [source,java]
 ----
 package io.quarkus.it.keycloak;