From 84ff8b50c55040a853656b5ce382189840f9b846 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Mal=C3=A9=C5=99?= Date: Thu, 7 Sep 2023 15:43:01 +0200 Subject: [PATCH] Application of the QE feedback to the Datasource guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Maléř Adding @asciidoclet annotation Signed-off-by: Michal Maléř --- docs/src/main/asciidoc/datasource.adoc | 32 +++++++++++++------ .../runtime/DataSourceRuntimeConfig.java | 7 ++-- .../runtime/DevServicesBuildTimeConfig.java | 10 +++--- .../mongodb/runtime/CredentialConfig.java | 7 ++-- .../deployment/RabbitMQBuildTimeConfig.java | 7 ++-- .../vertx/http/runtime/CertificateConfig.java | 4 +-- 6 files changed, 42 insertions(+), 25 deletions(-) diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index d5afd66cfb894d..101756e45c3813 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 35e9162fb0fbe4..8aa56b4b6a4575 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 074290a2f095cb..56d360a8affb67 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 43bce59565cd72..bcb0bf7169550d 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 553c6e3ff84258..d7eab82ae10df9 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 1d8fa0a4f59365..0285b3362570e4 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. */