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
 
+Datasources are also automatically registered with the transaction recovery system when recovery is enabled. Sometimes an application may wish to override this behaviour, such as when more than one datasource connects to the same database, by setting the configuration property `quarkus.datasource.xa.jdbc.enable-recovery` to `false`. Note that it is vital that at least one such XA capable datasource is enabled for recovery.
+
 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 recover 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 database 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());
     }
 
 }