Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[3.15] doc backports #43421

Merged
merged 3 commits into from
Sep 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 57 additions & 83 deletions docs/src/main/asciidoc/datasource.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,19 @@
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, scalable data source connection pooling for JDBC and reactive drivers.
The `quarkus-jdbc-\*` and `quarkus-reactive-*-client` extensions provide build time optimizations and integrate configured data sources with Quarkus features like security, health checks, and metrics.
Quarkus uses link:https://agroal.github.io/[Agroal] and link:https://vertx.io/[Vert.x] to provide high-performance, scalable datasource connection pooling for JDBC and reactive drivers.
The `quarkus-jdbc-\*` and `quarkus-reactive-*-client` extensions provide build time optimizations and integrate configured datasources with Quarkus features like security, health checks, and metrics.

For more information about consuming and using a reactive datasource, see the Quarkus xref:reactive-sql-clients.adoc[Reactive SQL clients] guide.

Check warning on line 28 in docs/src/main/asciidoc/datasource.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/datasource.adoc", "range": {"start": {"line": 28, "column": 41}}}, "severity": "INFO"}

Additionally, refer to the Quarkus xref:hibernate-orm.adoc[Hibernate ORM] guide for information on consuming and using a JDBC datasource.


== Get started with configuring `datasources` in Quarkus

For users familiar with the fundamentals, this section provides an overview and code samples to set up data sources quickly.
For users familiar with the fundamentals, this section provides an overview and code samples to set up datasources quickly.

For more advanced configuration with examples, see <<datasource-reference>>.

Check warning on line 37 in docs/src/main/asciidoc/datasource.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/datasource.adoc", "range": {"start": {"line": 37, "column": 57}}}, "severity": "INFO"}

[[dev-services]]
=== Zero-config setup in development mode
Expand All @@ -48,7 +48,8 @@
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 use 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.
To use 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 "Configuration reference" guide.
Expand All @@ -73,7 +74,7 @@

. Configure your JDBC datasource:
+
[source, properties]
[source,properties]
----
quarkus.datasource.db-kind=postgresql <1>
quarkus.datasource.username=<your username>
Expand Down Expand Up @@ -111,7 +112,7 @@

. Configure your reactive datasource:
+
[source, properties]
[source,properties]
----
quarkus.datasource.db-kind=postgresql <1>
quarkus.datasource.username=<your username>
Expand All @@ -133,9 +134,9 @@
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, where `db-kind` defines which database platform to connect to, for example, `h2`:

Check warning on line 137 in docs/src/main/asciidoc/datasource.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/datasource.adoc", "range": {"start": {"line": 137, "column": 89}}}, "severity": "INFO"}
+
[source, properties]
[source,properties]
----
quarkus.datasource.db-kind=h2
----
Expand Down Expand Up @@ -167,7 +168,7 @@

. Configure the following properties to define credentials:
+
[source, properties]
[source,properties]
----
quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>
Expand Down Expand Up @@ -231,7 +232,7 @@

. Configure the JDBC connection by defining the JDBC URL property:
+
[source, properties]
[source,properties]
----
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
----
Expand All @@ -258,19 +259,20 @@

[WARNING]
====
OpenTracing has been deprecated in favor of OpenTelemetry. For tracing information, please check the related section about <<datasource-tracing>>, bellow.
OpenTracing has been deprecated in favor of OpenTelemetry.
For tracing information, please check the related section about <<datasource-tracing>>, bellow.
====

.A custom driver definition example with the legacy OpenTracing driver:

[source, properties]
[source,properties]
----
quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver
----

.An example for defining access to a database with no built-in support in JVM mode:

[source, properties]
[source,properties]
----
quarkus.datasource.db-kind=other
quarkus.datasource.jdbc.driver=oracle.jdbc.driver.OracleDriver
Expand Down Expand Up @@ -332,31 +334,30 @@
For more information about pool size adjustment properties, see the <<reactive-configuration>> section.

[[jdbc-and-reactive-datasources-simultaneously]]
==== JDBC and reactive datasources simultaneously

Check warning on line 337 in docs/src/main/asciidoc/datasource.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'JDBC and reactive datasources simultaneously'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'JDBC and reactive datasources simultaneously'.", "location": {"path": "docs/src/main/asciidoc/datasource.adoc", "range": {"start": {"line": 337, "column": 6}}}, "severity": "INFO"}

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.

If you want to use them both,
make sure to set both <<jdbc-datasource,JDBC>> and <<reactive-datasource,reactive>> configuration,
for example:
When both a JDBC extension and a reactive datasource extension for the same database kind are included, both JDBC and reactive datasources will be created by default.

* To use the <<jdbc-datasource,JDBC>> and <<reactive-datasource,reactive>> datasources simultaneously:
+
[source,properties]
----
%prod.quarkus.datasource.reactive.url=postgresql:///your_database
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
----

If you do not want to have both a JDBC datasource and a reactive datasource created, use the following configuration.

* To disable the JDBC datasource explicitly:
+
[source, properties]
[source,properties]
----
quarkus.datasource.jdbc=false
----

* To disable the reactive datasource explicitly:
+
[source, properties]
[source,properties]
----
quarkus.datasource.reactive=false
----
Expand Down Expand Up @@ -429,26 +430,23 @@
----

[[datasource-active]]
=== Activate/deactivate datasources
=== Activate or deactivate datasources

If a datasource is configured at build time,
by default it is active at runtime,
that is Quarkus will start the corresponding JDBC connection pool or reactive client on application startup.
When a datasource is configured at build time, it is active by default at runtime.
This means that Quarkus will start the corresponding JDBC connection pool or reactive client when the application starts.

To deactivate a datasource at runtime, set `quarkus.datasource[.optional name].active` to `false`.
Then Quarkus will not start the corresponding JDBC connection pool or reactive client on application startup.
Any attempt to use the corresponding datasource at runtime will fail with a clear error message.
Quarkus will then skip starting the JDBC connection pool or reactive client during application startup.
Any attempt to use the deactivated datasource at runtime results in an exception.

This is in particular useful when you want an application to be able
to use one of a pre-determined set of datasources at runtime.
This feature is especially useful when you need the application to select one datasource from a predefined set at runtime.

[WARNING]
====
If another Quarkus extension relies on an inactive datasource,
that extension might fail to start.
If another Quarkus extension relies on an inactive datasource, that extension might fail to start.
In such case, you will need to deactivate that other extension too.
For example see xref:hibernate-orm.adoc#persistence-unit-active[here for Hibernate ORM].
In such a case, you will need to deactivate that other extension as well.
For an example of this scenario, see the xref:hibernate-orm.adoc#persistence-unit-active[Hibernate ORM] section.
====

For example, with the following configuration:
Expand All @@ -464,10 +462,7 @@
quarkus.datasource."oracle".jdbc.url=jdbc:oracle:///your_database
----

Setting `quarkus.datasource."pg".active=true` xref:config-reference.adoc#configuration-sources[at runtime]
will make only the PostgreSQL datasource available,
and setting `quarkus.datasource."oracle".active=true` at runtime
will make only the Oracle datasource available.
Setting `quarkus.datasource."pg".active=true` xref:config-reference.adoc#configuration-sources[at runtime] will make only the PostgreSQL datasource available, and setting `quarkus.datasource."oracle".active=true` at runtime will make only the Oracle datasource available.

[TIP]
====
Expand All @@ -491,8 +486,7 @@

[TIP]
====
It can also be useful to define a xref:cdi.adoc#ok-you-said-that-there-are-several-kinds-of-beans[CDI bean producer] redirecting to the currently active datasource,
like this:
It can also be useful to define a xref:cdi.adoc#ok-you-said-that-there-are-several-kinds-of-beans[CDI bean producer] redirecting to the currently active datasource, like this:
[source,java,indent=0]
----
Expand Down Expand Up @@ -524,10 +518,9 @@
[[datasource-multiple-single-transaction]]
=== Use multiple datasources in a single transaction

By default, XA support on datasources is disabled,
and thus a transaction may include at most one datasource.
Attempting to access multiple non-XA datasources in the same transaction
would result in an exception similar to this:
By default, XA support on datasources is disabled.
Therefore, a transaction may include no more than one datasource.
Attempting to access multiple non-XA datasources in the same transaction results in an exception similar to the following:

[source]
----
Expand All @@ -543,11 +536,9 @@
To allow using multiple JDBC datasources in the same transaction:

. Make sure your JDBC driver supports XA.
All <<extensions-and-database-drivers-reference,supported JDBC drivers do>>,
but <<other-databases,other JDBC drivers>> might not.
All <<extensions-and-database-drivers-reference,supported JDBC drivers do>>, but <<other-databases,other JDBC drivers>> might not.
. Make sure your database server is configured to enable XA.
. Enable XA support explicitly for each relevant datasource by setting
<<quarkus-agroal_quarkus-datasource-jdbc-transactions,`quarkus.datasource[.optional name].jdbc.transactions`>> to `xa`.
. Enable XA support explicitly for each relevant datasource by setting <<quarkus-agroal_quarkus-datasource-jdbc-transactions,`quarkus.datasource[.optional name].jdbc.transactions`>> to `xa`.

Using XA, a rollback in one datasource will trigger a rollback in every other datasource enrolled in the transaction.

Expand All @@ -558,44 +549,28 @@

[NOTE]
====
If your transaction involves other, non-datasource resources,
keep in mind *those* resources might not support XA transactions,
or might require additional configuration.
If your transaction involves non-datasource resources, be aware that they might not support XA transactions or might require additional configuration.
====

If XA cannot be enabled for one of your datasources:

* Be aware that enabling XA for all datasources _except one_ (and only one) is still supported
through https://www.narayana.io/docs/project/index.html#d5e857[Last Resource Commit Optimization (LRCO)].
* If you do not need a rollback for one datasource to trigger a rollback for other datasources,
consider splitting your code into multiple transactions.
To that end, use xref:transaction.adoc#programmatic-approach[`QuarkusTransaction.requiringNew()`]/xref:transaction.adoc#declarative-approach[`@Transactional(REQUIRES_NEW)`] (preferably)
or xref:transaction.adoc#legacy-api-approach[`UserTransaction`] (for more complex use cases).
* Be aware that enabling XA for all datasources _except one_ (and only one) is still supported through https://www.narayana.io/docs/project/index.html#d5e857[Last Resource Commit Optimization (LRCO)].
* If you do not need a rollback for one datasource to trigger a rollback for other datasources, consider splitting your code into multiple transactions.
To do so, use xref:transaction.adoc#programmatic-approach[`QuarkusTransaction.requiringNew()`]/xref:transaction.adoc#declarative-approach[`@Transactional(REQUIRES_NEW)`] (preferably) or xref:transaction.adoc#legacy-api-approach[`UserTransaction`] (for more complex use cases).

[CAUTION]
====
As a last resort, and for compatibility with Quarkus 3.8 and earlier,
you may allow unsafe transaction handling across multiple non-XA datasources
by setting `quarkus.transaction-manager.unsafe-multiple-last-resources` to `allow`.
With this property set to `allow`, a transaction rollback
could possibly be applied to only some of the non-XA datasources,
with other non-XA datasources having already committed their changes,
leaving your overall system in an inconsistent state.
Alternatively, you can allow the same unsafe behavior,
but with warnings when it is taken advantage of:
* setting the property to `warn-each`
would result in logging a warning on *each* offending transaction.
* setting the property to `warn-first`
would result in logging a warning on the *first* offending transaction.
We do not recommend using this configuration property,
and we plan to remove it in the future,
so you should plan fixing your application accordingly.
If you think your use case of this feature is valid and this option should be kept around,
open an issue in the https://github.com/quarkusio/quarkus/issues/new?assignees=&labels=kind%2Fenhancement&projects=&template=feature_request.yml[Quarkus tracker]
If no other solution works, and to maintain compatibility with Quarkus 3.8 and earlier, set `quarkus.transaction-manager.unsafe-multiple-last-resources` to `allow` to enable unsafe transaction handling across multiple non-XA datasources.
With this property set to allow, it might happen that a transaction rollback will only be applied to the last non-XA datasource, while other non-XA datasources have already committed their changes, potentially leaving your overall system in an inconsistent state.
Alternatively, you can allow the same unsafe behavior, but with warnings when it takes effect:
* Setting the property to `warn-each` results in logging a warning on *each* offending transaction.
* Setting the property to `warn-first` results in logging a warning on the *first* offending transaction.
We do not recommend using this configuration property, and we plan to remove it in the future, so you should fix your application accordingly.
If you think your use case of this feature is valid and this option should be kept around, open an issue in the link:https://github.com/quarkusio/quarkus/issues/new?assignees=&labels=kind%2Fenhancement&projects=&template=feature_request.yml[Quarkus tracker]
explaining why.
====

Expand All @@ -610,7 +585,7 @@

This behavior can be disabled by using the `quarkus.datasource.health.enabled` property.

To exclude only a particular datasource from the health check, use:
To exclude only a particular datasource from the health check:

[source,properties]
----
Expand All @@ -625,8 +600,7 @@
For the exposed metrics to contain any actual values, a metric collection must be enabled internally by the 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.

To disable metrics for a particular data source,
set `quarkus.datasource.jdbc.enable-metrics` to `false`, or apply `quarkus.datasource.<datasource name>.jdbc.enable-metrics` for a named datasource.
To disable metrics for a particular datasource, set `quarkus.datasource.jdbc.enable-metrics` to `false`, or apply `quarkus.datasource.<datasource name>.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.<datasource name>.jdbc.enable-metrics` for a named datasource explicitly enables metrics collection even if a metrics extension is not in use.
Expand All @@ -640,10 +614,11 @@

To use tracing with a datasource, you need to add the xref:opentelemetry-tracing.adoc[`quarkus-opentelemetry`] extension to your project.

You don't need to declare a different driver because you need tracing. If you use a JDBC driver, you need to follow the instructions in the OpenTelemetry extension xref:opentelemetry-tracing.adoc#jdbc[here].
You do not need to declare a different driver to enable tracing.
If you use a JDBC driver, you need to follow xref:opentelemetry-tracing.adoc#jdbc[the instructions in the OpenTelemetry extension].

Even with all the tracing infrastructure in place the datasource tracing is not enabled by default, and you need to enable it by setting this property:
[source, properties]
Even with all the tracing infrastructure in place, the datasource tracing is not enabled by default, and you need to enable it by setting this property:
[source,properties]
----
# enable tracing
quarkus.datasource.jdbc.telemetry=true
Expand Down Expand Up @@ -676,7 +651,6 @@
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.


==== Support and limitations

Embedded databases (H2 and Derby) work in JVM mode.
Expand Down
Loading
Loading