diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index d5afd66cfb894d..684fe97a8c08a7 100644 --- a/docs/src/main/asciidoc/datasource.adoc +++ b/docs/src/main/asciidoc/datasource.adoc @@ -9,7 +9,7 @@ include::_attributes.adoc[] :diataxis-type: reference :categories: data,getting-started,reactive -Use a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive drivers. +Use a unified configuration model to define data sources for Java Database Connectivity (JDBC) and Reactive drivers. //// Note for contributors and writers: @@ -20,38 +20,36 @@ See, https://docs.oracle.com/javase/tutorial/jdbc/basics/connecting.html Applications use datasources to access relational databases. Quarkus provides a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive database drivers. -Quarkus uses link:https://agroal.github.io/[Agroal] and link:https://vertx.io/[Vert.x] to provide high-performance, scaleable data source connection pooling for JDBC and reactive drivers. +Quarkus uses link:https://agroal.github.io/[Agroal] and link:https://vertx.io/[Vert.x] to provide high-performance, scalable data source connection pooling for JDBC and reactive drivers. The `jdbc-\*` and `reactive-*` extensions provide build time optimizations and integrate configured data sources with Quarkus features like security, health checks, and metrics. -For more information on consuming and using a reactive datasource, consult the Quarkus xref:reactive-sql-clients.adoc[Reactive SQL clients] guide. +For more information about consuming and using a reactive datasource, see the Quarkus xref:reactive-sql-clients.adoc[Reactive SQL clients] guide. Additionally, refer to the Quarkus xref:hibernate-orm.adoc[Hibernate ORM] guide for information on consuming and using a JDBC datasource. -//// -Future references to all other parts of this doc. -//// - == Get started with configuring `datasources` in Quarkus For rapid configuration of datasources, this section offers a brief overview and code samples for testing and utilization, suitable for users familiar with the fundamentals. -For more advanced configuration with examples, see xref:datasource-reference[Datasource references]. +For more advanced configuration with examples, see <>. [[dev-services]] === Zero-config setup in development mode -Quarkus simplifies database configuration by offering the Dev Services feature, enabling zero-config database setup for testing or running in dev mode. +Quarkus simplifies database configuration by offering the Dev Services feature, enabling zero-config database setup for testing or running in development (dev) mode. In dev mode, the suggested approach is to use DevServices and let Quarkus handle the database for you, whereas for production mode, you provide explicit database configuration details pointing to a database managed outside of Quarkus. To use Dev Services, add the appropriate driver extension, such as `jdbc-postgresql`, for your desired database type to the `pom.xml` file. -In Dev mode, if you do not provide any explicit database connection details, Quarkus automatically handles the database setup and provides the wiring between the application and the database. +In dev mode, if you do not provide any explicit database connection details, Quarkus automatically handles the database setup and provides the wiring between the application and the database. + If you provide user credentials, the underlying database will be configured to use them. This is useful if you want to connect to the database with an external tool. To utilize this feature, ensure a Docker or Podman container runtime is installed, depending on the database type. Certain databases, such as H2, operate in in-memory mode and do not require a container runtime. -TIP: Prefix the actual connection details for Prod mode with `%prod.` to ensure they are not applied in Dev mode. For more information, see the xref:config-reference.adoc#profiles[Profiles] section of the xref:config-reference.adoc[Configuration reference] guide. +TIP: Prefix the actual connection details for prod mode with `%prod.` to ensure they are not applied in dev mode. +For more information, see the xref:config-reference.adoc#profiles[Profiles] section of the "Configuration reference" guide. For more information about Dev Services, see xref:dev-services.adoc[Dev Services overview]. @@ -85,7 +83,17 @@ 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 you add a driver to the test scope, Quarkus automatically includes the specified driver in testing. + +==== JDBC connection pool size adjustment + +To protect your database from overloading during load peaks, size the pool adequately to throttle the database load. +The optimal pool size depends on many factors, such as the number of parallel application users or the nature of the workload. + +Be aware that setting the pool size too low might cause some requests to time out while waiting for a connection. + +For more information about pool size adjustment properties, see the <> section. + === Configure a reactive datasource @@ -175,7 +183,6 @@ JDBC is the most common database connection pattern, typically needed when used .. For use with a built-in JDBC driver, choose and add the Quarkus extension for your relational database driver from the list below: + - * Derby - `jdbc-derby` * H2 - `jdbc-h2` + @@ -206,6 +213,7 @@ Using a built-in JDBC driver extension automatically includes the Agroal extensi However, for custom drivers, Agroal needs to be added explicitly. ==== + .. For use with a custom JDBC driver, add the `quarkus-agroal` dependency to your project alongside the extension for your relational database driver: + [source,bash] @@ -236,7 +244,8 @@ For more information about configuring JDBC, see <> 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. @@ -421,7 +438,7 @@ Conversely, setting `quarkus.datasource.jdbc.enable-metrics` to `true`, or `quar This can be useful if you need to access the collected metrics programmatically. They are available after calling `dataSource.getMetrics()` on an injected `AgroalDataSource` instance. -If the metrics collection for this datasource is disabled, all values result to zero. +If the metrics collection for this datasource is disabled, all values result in zero. === Narayana transaction manager integration @@ -429,7 +446,7 @@ Integration is automatic if the Narayana JTA extension is also available. You can override this by setting the `transactions` configuration property: -* `quarkus.datasource.jdbc.transactions` for default unnamend datasource +* `quarkus.datasource.jdbc.transactions` for default unnamed datasource * `quarkus.datasource.__.jdbc.transactions` for named datasource For more information, see the <> section below. @@ -450,19 +467,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. +However, the Quarkus Derby extension allows native compilation of the Derby JDBC *client*, supporting *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..dc9cd2b972e990 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. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. *

- * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available. + * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @WithConverter(TrimmedStringConverter.class) Optional credentialsProviderName(); diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java index b8cf1f61fa6b58..eccf515ebc6c95 100644 --- a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java +++ b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java @@ -30,7 +30,7 @@ public interface DataSourcesBuildTimeConfig { Map dataSources(); /** - * Whether or not an health check is published in case the smallrye-health extension is present. + * Whether or not a health check is published in case the smallrye-health extension is present. *

* This is a global setting and is not specific to a datasource. */ 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..475ab13131b1ed 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 @@ -10,18 +10,18 @@ public interface DevServicesBuildTimeConfig { /** - * If DevServices has been explicitly enabled or disabled. DevServices is generally enabled - * by default, unless there is an existing configuration present. + * If DevServices has been explicitly enabled or disabled. + * DevServices is generally enabled by default unless an existing configuration is present. * - * When DevServices is enabled Quarkus will attempt to automatically configure and start - * a database when running in Dev or Test mode. + * When DevServices is enabled, Quarkus will attempt to automatically configure and start a database when running in Dev or + * Test mode. */ Optional enabled(); /** - * The container image name to use, for container based DevServices providers. + * The container image name 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 a container-based database, such as H2 or Derby. */ Optional imageName(); @@ -33,8 +33,8 @@ public interface DevServicesBuildTimeConfig { /** * Generic properties that are passed for additional container configuration. *

- * Properties defined here are database specific and are interpreted specifically in each database dev service - * implementation. + * Properties defined here are database-specific + * and are interpreted specifically in each database dev service implementation. */ Map containerProperties(); @@ -51,14 +51,14 @@ public interface DevServicesBuildTimeConfig { OptionalInt port(); /** - * The container start command to use, for container based DevServices providers. + * 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 a container-based database, such as H2 or Derby. */ Optional command(); /** - * The name of the database to use if this Dev Service supports overriding it. + * The database name to use if this Dev Service supports overriding it. */ Optional dbName(); @@ -73,21 +73,22 @@ 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 path to a SQL script to 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 a container-based database, such as H2 or Derby. */ Optional initScriptPath(); /** - * The volumes to be mapped to the container. The map key corresponds to the host location and the map value is the - * container location. If the host location starts with "classpath:", then the mapping will load the resource from the - * classpath with read-only permission. + * The volumes to be mapped to the container. + * The map key corresponds to the host location; the map value is the container location. + * If the host location starts with "classpath:", + * the mapping loads the resource from the classpath with read-only permission. * - * 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. + * When using a file system location, the volume will be generated with read-write permission, + * potentially leading to data loss or modification in your file system. * - * 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 a container-based database, such as H2 or Derby. */ Map volumes(); } diff --git a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java index d14a2dbc9fd293..c5e95b471c827f 100644 --- a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java +++ b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java @@ -24,7 +24,7 @@ public class InfinispanClientsBuildTimeConfig { public Map namedInfinispanClients; /** - * Whether or not an health check is published in case the smallrye-health extension is present. + * Whether or not a health check is published in case the smallrye-health extension is present. *

* This is a global setting and is not specific to an Infinispan Client. */ 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..8c38177b139524 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 @@ -37,7 +37,8 @@ public class CredentialConfig { /** * Configures the source of the authentication credentials. - * This is typically the database that the credentials have been created. The value defaults to the database + * This is typically the database where the credentials have been created. + * The value defaults to the database * specified in the path portion of the connection string or in the 'database' configuration property. * If the database is specified in neither place, the default value is {@code admin}. This option is only * respected when using the MONGO-CR mechanism (the default). @@ -61,10 +62,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. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. *

- * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available. + * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @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..2368c16e6e40ec 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 @@ -10,7 +10,8 @@ public class RabbitMQBuildTimeConfig { /** - * Configuration for DevServices. DevServices allows Quarkus to automatically start a RabbitMQ broker in dev and test mode. + * Configuration for DevServices. + * DevServices allows Quarkus to start a RabbitMQ broker in dev and test mode automatically. */ @ConfigItem public RabbitMQDevServicesBuildTimeConfig devservices; @@ -24,10 +25,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. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. *

- * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available. + * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @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..9666a72d9f2dbb 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 @@ -10,7 +10,8 @@ import io.quarkus.runtime.configuration.TrimmedStringConverter; /** - * A certificate configuration. Either the certificate and key files must be given, or a key store must be given. + * A certificate configuration. + * Provide either the certificate and key files or a keystore. */ @ConfigGroup @SuppressWarnings("OptionalUsedAsFieldOrParameterType") @@ -18,8 +19,8 @@ public class CertificateConfig { /** * The {@linkplain CredentialsProvider}. - * If this property is configured then a matching 'CredentialsProvider' will be used - * to get the keystore, keystore key and truststore passwords unless these passwords have already been configured. + * If this property is configured, then a matching 'CredentialsProvider' will be used + * to get the keystore, keystore key, and truststore passwords unless these passwords have already been configured. * * Please note that using MicroProfile {@linkplain ConfigSource} which is directly supported by Quarkus Configuration * should be preferred unless using `CredentialsProvider` provides for some additional security and dynamism. @@ -31,10 +32,11 @@ 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 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. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. + *

+ * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @ConfigItem @ConvertWith(TrimmedStringConverter.class) @@ -42,14 +44,14 @@ public class CertificateConfig { /** * The list of path to server certificates using the PEM format. - * Specifying multiple files require SNI to be enabled. + * Specifying multiple files requires SNI to be enabled. */ @ConfigItem public Optional> files; /** - * The list of path to server certificates private key file using the PEM format. - * Specifying multiple files require SNI to be enabled. + * The list of path to server certificates private key files using the PEM format. + * Specifying multiple files requires SNI to be enabled. * * The order of the key files must match the order of the certificates. */ @@ -57,28 +59,28 @@ public class CertificateConfig { public Optional> keyFiles; /** - * An optional key store which holds the certificate information instead of specifying separate files. + * An optional key store that holds the certificate information instead of specifying separate files. */ @ConfigItem public Optional keyStoreFile; /** - * An optional parameter to specify type of the key store file. If not given, the type is automatically detected - * based on the file name. + * An optional parameter to specify the type of the key store file. + * If not given, the type is automatically detected based on the file name. */ @ConfigItem public Optional keyStoreFileType; /** - * An optional parameter to specify a provider of the key store file. If not given, the provider is automatically detected - * based on the key store file type. + * An optional parameter to specify a provider of the key store file. + * If not given, the provider is automatically detected based on the key store file type. */ @ConfigItem public Optional keyStoreProvider; /** - * A parameter to specify the password of the key store file. If not given, and if it can not be retrieved from - * {@linkplain CredentialsProvider}. + * A parameter to specify the password of the key store file. + * If not given, and if it can not be retrieved from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -86,9 +88,9 @@ public class CertificateConfig { public Optional keyStorePassword; /** - * A parameter to specify a {@linkplain CredentialsProvider} property key which can be used to get the password of the key - * store file - * from {@linkplain CredentialsProvider}. + * A parameter to specify a {@linkplain CredentialsProvider} property key, + * which can be used to get the password of the key + * store file from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -96,15 +98,17 @@ public class CertificateConfig { public Optional keyStorePasswordKey; /** - * An optional parameter to select a specific key in the key store. When SNI is disabled, if the key store contains multiple - * keys and no alias is specified, the behavior is undefined. + * An optional parameter to select a specific key in the key store. + * When SNI is disabled, and the key store contains multiple + * keys and no alias is specified; the behavior is undefined. */ @ConfigItem public Optional keyStoreKeyAlias; /** - * An optional parameter to define the password for the key, in case it's different from {@link #keyStorePassword} - * If not given then it may be retrieved from {@linkplain CredentialsProvider}. + * An optional parameter to define the password for the key, + * in case it is different from {@link #keyStorePassword} + * If not given, it might be retrieved from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider}. */ @@ -112,8 +116,8 @@ public class CertificateConfig { public Optional keyStoreKeyPassword; /** - * A parameter to specify a {@linkplain CredentialsProvider} property key which can be used to get the password for the key - * from {@linkplain CredentialsProvider}. + * A parameter to specify a {@linkplain CredentialsProvider} property key, + * which can be used to get the password for the key from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -121,28 +125,28 @@ public class CertificateConfig { public Optional keyStoreKeyPasswordKey; /** - * An optional trust store which holds the certificate information of the certificates to trust. + * An optional trust store that holds the certificate information of the trusted certificates. */ @ConfigItem public Optional trustStoreFile; /** - * An optional parameter to specify type of the trust store file. If not given, the type is automatically detected - * based on the file name. + * An optional parameter to specify the type of the trust store file. + * If not given, the type is automatically detected based on the file name. */ @ConfigItem public Optional trustStoreFileType; /** - * An optional parameter to specify a provider of the trust store file. If not given, the provider is automatically detected - * based on the trust store file type. + * An optional parameter to specify a provider of the trust store file. + * If not given, the provider is automatically detected based on the trust store file type. */ @ConfigItem public Optional trustStoreProvider; /** * A parameter to specify the password of the trust store file. - * If not given then it may be retrieved from {@linkplain CredentialsProvider}. + * If not given, it might be retrieved from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider}. */ @@ -150,9 +154,8 @@ public class CertificateConfig { public Optional trustStorePassword; /** - * A parameter to specify a {@linkplain CredentialsProvider} property key which can be used to get the password of the trust - * store file - * from {@linkplain CredentialsProvider}. + * A parameter to specify a {@linkplain CredentialsProvider} property key, + * which can be used to get the password of the trust store file from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -160,8 +163,8 @@ public class CertificateConfig { public Optional trustStorePasswordKey; /** - * An optional parameter to trust only one specific certificate in the trust store (instead of trusting all certificates in - * the store). + * An optional parameter to trust a single certificate from the trust store rather than trusting all certificates in the + * store. */ @ConfigItem public Optional trustStoreCertAlias;