diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index 6a8c0cd15c9cb9..61039732764bfb 100644 --- a/docs/src/main/asciidoc/datasource.adoc +++ b/docs/src/main/asciidoc/datasource.adoc @@ -3,62 +3,66 @@ This guide is maintained in the main Quarkus repository and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// -= Datasources +[id="datasources"] += Get started with configuring datasources in Quarkus include::_attributes.adoc[] -:categories: data -:summary: With Quarkus, you can easily configure a datasource, or several if need be. +:categories: data,getting-started -Many projects that use data require connections to a relational database. +Learn how to easily configure a Java Database Connectivity (JDBC) and Reactive datasource, their combination, or several datasources if required. -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. +Many Java applications require connections to a relational database. +The usual way to establish database connections is to combine a data source and a database driver. -Quarkus has you covered either way: +Quarkus supports JDBC and reactive drivers and allows for unified and flexible configurations. -* 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 lightweight link:https://agroal.github.io/[Agroal] datasource and connection pooling implementation for JDBC, as well as link: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, health checks, and metrics. -Both are configured via unified and flexible configuration. +For more details about consuming and using a reactive datasource, +refer to the xref:reactive-sql-clients.adoc[Reactive SQL clients] guide. -[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. -==== +Datasource guide then explains the following: -This guide will explain how to: +* Configuring a datasource or multiple datasources +* Obtaining a reference to those datasources in the code +* Enabling metrics and health checks for datasources + +//// +Future references to all other parts of this doc. +//// -* configure a datasource, or multiple datasources -* how to obtain a reference to those datasources in code -* which pool tuning configuration properties are available -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]. +== Get started with configuring `datasources` in Quarkus -== TL;DR +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. -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. +For the advanced configuration with examples, see xref:datasource-reference[Datasource references]. [[dev-services]] -=== Zero Config Setup (Dev Services) +=== Zero-config setup in development mode -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. -=== JDBC datasource +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. -Add the `agroal` extension plus one of `jdbc-db2`, `jdbc-derby`, `jdbc-h2`, `jdbc-mariadb`, `jdbc-mssql`, `jdbc-mysql`, `jdbc-oracle` or `jdbc-postgresql`. +For more details and optional configurations, see xref:databases-dev-services.adoc[Databases Dev Services]. + +=== JDBC datasource -Then configure your 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`. +. Configure your datasource as follows: ++ [source, properties] ---- quarkus.datasource.db-kind=postgresql <1> @@ -68,17 +72,22 @@ 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 added, 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] ---- quarkus.datasource.db-kind=postgresql <1> @@ -88,25 +97,33 @@ quarkus.datasource.password= quarkus.datasource.reactive.url=postgresql:///your_database quarkus.datasource.reactive.max-size=20 ---- -<1> As specified above this is optional. +<1> If you only have a single Reactive driver extension or are running tests and only have a single test-scoped Reactive driver extension added, then this is optional. -== Default datasource +== Configure datasources -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. +The following section describes the configuration for single or multiple datasources. +For simplicity, we will reference a single datasource as the default (unnamed) datasource. -To define a datasource, start with the following (note that this is only required if you have more than one -database type installed): +=== Configure a single datasource +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 configuration property: ++ [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 only if your application depends on more than one database driver. +If the application operates with a single driver, this driver is detected automatically. ++ +The database kind defines to which type of database you will connect. +In particular, Quarkus deduces the JDBC driver class it needs to use from the database kind. ++ +Quarkus currently includes these built-in database kinds: ++ * DB2: `db2` * Derby: `derby` * H2: `h2` @@ -115,176 +132,116 @@ 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. -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. - +* 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 define 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. - -==== Install the Maven dependencies +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. -First, you will need to add the `quarkus-agroal` dependency to your project. +==== JDBC datasource -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` ++ +[NOTE] +==== +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 <> for suggestions regarding integration testing. +==== +* DB2 - `jdbc-db2` * MariaDB - `jdbc-mariadb` * Microsoft SQL Server - `jdbc-mssql` * MySQL - `jdbc-mysql` * Oracle - `jdbc-oracle` * PostgreSQL - `jdbc-postgresql` +* 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 https://github.com/quarkiverse[Quarkiverse]. +To use a JDBC driver for another database, <>. -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] - -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. - -Read <> (below) 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: - +. Add the extension to your application using the `add-extension` command. ++ +For example, to add 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. -==== - -[TIP] -==== -For more information about the JDBC URL format, please refer to the <>. +All the configuration properties specific to JDBC have the `jdbc` prefix. +For reactive datasources, the prefix is `reactive`. ==== -When using one of the built-in datasource kinds, the JDBC driver is resolved automatically to the following values: - -.Database kind to JDBC driver mapping -|=== -|Database kind |JDBC driver |XA driver - -|`db2` -|`com.ibm.db2.jcc.DBDriver` -|`com.ibm.db2.jcc.DB2XADataSource` - -|`derby` -|`org.apache.derby.jdbc.ClientDriver` -|`org.apache.derby.jdbc.ClientXADataSource` - -|`h2` -|`org.h2.Driver` -|`org.h2.jdbcx.JdbcDataSource` +.References -|`mariadb` -|`org.mariadb.jdbc.Driver` -|`org.mariadb.jdbc.MySQLDataSource` +* <> +* <> -|`mssql` -|`com.microsoft.sqlserver.jdbc.SQLServerDriver` -|`com.microsoft.sqlserver.jdbc.SQLServerXADataSource` -|`mysql` -|`com.mysql.cj.jdbc.Driver` -|`com.mysql.cj.jdbc.MysqlXADataSource` - -|`oracle` -|`oracle.jdbc.driver.OracleDriver` -|`oracle.jdbc.xa.client.OracleXADataSource` - -|`postgresql` -|`org.postgresql.Driver` -|`org.postgresql.xa.PGXADataSource` -|=== - -[TIP] -==== -As previously stated, most of the time, this automatic resolution will suit you and -you won't need to configure the driver. -==== [[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 +252,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. +For all the details about the JDBC configuration options and configuring other aspects, +such as the connection pool size, refer to the <> section. -Please refer to the <> for all the details about the JDBC configuration knobs. +===== Consuming the datasource -==== Consuming the datasource - -If you are using Hibernate ORM, the datasource will be consumed automatically. - -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 up the datasource and uses 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. +. Add the corresponding extension to your application: ++ * 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 adding 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 +=== Configure multiple datasources -=== Configuring 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 +355,18 @@ 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 -specify Dev Services properties to create named datasources (covered later in this guide). +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 according to the xref:databases-dev-services.adoc[Dev Services for Databases] 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 +381,91 @@ AgroalDataSource usersDataSource; AgroalDataSource inventoryDataSource; ---- -== Datasource Health Check +== Datasource integrations + +=== Datasource health check -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. +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. -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. +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`. + +This behavior can be disabled by using the `quarkus.datasource.health.enabled` property. + +To exclude only a particular datasource from the health check, use: + +[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. + +If the metrics collection for this datasource is disabled, all values result to zero. + +=== Narayana transaction manager integration -== Narayana Transaction Manager integration +Integration is automatic if the Narayana JTA extension is also available. -If the Narayana JTA extension is also available, integration is automatic. +You can override this by setting the `transactions` configuration property. +See the <> section below. -You can override this by setting the `transactions` configuration property - see the <> below. +==== Named datasources -=== 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. -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`. +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 "embedded mode" as a facility to run quick integration tests. +Some databases like H2 and Derby are commonly used in the _embedded mode_ as a facility to run integration tests quickly. -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. +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. -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. +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. -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. +==== Support and limitations -If you plan to run such integration tests in the JVM exclusively, it will of course work as usual. +Embedded databases (H2 and Derby) work in JVM mode. +For native mode, the following limitations apply: -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. +* 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. -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. +==== Run an integration test -Follows an example for H2: +. 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 ++ +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 +478,247 @@ 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 ---- +[[datasource-reference]] +== 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]. + + +[[extensions-and-database-drivers-reference]] +=== Quarkus extensions and database drivers reference + +The below tables list the built-in db-kind values, the corresponding Quarkus extensions, and the JDBC drivers used by those extensions. + +When using one of the built-in datasource kinds, the JDBC and Reactive drivers are resolved automatically to match the values from these tables. + +.Database kind to JDBC driver mapping +[options="header",cols="^10%,^25%,65%"] +|=== +|Database kind |Quarkus extension |Drivers + +|`db2` +|`quarkus-jdbc-db2` +a|* JDBC: `com.ibm.db2.jcc.DBDriver` + +* XA: `com.ibm.db2.jcc.DB2XADataSource` + +|`derby` +|`quarkus-jdbc-derby` +a|* JDBC: `org.apache.derby.jdbc.ClientDriver` + +* XA: `org.apache.derby.jdbc.ClientXADataSource` + +|`h2` +|`quarkus-jdbc-h2` +a|* JDBC: `org.h2.Driver` + +* XA: `org.h2.jdbcx.JdbcDataSource` + +|`mariadb` +|`quarkus-jdbc-mariadb` +a|* JDBC: `org.mariadb.jdbc.Driver` + +* XA: `org.mariadb.jdbc.MySQLDataSource` + +|`mssql` +|`quarkus-jdbc-mssql` +a|* JDBC: `com.microsoft.sqlserver.jdbc.SQLServerDriver` + +* XA: `com.microsoft.sqlserver.jdbc.SQLServerXADataSource` + +|`mysql` +|`quarkus-jdbc-mysql` +a|* JDBC: `com.mysql.cj.jdbc.Driver` + +* XA: `com.mysql.cj.jdbc.MysqlXADataSource` + +|`oracle` +|`quarkus-jdbc-oracle` +a|* JDBC: `oracle.jdbc.driver.OracleDriver` + +* XA: `oracle.jdbc.xa.client.OracleXADataSource` + +|`postgresql` +|`quarkus-jdbc-postgresql` +a|* JDBC: `org.postgresql.Driver` + +* XA: `org.postgresql.xa.PGXADataSource` +|=== + + +.Database kind to Reactive driver mapping +[options="header",cols="^10%,^25%,65%"] +|=== +|Database kind |Quarkus extension |Driver + +|`oracle` +|`reactive-oracle-client` +|`io.vertx.oracleclient.spi.OracleDriver` + +|`mysql` +|`reactive-mysql-client` +|`io.vertx.mysqlclient.spi.MySQLDriver` + +|`mssql` +|`reactive-mssql-client` +|`io.vertx.mssqlclient.spi.MSSQLDriver` + +|`postgresql` +|`reactive-pg-client` +|`io.vertx.pgclient.spi.PgDriver` + +|`db2` +|`reactive-db2-client` +|`io.vertx.db2client.spi.DB2Driver` +|=== + +[TIP] +==== +This automatic resolution is applicable in most cases so that driver configuration is not needed. +==== [[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 +732,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 +748,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 +766,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.