From 5df46678a1800f9906f6dcbab4089bab0310f0b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Mal=C3=A9=C5=99?= Date: Thu, 20 Apr 2023 15:10:50 +0200 Subject: [PATCH] Datasource review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Maléř Applying suggestions form an SME review-1 Signed-off-by: Michal Maléř Applying suggestions form an SME review-2 Signed-off-by: Michal Maléř Applying suggestions form an SME review-3 Signed-off-by: Michal Maléř --- docs/src/main/asciidoc/datasource.adoc | 546 +++++++++++++------------ 1 file changed, 277 insertions(+), 269 deletions(-) diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index 6a8c0cd15c9cb9..80661e3e1099f8 100644 --- a/docs/src/main/asciidoc/datasource.adoc +++ b/docs/src/main/asciidoc/datasource.adoc @@ -6,58 +6,55 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Datasources include::_attributes.adoc[] :categories: data -:summary: With Quarkus, you can easily configure a datasource, or several if need be. +:summary: Learn how to easily configure a Java Database Connectivity (JDBC) and Reactive datasource, their combination, or several datasources if required -Many projects that use data require connections to a relational database. +This guide is mainly about datasource configuration, and explains the following: -The usual way of obtaining connections to a database is to use a datasource and configure a JDBC driver. -But you might also prefer using a reactive driver to connect to your database in a reactive way. +* Configuring a datasource or multiple datasources +* How to obtain a reference to those datasources in the code +* How to enable metrics and health checks for datasources -Quarkus has you covered either way: +Many projects require connections to a relational database. +The usual way to obtain database connections is to use a datasource with a database driver. -* For JDBC, the preferred datasource and connection pooling implementation is https://agroal.github.io/[Agroal]. -* For reactive, we use the https://vertx.io/[Vert.x] reactive drivers. +Quarkus supports JDBC and reactive drivers and allows for unified and flexible configurations. -Both are configured via unified and flexible configuration. +Quarkus supports lightweight link:https://agroal.github.io/[Agroal] datasource and connection pooling implementation for JDBC, as well as https://vertx.io/[Vert.x] reactive drivers for reactive approaches. +This provides high performance, scalability, and features integration with the other components in Quarkus, +such as security, transaction management components, health, and metrics. -[NOTE] -==== -Agroal is a modern, lightweight connection pool implementation designed for very high performance and scalability, -and features first class integration with the other components in Quarkus, such as security, transaction management components, health, and metrics. -==== - -This guide will explain how to: - -* configure a datasource, or multiple datasources -* how to obtain a reference to those datasources in code -* which pool tuning configuration properties are available +For more details about consuming and using a reactive datasource, +refer to the xref:reactive-sql-clients.adoc[Reactive SQL clients] guide. -This guide is mainly about datasource configuration. -If you want more details about how to consume and make use of a reactive datasource, -please refer to the xref:reactive-sql-clients.adoc[Reactive SQL clients guide]. -== TL;DR +== Introduction to datasource configuration -This is a quick introduction to datasource configuration. -If you want a better understanding of how all this works, this guide has a lot more information in the subsequent paragraphs. +To start configuring datasources quickly, this section serves as a quick introduction to datasources and provides you with code references you can test and use if you are already familiar with the basics. +For explainers, examples, and references, refer to the other chapters in this guide. [[dev-services]] -=== Zero Config Setup (Dev Services) +=== Zero-config setup -When testing or running in dev mode Quarkus can even provide you with a zero config database out of the box, a feature -we refer to as Dev Services. Depending on your database type you may need Docker installed in order to use this feature. +When testing or running in development mode, Quarkus can provide you with a zero-config database, a feature referred to as _Dev Services_. -If you want to use Dev Services then all you need to do is include the relevant extension for the type of database you want, -e.g. `jdbc-postgresql`, `reactive-pg-client` or both. Don't configure a database URL, username and password - -Quarkus will provide the database and you can just start coding without worrying about config. +Depending on your database type, a Docker or Podman container runtime need to be installed to use this feature. +Some databases, such as H2, run in-memory and do not require a container runtime. -See xref:databases-dev-services.adoc[Databases Dev Services] for more details and optional configurations. +. To start using Dev Services, include the relevant extension for the type of database you want, such as `jdbc-postgresql`, `reactive-pg-client`, or both. ++ +In this scenario, configuring a database URL and setting up username and password is not needed. +If you provide the user credentials, Quarkus will configure the underlying database to use them. +This is useful when you want to connect to the underlying database externally using your tooling. ++ +Quarkus provides the database instance and the necessary connection between the database and application. You can start coding without worrying about config. ++ +For more details and optional configurations, see xref:databases-dev-services.adoc[Databases Dev Services]. === JDBC datasource -Add the `agroal` extension plus one of `jdbc-db2`, `jdbc-derby`, `jdbc-h2`, `jdbc-mariadb`, `jdbc-mssql`, `jdbc-mysql`, `jdbc-oracle` or `jdbc-postgresql`. +. Add the `agroal` extension plus one of `jdbc-db2`, `jdbc-derby`, `jdbc-h2`, `jdbc-mariadb`, `jdbc-mssql`, `jdbc-mysql`, `jdbc-oracle` or `jdbc-postgresql`. -Then configure your datasource: +. Configure your datasource as follows: [source, properties] ---- @@ -68,16 +65,21 @@ quarkus.datasource.password= quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test quarkus.datasource.jdbc.max-size=16 ---- -<1> If you only have a single JDBC extension, or you are running tests and only have a single test scoped JDBC extension installed then this is -optional. If there is only one possible extension we assume this is the correct one, and if a driver has been added with test scope then -we assume that this should be used in testing. +<1> If you only have a single JDBC extension or are running tests and only have a single test-scoped JDBC extension installed, then this is optional. +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. === Reactive datasource -Add the correct reactive extension for the database you are using: -`reactive-db2-client`, `reactive-mssql-client`, `reactive-mysql-client`, `reactive-oracle-client`, or `reactive-pg-client`. +. Add the correct reactive extension for the database of your choice. -Then configure your reactive datasource: +* `reactive-db2-client` +* `reactive-mssql-client` +* `reactive-mysql-client` +* `reactive-oracle-client` +* `reactive-pg-client` + +. Configure your reactive datasource: [source, properties] ---- @@ -88,25 +90,32 @@ quarkus.datasource.password= quarkus.datasource.reactive.url=postgresql:///your_database quarkus.datasource.reactive.max-size=20 ---- -<1> As specified above this is optional. +<1> This is optional. + +== How to configure datasources -== Default datasource +The following section describes the configuration for single or multiple datasources. +For simplicity, we will reference a single datasource as the default (unnamed) datasource. -A datasource can be either a JDBC datasource, a reactive one or both. -It all depends on how you configure it and which extensions you added to your project. +=== Configure a single datasource -To define a datasource, start with the following (note that this is only required if you have more than one -database type installed): +A datasource can be either a JDBC datasource, reactive, or both. +This depends on the configuration and the selection of project extensions. +. Define a datasource with the following command: ++ [source, properties] ---- quarkus.datasource.db-kind=h2 ---- - -The database kind defines which type of database you will connect to. - -We currently include these built-in database kinds: - ++ +NOTE: This step is required if you have multiple drivers for more than one +database type installed. ++ +The database kind defines to which type of database you will connect. ++ +Quarkus currently include these built-in database kinds: ++ * DB2: `db2` * Derby: `derby` * H2: `h2` @@ -115,61 +124,55 @@ We currently include these built-in database kinds: * MySQL: `mysql` * Oracle: `oracle` * PostgreSQL: `postgresql`, `pgsql` or `pg` - -Giving Quarkus the database kind you are targeting will facilitate configuration. ++ +Providing Quarkus with the database kind you are targeting simplifies the subsequent configuration. By using a JDBC driver extension and setting the kind in the configuration, -Quarkus resolves the JDBC driver automatically, -so you don't need to configure it yourself. -If you want to use a database kind that is not part of the built-in ones, use `other` and define the JDBC driver explicitly. - +Quarkus resolves the JDBC driver automatically, so you do not need to configure it yourself. ++ +If you want to use a database kind that is not built-in, use `other` and define the JDBC driver explicitly. ++ [NOTE] ==== -You can use any JDBC driver in a Quarkus app in JVM mode (see <>). -It is unlikely that it will work when compiling your application to a native executable though. +You can use any JDBC driver in a Quarkus app in JVM mode. +See <>. +However, JVM mode is unlikely to work when compiling your application to a native executable. -If you plan to make a native executable, we recommend you use the existing JDBC Quarkus extensions (or contribute one for your driver). +If you want to build a native executable, use the existing JDBC Quarkus extensions, or contribute one for your driver. ==== -There is a good chance you will need to define some credentials to access your database. - -This is done by configuring the following properties: - +. Configure the following properties to enable access to your database by defining the following credentials: ++ [source, properties] ---- quarkus.datasource.username= quarkus.datasource.password= ---- - ++ You can also retrieve the password from Vault by link:{vault-datasource-guide}[using a credential provider] for your datasource. -Once you have defined the database kind and the credentials, you are ready to configure either a JDBC datasource, a reactive one, or both. - -=== JDBC datasource - -JDBC is the most common database connection pattern. -You typically need a JDBC datasource when using Hibernate ORM. +Until now, the configuration has been the same regardless of whether you’re using a JDBC or a reactive driver. +When you have defined the database kind and the credentials, the rest depends on what type of driver you are using. +It is possible to use JDBC and a reactive driver simultaneously. -==== Install the Maven dependencies +==== JDBC datasource -First, you will need to add the `quarkus-agroal` dependency to your project. - -You can add it using a simple Maven command: +JDBC is the most common database connection pattern, typically needed when used in combination with non-reactive Hibernate ORM. +. Add the `quarkus-agroal` dependency to your project using the following Maven command: ++ [source,bash] ---- ./mvnw quarkus:add-extension -Dextensions="agroal" ---- - ++ [TIP] ==== -Agroal comes as a transitive dependency of the Hibernate ORM extension so if you are using Hibernate ORM, -you don't need to add the Agroal extension dependency explicitly. +Agroal comes as a transitive dependency of the Hibernate ORM extension. +Therefore, the Agroal extension dependency does not have to be added explicitly when Hibernate ORM is in use. ==== -You will also need to choose, and add, the Quarkus extension for your relational database driver. - -Quarkus provides driver extensions for: - +. Choose and add the Quarkus extension for your relational database driver from the list below: ++ * DB2 - `jdbc-db2` * Derby - `jdbc-derby` * H2 - `jdbc-h2` @@ -178,48 +181,44 @@ Quarkus provides driver extensions for: * MySQL - `jdbc-mysql` * Oracle - `jdbc-oracle` * PostgreSQL - `jdbc-postgresql` - -Some other JDBC extensions can be found in the Quarkiverse such as: - -* SQLite: https://github.com/quarkiverse/quarkus-jdbc-sqlite[Project homepage] - https://quarkiverse.github.io/quarkiverse-docs/quarkus-jdbc-sqlite/dev/index.html[Documentation] - ++ +Other JDBC extensions, such as link:https://github.com/quarkiverse/quarkus-jdbc-sqlite[SQLite] and its link:https://quarkiverse.github.io/quarkiverse-docs/quarkus-jdbc-sqlite/dev/index.html[documentation], can be found in the Quarkiverse website. ++ See <> if you want to use a JDBC driver for another database. - ++ [NOTE] ==== -The H2 and Derby databases can normally be configured to run in "embedded mode"; -however the Derby extension does not support compiling the embedded database engine into native executables. +The H2 and Derby databases can be configured to run in "embedded mode"; however, the Derby extension does not support compiling the embedded database engine into native executables. -Read <> (below) for suggestions regarding integration testing. +Read <> for suggestions regarding integration testing. ==== -As usual, you can install the extension using `add-extension`. - -To install the PostgreSQL driver dependency for instance, run the following command: - +. Install the extension using the `add-extension` command. ++ +For example, to install the PostgreSQL driver dependency, run the following command: ++ [source,bash] ---- ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql" ---- -==== Configure the JDBC connection - -Configuring your JDBC connection is easy, the only mandatory property is the JDBC URL. - +. Configure the JDBC connection by defining the JDBC URL property: ++ [source, properties] ---- quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test ---- - ++ [NOTE] ==== Note the `jdbc` prefix in the property name. -All the configuration properties specific to JDBC have this prefix. +All the configuration properties specific to JDBC have the `jdbc` prefix. +For reactive datasources, the prefix is `reactive`. ==== - ++ [TIP] ==== -For more information about the JDBC URL format, please refer to the <>. +For more information about the JDBC URL format, refer to the <>. ==== When using one of the built-in datasource kinds, the JDBC driver is resolved automatically to the following values: @@ -263,28 +262,26 @@ When using one of the built-in datasource kinds, the JDBC driver is resolved aut [TIP] ==== -As previously stated, most of the time, this automatic resolution will suit you and -you won't need to configure the driver. +This automatic resolution is applicable in most cases so that driver configuration is not needed anymore. ==== [[other-databases]] -==== Use a database with no built-in extension or with a different driver +===== Use a database with no built-in extension or with a different driver -You can use a specific driver if you need to (for instance for using the OpenTracing driver) -or if you want to use a database for which Quarkus does not have a built-in JDBC driver extension. +You can use a specific driver if you need to (for instance, for using the OpenTracing driver) or if you want to use a database for which Quarkus does not have a built-in JDBC driver extension. -Without an extension, the driver will work fine in any Quarkus app running in JVM mode. -It is unlikely that it will work when compiling your application to a native executable though. -If you plan to make a native executable, we recommend you use the existing JDBC Quarkus extensions (or contribute one for your driver). +Without an extension, the driver will work correctly in any Quarkus app running in JVM mode. +However, the driver is unlikely to work when compiling your application to a native executable. +If you plan to make a native executable, use the existing JDBC Quarkus extensions, or contribute one for your driver. -Here is how you would use the OpenTracing driver: +.An example with the OpenTracing driver: [source, properties] ---- quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver ---- -Here is how you would define access to a database with no built-in support (in JVM mode): +.An example for defining access to a database with no built-in support in JVM mode: [source, properties] ---- @@ -295,102 +292,90 @@ quarkus.datasource.username=scott quarkus.datasource.password=tiger ---- -==== More configuration - -You can configure a lot more things, for instance the size of the connection pool. - -Please refer to the <> for all the details about the JDBC configuration knobs. - -==== Consuming the datasource +For all the details about the JDBC configuration options and configuring other aspects, +such as the connection pool size, refer to the <> section. -If you are using Hibernate ORM, the datasource will be consumed automatically. +===== Consuming the datasource -If for whatever reason, access to the datasource is needed in code, it can be obtained as any other bean in the following manner: +With Hibernate ORM, the Hibernate layer automatically picks the datasource up and use it. +. For the in-code access to the datasource, obtain it as any other bean as follows: ++ [source,java] ---- @Inject AgroalDataSource defaultDataSource; ---- - -In the above example, the type is `AgroalDataSource` which is a subtype of `javax.sql.DataSource`. ++ +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 - -If you prefer using a reactive datasource, Quarkus offers DB2, MariaDB/MySQL, Microsoft SQL Server, Oracle and PostgreSQL reactive clients. -==== Install the Maven dependencies +==== Reactive datasource -Depending on which database you want to use, add the corresponding extension: +If you prefer using a reactive datasource, Quarkus offers DB2, MariaDB/MySQL, Microsoft SQL Server, Oracle, and PostgreSQL reactive clients. +. Install the corresponding database extension: ++ * DB2: `quarkus-reactive-db2-client` * MariaDB/MySQL: `quarkus-reactive-mysql-client` * Microsoft SQL Server: `quarkus-reactive-mssql-client` * Oracle: `quarkus-reactive-oracle-client` * PostgreSQL: `quarkus-reactive-pg-client` - ++ The installed extension must be consistent with the `quarkus.datasource.db-kind` you define in your datasource configuration. -==== Configure the reactive datasource - -Once the driver is there, you just need to configure the connection URL. - -Optionally, but highly recommended, you should define a proper size for your connection pool. - +. After installing the driver, configure the connection URL and define a proper size for your connection pool. ++ [source,properties] ---- quarkus.datasource.reactive.url=postgresql:///your_database quarkus.datasource.reactive.max-size=20 ---- -=== JDBC and reactive datasources simultaneously +==== JDBC and reactive datasources simultaneously -By default, if you include both a JDBC extension (+ Agroal) and a reactive datasource extension handling the given database kind, -both will be created. - -If you want to disable the JDBC datasource explicitly, use: +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. +* To disable the JDBC datasource explicitly: ++ [source, properties] ---- quarkus.datasource.jdbc=false ---- -If you want to disable the reactive datasource explicitly, use: - +* To disable the reactive datasource explicitly: ++ [source, properties] ---- quarkus.datasource.reactive=false ---- - ++ [TIP] ==== -Most of the time, the configuration above won't be necessary as either a JDBC driver or a reactive datasource extension will be present and not both. +In most cases, the configuration above will be optional as either a JDBC driver or a reactive datasource extension will be present, not both. ==== -== Multiple Datasources - -=== Configuring Multiple Datasources +=== Configure multiple datasources -For now, multiple datasources are only supported for JDBC and the Agroal extension. -So it is not currently possible to create multiple reactive datasources. +Multiple datasources are only supported for JDBC and the Agroal extension. +Creating multiple reactive datasources is not currently possible. [NOTE] ==== -The Hibernate ORM extension xref:hibernate-orm.adoc#multiple-persistence-units[supports defining several persistence units using configuration properties]. -For each persistence unit, you can point to the datasource of your choice. +The Hibernate ORM extension supports defining xref:hibernate-orm.adoc#multiple-persistence-units[persistence units] using configuration properties. +For each persistence unit, point to the datasource of your choice. ==== -Defining multiple datasources works exactly the same way as defining a single datasource, with one important change: -you define a name. +Defining multiple datasources works like defining a single datasource, with one important change - you have to specify a name (configuration key) for each datasource. -In the following example, you have 3 different datasources: +The following example provides three different datasources: -* The default one, -* A datasource named `users`, -* A datasource named `inventory`, +* the default one +* a datasource named `users` +* a datasource named `inventory` -each with its own configuration. +Each with its configuration: [source,properties] ---- @@ -410,18 +395,19 @@ quarkus.datasource.inventory.jdbc.url=jdbc:h2:mem:inventory quarkus.datasource.inventory.jdbc.max-size=12 ---- -Notice there is an extra bit in the key. +Notice there is an extra section in the configuration key. The syntax is as follows: `quarkus.datasource.[optional name.][datasource property]`. -NOTE: Even when only one database extension is installed, named databases need to specify at least one build time -property so that Quarkus knows they exist. Generally this will be the `db-kind` property, although you can also +NOTE: Even when only one database extension is installed, named databases need to specify at least one build-time property so that Quarkus can detect them. +Generally, this is the `db-kind` property, but you can also specify Dev Services properties to create named datasources (covered later in this guide). -=== Named Datasource Injection +==== Named Datasource Injection When using multiple datasources, each `DataSource` also has the `io.quarkus.agroal.DataSource` qualifier with the name of the datasource as the value. -Using the above properties to configure three different datasources, you can also inject each one as follows: +. Using the above-mentoned properties to configure three different datasources, inject each one as follows: ++ [source,java,indent=0] ---- @Inject @@ -436,69 +422,91 @@ AgroalDataSource usersDataSource; AgroalDataSource inventoryDataSource; ---- -== Datasource Health Check +== Datasource integrations + +=== Datasource Health Check + +If you use the `quarkus-smallrye-health` extension, the `quarkus-agroal` and reactive client extensions automatically add a readiness health check to validate the datasource. -If you are using the `quarkus-smallrye-health` extension, the `quarkus-agroal` and reactive client extensions will automatically add a readiness health check -to validate the datasource. +When you access your application's `/q/health/ready` endpoint, you receive information about the datasource validation status. +If you have multiple datasources, all datasources are checked, and if a single datasource validation failure occurs, the status changes to`DOWN`. -When you access the `/q/health/ready` endpoint of your application you will have information about the datasource validation status. -If you have multiple datasources, all datasources will be checked and the status will be `DOWN` as soon as there is one datasource validation failure. +This behavior can be disabled by using the `quarkus.datasource.health.enabled` property. +To exclude only a particular datasource from the health check: + +[source,properties] +---- + `quarkus.datasource."datasource-name".health-exclude=true`. +---- -This behavior can be disabled via the property `quarkus.datasource.health.enabled`. +=== Datasource Metrics -== Datasource Metrics +If you are using the `quarkus-micrometer` or `quarkus-smallrye-metrics` extensions, `quarkus-agroal` can expose some datasource metrics on the `/q/metrics` endpoint. +This can be activated by setting the `quarkus.datasource.metrics.enabled` property to `true`. -If you are using the `quarkus-micrometer` or `quarkus-smallrye-metrics` extension, `quarkus-agroal` can expose some data source metrics on the -`/q/metrics` endpoint. This can be turned on by setting the property `quarkus.datasource.metrics.enabled` to true. +For the exposed metrics to contain any actual values, a metric collection must be enabled internally by Agroal mechanisms. +By default, this metric collection mechanism is enabled for all datasources when a metrics extension is present, and metrics for the Agroal extension are enabled. -For the exposed metrics to contain any actual values, it is necessary that metric collection is enabled internally -by Agroal mechanisms. By default, this metric collection mechanism gets turned on for all data sources if a metrics extension -is present and metrics for the Agroal extension are enabled. If you want to disable metrics for a particular data source, -this can be done by setting `quarkus.datasource.jdbc.enable-metrics` to `false` (or `quarkus.datasource..jdbc.enable-metrics` for a named datasource). -This disables collecting the metrics as well as exposing them in the `/q/metrics` endpoint, -because it does not make sense to expose metrics if the mechanism to collect them is disabled. +To disable metrics for a particular data source, +set `quarkus.datasource.jdbc.enable-metrics` to `false`, or apply `quarkus.datasource..jdbc.enable-metrics` for a named datasource. +This disables collecting the metrics and exposing them in the `/q/metrics` endpoint if the mechanism to collect them is disabled. -Conversely, setting `quarkus.datasource.jdbc.enable-metrics` to `true` (or `quarkus.datasource..jdbc.enable-metrics` for a named datasource) explicitly can be used to enable collection of metrics even if -a metrics extension is not in use. +Conversely, setting `quarkus.datasource.jdbc.enable-metrics` to `true`, or `quarkus.datasource..jdbc.enable-metrics` for a named datasource explicitly enables metrics collection even if a metrics extension is not in use. 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 collection of metrics is disabled -for this data source, all values will be zero. +They are available after calling `dataSource.getMetrics()` on an injected `AgroalDataSource` instance. -== Narayana Transaction Manager integration +If the metrics collection for this datasource is disabled, all values result to zero. -If the Narayana JTA extension is also available, integration is automatic. +=== Narayana transaction manager integration -You can override this by setting the `transactions` configuration property - see the <> below. +Integration is automatic if the Narayana JTA extension is also available. -=== Named Datasources +You can override this by setting the `transactions` configuration property. +See the <> section below. -When using Dev Services the default datasource will always be created, but to specify a named datasource you need to have -at least one build time property so Quarkus knows to create the datasource. You will usually either specify -the `db-kind` property, or explicitly enable Dev Services: `quarkus.datasource."name".devservices.enabled=true`. +==== Named datasources + +When using Dev Services, the default datasource will always be created, but to specify a named datasource, you need to have at least one build time property so Quarkus can detect how to create the datasource. + +You will usually specify the `db-kind` property or explicitly enable Dev Services by setting `quarkus.datasource."name".devservices.enabled=true`. [[in-memory-databases]] -== Testing with in-memory databases +=== Testing with in-memory databases + +Some databases like H2 and Derby are commonly used in the _embedded mode_ as a facility to run integration tests quickly. -Some databases like H2 and Derby are commonly used in "embedded mode" as a facility to run quick integration tests. +It is recommended to use the real database you intend to use in production, but it’s possible to use JVM-powered databases for the scenarios when the ability to run quick integration tests is required. -Our suggestion is to use the real database you intend to use in production; container technologies made this simple enough so you no longer have an excuse. Still, there are sometimes -good reasons to also want the ability to run quick integration tests using the JVM powered databases, -so this is possible as well. +Note that while configuring Derby to use the embedded engine works as usual in JVM mode, such an application will not compile into a native executable, because the Quarkus extensions only cover making the JDBC client code compatible with the native compilation step. +Embedding the entire database engine into a native executable is currently not implemented. -It is important to remember that when configuring Derby to use the embedded engine, -this will work as usual in JVM mode but such an application will not compile into a native executable, as the Quarkus extensions only cover for making the JDBC client code compatible with the native compilation step: embedding the whole database engine into a native executable is currently not implemented. +==== Support and limitations -Compiling H2 into a native-image is now possible (it didn't use to be) but this is considered experimental; even if this is technically possible, -we would still recommend to consider carefully why you would want to embed H2 within your native-image. +Embedded databases (H2 and Derby) work in JVM mode. +For native mode, the following limitations apply: -If you plan to run such integration tests in the JVM exclusively, it will of course work as usual. +* Derby cannot be embedded into the application in native mode, and only remote connection is supported. +* H2 can be embedded into the application in native mode, but this is considered experimental. +We recommend carefully considering alternatives (remote connection to a separate database, etc.) before embedding H2 within your native image. -If you want the ability to run such integration test in both JVM and/or native executables, we have some cool helpers for you: just add either `@QuarkusTestResource(H2DatabaseTestResource.class)` or `@QuarkusTestResource(DerbyDatabaseTestResource.class)` on any class in your integration tests, this will make sure the test suite starts (and stops) the embedded database into a separate process as necessary to run your tests. +==== Run an integration test -These additional helpers are provided by the artifacts having Maven coordinates `io.quarkus:quarkus-test-h2` and `io.quarkus:quarkus-test-derby`, respectively for H2 and Derby. +. Add a dependency on the artifacts providing the additional tools that are under the following Maven coordinates: ++ +* `io.quarkus:quarkus-test-h2` for H2 +* `io.quarkus:quarkus-test-derby` for Derby -Follows an example for H2: ++ +This will allow you to test your application even when it is compiled into a native executable while the database will run as a JVM process. +. Add the following specific annotation on any class in your integration tests for running integration tests in both JVM or native executables: ++ +* `@QuarkusTestResource(H2DatabaseTestResource.class)` +* `@QuarkusTestResource(DerbyDatabaseTestResource.class)` ++ +This will make sure the test suite starts and stops the embedded database into a separate process as necessary to run your tests. ++ +.H2 example [source,java] ---- package my.app.integrationtests.db; @@ -511,154 +519,152 @@ public class TestResources { } ---- -This will allow you to test your application even when it's compiled into a native executable, -while the database will run in the JVM as usual. - -Connect to it using: - +. Connect to it using: ++ [source,properties] ---- quarkus.datasource.db-kind=h2 -quarkus.datasource.jdbc.url=jdbc:h2:mem:test +quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:test ---- +== References + [[configuration-reference]] -== Common Datasource Configuration Reference +=== Common Datasource Configuration Reference include::{generated-dir}/config/quarkus-datasource.adoc[opts=optional, leveloffset=+1] [[jdbc-configuration]] -== JDBC Configuration Reference +=== JDBC Configuration Reference include::{generated-dir}/config/quarkus-agroal.adoc[opts=optional, leveloffset=+1] [[jdbc-url]] -== JDBC URL Reference +=== JDBC URL Reference Each of the supported databases contains different JDBC URL configuration options. -Going into each of those options is beyond the scope of this document, -but the following section gives an overview of each database URL and a link to the official documentation. +The following section gives an overview of each database URL and a link to the official documentation. -=== DB2 +==== DB2 `jdbc:db2://[:]/[:=;[=;]]` Example:: `jdbc:db2://localhost:50000/MYDB:user=dbadm;password=dbadm;` -See the https://www.ibm.com/support/knowledgecenter/SSEPGG_11.5.0/com.ibm.db2.luw.apdv.java.doc/src/tpc/imjcc_r0052342.html[official documentation] for more detail on URL syntax and additional supported options. +For more information on URL syntax and additional supported options, see the link:https://www.ibm.com/support/knowledgecenter/SSEPGG_11.5.0/com.ibm.db2.luw.apdv.java.doc/src/tpc/imjcc_r0052342.html[official documentation]. -=== Derby +==== Derby `jdbc:derby:[//serverName[:portNumber]/][memory:]databaseName[;property=value[;property=value]]` Example:: `jdbc:derby://localhost:1527/myDB`, `jdbc:derby:memory:myDB;create=true` Derby is an embedded database. -It can run as a server, based on a file, or live completely in memory. +It can run as a server, based on a file, or run completely in memory. All of these options are available as listed above. -You can find more information at the https://db.apache.org/derby/docs/10.8/devguide/cdevdvlp17453.html#cdevdvlp17453[official documentation]. -=== H2 +For more information, see the link:https://db.apache.org/derby/docs/10.8/devguide/cdevdvlp17453.html#cdevdvlp17453[official documentation]. + +==== H2 `jdbc:h2:{ {.|mem:}[name] | [file:]fileName | {tcp|ssl}:[//]server[:port][,server2[:port]]/name }[;key=value...]` Example:: `jdbc:h2:tcp://localhost/~/test`, `jdbc:h2:mem:myDB` H2 is an embedded database. -It can run as a server, based on a file, or live completely in memory. +It can run as a server, based on a file, or run completely in memory. All of these options are available as listed above. -You can find more information at the https://h2database.com/html/features.html?highlight=url&search=url#database_url[official documentation]. -=== MariaDB +For more information, see the link:https://h2database.com/html/features.html?highlight=url&search=url#database_url[official documentation]. + +==== MariaDB `jdbc:mariadb:[replication:|failover:|sequential:|aurora:]//[,...]/[database][?=[&=]]` -hostDescription:: `[:] or address=(host=)[(port=)][(type=(master|slave))]` +hostDescription:: `[:] or address=(host=)[(port=)][(type=(master|slave))]` Example:: `jdbc:mariadb://localhost:3306/test` -You can find more information about this feature and others detailed in the https://mariadb.com/kb/en/library/about-mariadb-connector-j/[official documentation]. +For more information, see the link:https://mariadb.com/kb/en/library/about-mariadb-connector-j/[official documentation]. -=== Microsoft SQL Server +==== Microsoft SQL Server `jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]` Example:: `jdbc:sqlserver://localhost:1433;databaseName=AdventureWorks` The Microsoft SQL Server JDBC driver works essentially the same as the others. -More details can be found in the https://docs.microsoft.com/en-us/sql/connect/jdbc/connecting-to-sql-server-with-the-jdbc-driver?view=sql-server-2017[official documentation]. -=== MySQL +For more information, see the link:https://docs.microsoft.com/en-us/sql/connect/jdbc/connecting-to-sql-server-with-the-jdbc-driver?view=sql-server-2017[official documentation]. + +==== MySQL `jdbc:mysql:[replication:|failover:|sequential:|aurora:]//[,...]/[database][?=[&=]]` -hostDescription:: `[:] or address=(host=)[(port=)][(type=(master|slave))]` +hostDescription:: `[:] or address=(host=)[(port=)][(type=(master|slave))]` Example:: `jdbc:mysql://localhost:3306/test` -You can find more information about this feature and others detailed in the https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference.html[official documentation]. +For more information, see the link:https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference.html[official documentation]. -==== MySQL Limitations +===== MySQL Limitations -When compiling a Quarkus application to native-image, the MySQL support for JMX and Oracle Cloud Infrastructure (OCI) integrations are disabled as they are not compatible -with GraalVM native-images. -The lack of JMX support is a natural consequence of running in native and is unlikely to be resolved. -The integration with OCI could be resolved, if you need it we suggest opening a support request with the MySQL Connector/J maintainers. +When compiling a Quarkus application to a native image, the MySQL support for JMX and Oracle Cloud Infrastructure (OCI) integrations are disabled as they are incompatible with GraalVM native images. -=== Oracle +* The lack of JMX support is a natural consequence of running in native mode and is unlikely to be resolved. +* The integration with OCI is not supported. + +==== Oracle `jdbc:oracle:driver_type:@database_specifier` Example:: `jdbc:oracle:thin:@localhost:1521/ORCL_SVC` -More details can be found in the https://docs.oracle.com/en/database/oracle/oracle-database/21/jjdbc/data-sources-and-URLs.html#GUID-AEA8E228-1B21-4111-AF4C-B1F33744CA08[official documentation]. - -=== PostgreSQL +For more information, see the link:https://docs.oracle.com/en/database/oracle/oracle-database/21/jjdbc/data-sources-and-URLs.html#GUID-AEA8E228-1B21-4111-AF4C-B1F33744CA08[official documentation]. -PostgreSQL only runs as a server, as do the rest of the databases below. -As such, you must specify connection details, or use the defaults. +==== PostgreSQL `jdbc:postgresql:[//][host][:port][/database][?key=value...]` Example:: `jdbc:postgresql://localhost/test` -Defaults for the different parts are as follows: +The defaults for the different parts are as follows: `host`:: localhost `port`:: 5432 `database`:: same name as the username -The https://jdbc.postgresql.org/documentation/head/connect.html[official documentation] go into more detail and list optional parameters as well. +For more information about additional parameters, see the link:https://jdbc.postgresql.org/documentation/head/connect.html[official documentation]. [[reactive-configuration]] -== Reactive Datasource Configuration Reference +=== Reactive Datasource Configuration Reference include::{generated-dir}/config/quarkus-reactive-datasource.adoc[opts=optional, leveloffset=+1] -=== Reactive DB2 Configuration +==== Reactive DB2 Configuration include::{generated-dir}/config/quarkus-reactive-db2-client.adoc[opts=optional, leveloffset=+1] -=== Reactive MariaDB/MySQL Specific Configuration +==== Reactive MariaDB/MySQL Specific Configuration include::{generated-dir}/config/quarkus-reactive-mysql-client.adoc[opts=optional, leveloffset=+1] -=== Reactive Microsoft SQL Server Specific Configuration +==== Reactive Microsoft SQL Server-Specific Configuration include::{generated-dir}/config/quarkus-reactive-mssql-client.adoc[opts=optional, leveloffset=+1] -=== Reactive Oracle Specific Configuration +==== Reactive Oracle-Specific Configuration include::{generated-dir}/config/quarkus-reactive-oracle-client.adoc[opts=optional, leveloffset=+1] -=== Reactive PostgreSQL Specific Configuration +==== Reactive PostgreSQL Specific Configuration include::{generated-dir}/config/quarkus-reactive-pg-client.adoc[opts=optional, leveloffset=+1] [[reactive-url]] -== Reactive Datasource URL Reference +=== Reactive Datasource URL Reference -=== DB2 +==== DB2 `db2://[user[:[password]]@]host[:port][/database][?=[&=]]` @@ -672,9 +678,9 @@ Currently, the client supports the following parameter keys: * `password` * `database` -NOTE: Configuring parameters in connection URL will override the default properties. +NOTE: Configuring parameters in the connection URL overrides the default properties. -=== Microsoft SQL Server +==== Microsoft SQL Server `sqlserver://[user[:[password]]@]host[:port][/database][?=[&=]]` @@ -688,9 +694,9 @@ Currently, the client supports the following parameter keys: * `password` * `database` -NOTE: Configuring parameters in connection URL will override the default properties. +NOTE: Configuring parameters in the connection URL overrides the default properties. -=== MySQL / MariaDB +==== MySQL / MariaDB `mysql://[user[:[password]]@]host[:port][/database][?=[&=]]` @@ -706,40 +712,42 @@ Currently, the client supports the following parameter keys (case-insensitive): * `socket` * `useAffectedRows` -NOTE: Configuring parameters in connection URL will override the default properties. +NOTE: Configuring parameters in the connection URL overrides the default properties. -=== Oracle +==== Oracle -==== EZConnect Format +===== EZConnect Format `oracle:thin:@[[protocol:]//]host[:port][/service_name][:server_mode][/instance_name][?connection properties]` Example:: `oracle:thin:@mydbhost1:5521/mydbservice?connect_timeout=10sec` -==== TNS Alias Format +===== TNS Alias Format `oracle:thin:@[?connection properties]` Example:: `oracle:thin:@prod_db?TNS_ADMIN=/work/tns/` -=== PostgreSQL +==== PostgreSQL `postgresql://[user[:[password]]@]host[:port][/database][?=[&=]]` Example:: `postgresql://dbuser:secretpassword@database.server.com:5432/mydb` -Currently, the client supports the following parameter keys: +Currently, the client supports: -* `host` -* `port` -* `user` -* `password` -* `dbname` -* `sslmode` -* additional properties, including: +* Following parameter keys: +** `host` +** `port` +** `user` +** `password` +** `dbname` +** `sslmode` + +* Additional properties, such as: ** `application_name` ** `fallback_application_name` ** `search_path` ** `options` -NOTE: Configuring parameters in connection URL will override the default properties. +NOTE: Configuring parameters in the connection URL overrides the default properties.