Application of the QE feedback to the Datasource guide

Signed-off-by: Michal Maléř <[email protected]>

docs/src/main/asciidoc/datasource.adoc

@@ -85,7 +85,16 @@ quarkus.datasource.jdbc.max-size=16
 <1> This configuration value is only required if there is more than one database extension on the classpath.
 
 If only one viable extension is available, Quarkus assumes this is the correct one.
-If a driver has been added to the test scope, Quarkus automatically includes the driver in testing.
+When a driver has been added to the test scope, Quarkus automatically includes the driver in testing.
+
+==== JDBC connection pool size adjustment
+
+To protect your database from overloading during the transaction load peaks, size the pool adequately to throttle the database load.
+The proper size always depends on many factors, such as the number of parallel application users or the nature of the workload.
+Be aware that this pool size adjustment will cause some requests to time out while waiting for a connection.
+
+For more information about pool size adjustment properties, see the xref:jdbc-configuration[] section.
+
 
 === Configure a reactive datasource
 
@@ -278,12 +287,10 @@ AgroalDataSource defaultDataSource;
 In the above example, the type is `AgroalDataSource`, a `javax.sql.DataSource` subtype.
 Because of this, you can also use `javax.sql.DataSource` as the injected type.
 
-
 ==== Reactive datasource
 
 Quarkus offers several reactive clients for a use with reactive datasource.
 
-
 . Add the corresponding extension to your application:
 +
 * DB2: `quarkus-reactive-db2-client`
@@ -302,6 +309,15 @@ quarkus.datasource.reactive.url=postgresql:///your_database
 quarkus.datasource.reactive.max-size=20
 ----
 
+===== Reactive connection pool size adjustment
+
+To protect your database from overloading during the transaction load peaks, size the pool adequately to throttle the database load.
+The proper size always depends on many factors, such as the number of parallel application users or the nature of the workload.
+Be aware that this pool size adjustment will cause some requests to time out while waiting for a connection.
+
+For more information about pool size adjustment properties, see the xref:reactive-configuration[] section.
+
+
 ==== JDBC and reactive datasources simultaneously
 
 When a JDBC extension - along with Agroal - and a reactive datasource extension handling the given database kind are included, they will both be created by default.
@@ -450,19 +466,17 @@ Some databases like H2 and Derby are commonly used in the _embedded mode_ as a f
 The recommended approach is to use the real database you intend to use in production, especially when xref:databases-dev-services.adoc[Dev Services provide a zero-config database for testing], and running tests against a container is relatively quick and produces expected results on an actual environment.
 However, it is also possible to use JVM-powered databases for scenarios when the ability to run simple integration tests is required.
 
-NOTE: While configuring Derby to use the embedded engine works as usual in JVM mode, such an application will not compile into a native executable. It is because Quarkus Derby extensions do not support embedding the entire database engine into a native executable, and it only covers making the JDBC client code compatible with the native compilation step.
 
 ==== Support and limitations
 
 Embedded databases (H2 and Derby) work in JVM mode.
 For native mode, the following limitations apply:
 
-* Derby cannot be embedded into the application in native mode, and only remote connection is supported.
-[IMPORTANT]
-====
-Embedding H2 within your native image is not recommended. 
+* Derby cannot be embedded into the application in native mode; it only supports a remote connection.
+The Quarkus Derby extension allows native compilation of the Derby JDBC client, supporting only remote connections.
+
+* Embedding H2 within your native image is not recommended.
 Consider using an alternative approach, for example, using a remote connection to a separate database instead.
-====
 
 ==== Run an integration test
 

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

@@ -28,10 +28,10 @@ public interface DataSourceRuntimeConfig {
     /**
      * The credentials provider bean name.
      * <p>
-     * It is the {@code &#64;Named} value of the credentials provider bean. It is used to discriminate if multiple
-     * CredentialsProvider beans are available.
+     * It represents the `@Named` value of the credentials provider bean,
+     * which is used for discrimination when multiple `CredentialsProvider` beans are available.
      * <p>
-     * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available.
+     * For Vault, it is named `vault-credentials-provider`. This is not necessary if only one credentials provider is available.
      */
     @WithConverter(TrimmedStringConverter.class)
     Optional<String> credentialsProviderName();

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

@@ -21,7 +21,7 @@ public interface DevServicesBuildTimeConfig {
     /**
      * The container image name to use, for container based DevServices providers.
      *
-     * If the provider is not container based (e.g. a H2 Database) then this has no effect.
+     * This has no effect if the provider is not container-based database, such as H2 or Derby.
      */
     Optional<String> imageName();
 
@@ -53,7 +53,7 @@ public interface DevServicesBuildTimeConfig {
     /**
      * The container start command to use, for container based DevServices providers.
      *
-     * If the provider is not container based (e.g. a H2 Database) then this has no effect.
+     * This has no effect if the provider is not container-based database, such as H2 or Derby.
      */
     Optional<String> command();
 
@@ -73,9 +73,9 @@ public interface DevServicesBuildTimeConfig {
     Optional<String> password();
 
     /**
-     * Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database
+     * The The path to a SQL script that will be loaded from the classpath and applied to the Dev Service database..
      *
-     * If the provider is not container based (e.g. an H2 or Derby Database) then this has no effect.
+     * This has no effect if the provider is not container-based database, such as H2 or Derby.
      */
     Optional<String> initScriptPath();
 
@@ -87,7 +87,7 @@ public interface DevServicesBuildTimeConfig {
      * When using a file system location, the volume will be created with read-write permission, so the data in your file
      * system might be wiped out or altered.
      *
-     * If the provider is not container based (e.g. an H2 or Derby Database) then this has no effect.
+     * This has no effect if the provider is not container-based database, such as H2 or Derby.
      */
     Map<String, String> volumes();
 }

extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java

@@ -61,10 +61,10 @@ public class CredentialConfig {
     /**
      * The credentials provider bean name.
      * <p>
-     * It is the {@code &#64;Named} value of the credentials provider bean. It is used to discriminate if multiple
-     * CredentialsProvider beans are available.
+     * It represents the `@Named` value of the credentials provider bean,
+     * which is used for discrimination when multiple `CredentialsProvider` beans are available.
      * <p>
-     * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available.
+     * For Vault, it is named `vault-credentials-provider`. This is not necessary if only one credentials provider is available.
      */
     @ConfigItem
     @ConvertWith(TrimmedStringConverter.class)

extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java

@@ -24,10 +24,10 @@ public class RabbitMQBuildTimeConfig {
     /**
      * The credentials provider bean name.
      * <p>
-     * It is the {@code &#64;Named} value of the credentials provider bean. It is used to discriminate if multiple
-     * CredentialsProvider beans are available.
+     * It represents the `@Named` value of the credentials provider bean,
+     * which is used for discrimination when multiple `CredentialsProvider` beans are available.
      * <p>
-     * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available.
+     * For Vault, it is named `vault-credentials-provider`. This is not necessary if only one credentials provider is available.
      */
     @ConfigItem
     public Optional<String> credentialsProviderName = Optional.empty();

extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java

@@ -31,8 +31,8 @@ public class CertificateConfig {
     /**
      * The credentials provider bean name.
      * <p>
-     * It is the {@code &#64;Named} value of the credentials provider bean. It is used to discriminate if multiple
-     * CredentialsProvider beans are available.
+     * It represents the `@Named` value of the credentials provider bean,
+     * which is used for discrimination when multiple `CredentialsProvider` beans are available.
      * It is recommended to set this property even if there is only one credentials provider currently available
      * to ensure the same provider is always found in deployments where more than one provider may be available.
      */