Add the ability to disable datasource recovery

docs/src/main/asciidoc/datasource.adoc

@@ -680,6 +680,8 @@ You can override this by setting the `transactions` configuration property:
 * `quarkus.datasource.jdbc.transactions` for default unnamed datasource
 * `quarkus.datasource._<datasource-name>_.jdbc.transactions` for named datasource
 
+When a datasource is enabled for XA (by setting `quarkus.datasource[.optional name].jdbc.transactions to xa)` and the transaction recovery system is enabled (by setting the property `quarkus.transaction-manager.enable-recovery` to true) then the datasource is automatically registered for recovery. This is a safe default, but you can override this behaviour on a per-datasource basis by setting `quarkus.datasource.jdbc.enable-recovery`/`quarkus.datasource."datasource-name".jdbc.enable-recovery` to `false`. Only use this for advanced use cases and if you know recovery will not be necessary, otherwise it may result in data loss and/or data unavailability because resources may become locked indefinitely.
+
 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.

extensions/agroal/deployment/src/test/java/io/quarkus/agroal/test/XaDataSourceConfigTest.java

@@ -0,0 +1,69 @@
+package io.quarkus.agroal.test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.sql.SQLException;
+
+import jakarta.enterprise.context.control.ActivateRequestContext;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.agroal.api.AgroalDataSource;
+import io.agroal.api.configuration.AgroalConnectionPoolConfiguration;
+import io.agroal.narayana.NarayanaTransactionIntegration;
+import io.quarkus.agroal.DataSource;
+import io.quarkus.narayana.jta.QuarkusTransaction;
+import io.quarkus.test.QuarkusUnitTest;
+
+public class XaDataSourceConfigTest {
+
+    //tag::injection[]
+    @Inject
+    @DataSource("xa")
+    AgroalDataSource xaRecoverDS;
+
+    @Inject
+    @DataSource("xaNoRecover")
+    AgroalDataSource xaNoRecoverDS;
+    //end::injection[]
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withConfigurationResource("application-recovery-datasources.properties");
+
+    @Test
+    @ActivateRequestContext
+    public void testEnlistDatasourcesWithRecovery() throws SQLException {
+        AgroalConnectionPoolConfiguration xaRecoverConfig = xaRecoverDS.getConfiguration().connectionPoolConfiguration();
+        AgroalConnectionPoolConfiguration xaNoRecoverConfig = xaNoRecoverDS.getConfiguration().connectionPoolConfiguration();
+
+        assertTrue(xaRecoverConfig.recoveryEnable(), "xaRecoverDS datasource should have recover enabled");
+        assertFalse(xaNoRecoverConfig.recoveryEnable(), "xaNoRecoverDS datasource should not have recover enabled");
+
+        assertInstanceOf(NarayanaTransactionIntegration.class, xaRecoverConfig.transactionIntegration(),
+                "Agroal transaction integration should use Narayana for xaRecoverDS");
+        assertInstanceOf(NarayanaTransactionIntegration.class, xaNoRecoverConfig.transactionIntegration(),
+                "Agroal transaction integration should use Narayana for xaNoRecoverDS");
+
+        // run a transaction and use the two datasources, ensuring that it commits ok
+        QuarkusTransaction.begin();
+
+        // Remark: the two datasources will have been registered with the transaction recovery system because the config
+        // includes quarkus.transaction-manager.enable-recovery=true
+        // see QuarkusRecoveryService for details of how the recovery service manages connections to datasources
+        try (var conn = xaRecoverDS.getConnection()) {
+            assertFalse(conn.getAutoCommit(), "XA connection should not have the auto commit flag set");
+            try (var conn2 = xaNoRecoverDS.getConnection()) {
+                assertFalse(conn2.getAutoCommit(), "XA connection should not have the auto commit flag set");
+            }
+        }
+
+        assertTrue(QuarkusTransaction.isActive(), "transaction should still have been active");
+
+        QuarkusTransaction.commit();
+    }
+}

extensions/agroal/deployment/src/test/resources/application-recovery-datasources.properties

@@ -0,0 +1,15 @@
+quarkus.transaction-manager.enable-recovery=true
+
+quarkus.datasource.xa.db-kind=h2
+quarkus.datasource.xa.username=username1
+quarkus.datasource.xa.jdbc.driver=org.h2.jdbcx.JdbcDataSource
+quarkus.datasource.xa.jdbc.url=jdbc:h2:tcp://localhost/mem:recover
+quarkus.datasource.xa.jdbc.enable-recovery=true
+quarkus.datasource.xa.jdbc.transactions=xa
+
+quarkus.datasource.xaNoRecover.db-kind=h2
+quarkus.datasource.xaNoRecover.username=username1
+quarkus.datasource.xaNoRecover.jdbc.driver=org.h2.jdbcx.JdbcDataSource
+quarkus.datasource.xaNoRecover.jdbc.url=jdbc:h2:tcp://localhost/mem:recover
+quarkus.datasource.xaNoRecover.jdbc.enable-recovery=false
+quarkus.datasource.xaNoRecover.jdbc.transactions=xa

extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSourceJdbcRuntimeConfig.java

@@ -133,6 +133,20 @@ public interface DataSourceJdbcRuntimeConfig {
     @WithDefault("true")
     boolean poolingEnabled();
 
+    /**
+     * Whether to enable recovery for this datasource.
+     * <p>
+     * Normally a transaction manager will call xa_recover () on an XA connection during recovery to obtain
+     * a list of transaction branches that are currently in a prepared or heuristically completed state.
+     * However, it can happen that multiple XA connections connect to the same datasource which would all
+     * return the same set of branches and for reasons of improved performance only one should be used
+     * for recover() calls. The default value for this configuration property is true because when there
+     * is only one connection it is vital for data consistency that the connection is able to report its
+     * list of prepared or heuristically completed branches.
+     */
+    @WithDefault("true")
+    boolean enableRecovery();
+
     /**
      * Require an active transaction when acquiring a connection. Recommended for production.
      * WARNING: Some extensions acquire connections without holding a transaction for things like schema updates and schema

extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSources.java

@@ -348,6 +348,7 @@ public boolean isValid(Connection connection) {
         }
         poolConfiguration.enhancedLeakReport(dataSourceJdbcRuntimeConfig.extendedLeakReport());
         poolConfiguration.flushOnClose(dataSourceJdbcRuntimeConfig.flushOnClose());
+        poolConfiguration.recoveryEnable(dataSourceJdbcRuntimeConfig.enableRecovery());
     }
 
 }