diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc
index d5afd66cfb894..101756e45c381 100644
--- a/docs/src/main/asciidoc/datasource.adoc
+++ b/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
diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java
index 35e9162fb0fbe..8aa56b4b6a457 100644
--- a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java
+++ b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java
@@ -28,10 +28,11 @@ public interface DataSourceRuntimeConfig {
/**
* The credentials provider bean name.
*
- * It is the {@code @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.
*
- * 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.
+ * @asciidoclet
*/
@WithConverter(TrimmedStringConverter.class)
Optional credentialsProviderName();
diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java
index 074290a2f095c..56d360a8affb6 100644
--- a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java
+++ b/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 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 command();
@@ -73,9 +73,9 @@ public interface DevServicesBuildTimeConfig {
Optional 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 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 volumes();
}
diff --git a/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java b/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java
index 43bce59565cd7..bcb0bf7169550 100644
--- a/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java
+++ b/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java
@@ -61,10 +61,11 @@ public class CredentialConfig {
/**
* The credentials provider bean name.
*
- * It is the {@code @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.
*
- * 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.
+ * @asciidoclet
*/
@ConfigItem
@ConvertWith(TrimmedStringConverter.class)
diff --git a/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java b/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java
index 553c6e3ff8425..d7eab82ae10df 100644
--- a/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java
+++ b/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java
@@ -24,10 +24,11 @@ public class RabbitMQBuildTimeConfig {
/**
* The credentials provider bean name.
*
- * It is the {@code @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.
*
- * 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.
+ * @asciidoclet
*/
@ConfigItem
public Optional credentialsProviderName = Optional.empty();
diff --git a/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java b/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java
index 1d8fa0a4f5936..0285b3362570e 100644
--- a/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java
+++ b/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.
*
- * It is the {@code @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.
*/