Merge pull request #34699 from MichalMaler/QUARKUS-2998-JDBCStore-tra…

…nsaction-logs-support

Documenting a possibility to store transaction logs to a database

docs/src/main/asciidoc/datasource.adoc

@@ -110,6 +110,7 @@ quarkus.datasource.reactive.max-size=20
 ----
 <1> This configuration value is only required if there is more than one Reactive driver extension on the classpath.
 
+[[configure-datasources]]
 == Configure datasources
 
 The following section describes the configuration for single or multiple datasources.
@@ -431,7 +432,9 @@ You can override this by setting the `transactions` configuration property:
 * `quarkus.datasource.jdbc.transactions` for default unnamend datasource
 * `quarkus.datasource._<datasource-name>_.jdbc.transactions` for named datasource
 
-See the <<configuration-reference,Configuration Reference>> section below.
+For more information, see the <<configuration-reference,Configuration reference>> section below.
+
+To facilitate the storage of transaction logs in a database by using JDBC, see xref:transaction.adoc#jdbcstore[Configuring transaction logs to be stored in a datasource] section of the xref:transaction.adoc[Using transactions in Quarkus] guide.
 
 ==== Named datasources
 

docs/src/main/asciidoc/transaction.adoc

@@ -362,15 +362,36 @@ NOTE: The `event` object represents the transaction ID, and defines `toString()`
 TIP: In listener methods, you can access more information about the transaction in progress by accessing the `TransactionManager`,
 which is a CDI bean and can be ``@Inject``ed.
 
-== Configuring transaction log to be stored in a DataSource
+[[jdbcstore]]
+== Configure storing of Quarkus transaction logs in a database
 
-The Narayana project has the capability to store the transaction logs into a JDBC Datasource; this should be our recommendation for users needing transaction recovery capabilities, especially when running in volatile containers.
+In cloud environments where persistent storage is not available, such as when application containers are unable to use persistent volumes, you can configure the transaction management to store transaction logs in a database by using a JDBC datasource.
 
-To enable this capability, you need to set `quarkus.transaction-manager.object-store.type` to `jdbc` explicitly. Also, you can specify a datasource name to be used for the transaction log storage by setting `quarkus.transaction-manager.object-store.datasource`. It will use the default datasource configuration if not specified.
+IMPORTANT: While there are several benefits to using a database to store transaction logs, you might notice a reduction in performance compared with using the file system to store the logs.
 
-If you enable `quarkus.transaction-manager.object-store.create-table`, the transaction log table will be created automatically if it does not exist.
+Quarkus allows the following JDBC-specific configuration of the object store included in `quarkus.transacion-manager.object-store.<property>` properties, where <property> can be:
 
-NOTE: When enabling this capability, the transaction node identifier must be set through `quarkus.transaction-manager.node-name`.
+* `type` (_string_): Configure this property to `jdbc` to enable usage of a Quarkus JDBC datasource for transaction logging.
+The default value is `file-system`.
+* `datasource` (_string_): Specify the name of the datasource for the transaction log storage.
+If no value is provided for the `datasource` property, Quarkus uses the xref:datasource.adoc#configure-datasources[default datasource].
+* `create-table` (_boolean_): When set to `true`, the transaction log table gets automatically created if it does not already exist.
+The default value is `false`.
+* `drop-table` (_boolean_): When set to `true`, the tables are dropped on startup if they already exist.
+The default value is `false`.
+* `table-prefix` (string): Specify the prefix for a related table name.
+The default value is `quarkus_`.
+
+[NOTE]
+====
+To work around the current known issue of link:https://issues.redhat.com/browse/AG-209[Agroal having a different view on running transaction checks], set the datasource transaction type for the datasource responsible for writing the transaction logs to `disabled`:
+
+----
+quarkus.datasource.TX_LOG.jdbc.transactions=disabled
+----
+
+This example uses TX_LOG as the datasource name.
+====
 
 
 == Why always having a transaction manager?