feat: EXPOSED-555 Allow read-only suspendable transactions

exposed-core/api/exposed-core.api

@@ -3718,10 +3718,10 @@ public final class org/jetbrains/exposed/sql/transactions/TransactionStore : kot
 }
 
 public final class org/jetbrains/exposed/sql/transactions/experimental/SuspendedKt {
-	public static final fun newSuspendedTransaction (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public static synthetic fun newSuspendedTransaction$default (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
-	public static final fun suspendedTransactionAsync (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public static synthetic fun suspendedTransactionAsync$default (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public static final fun newSuspendedTransaction (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Ljava/lang/Boolean;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun newSuspendedTransaction$default (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Ljava/lang/Boolean;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public static final fun suspendedTransactionAsync (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Ljava/lang/Boolean;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun suspendedTransactionAsync$default (Lkotlin/coroutines/CoroutineContext;Lorg/jetbrains/exposed/sql/Database;Ljava/lang/Integer;Ljava/lang/Boolean;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 	public static final fun withSuspendTransaction (Lorg/jetbrains/exposed/sql/Transaction;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun withSuspendTransaction$default (Lorg/jetbrains/exposed/sql/Transaction;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 }

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/transactions/experimental/Suspended.kt

@@ -68,9 +68,10 @@ suspend fun <T> newSuspendedTransaction(
     context: CoroutineContext? = null,
     db: Database? = null,
     transactionIsolation: Int? = null,
+    readOnly: Boolean? = null,
     statement: suspend Transaction.() -> T
 ): T =
-    withTransactionScope(context, null, db, transactionIsolation) {
+    withTransactionScope(context, null, db, transactionIsolation, readOnly) {
         suspendedTransactionAsyncInternal(true, statement).await()
     }
 
@@ -86,7 +87,7 @@ suspend fun <T> Transaction.withSuspendTransaction(
     context: CoroutineContext? = null,
     statement: suspend Transaction.() -> T
 ): T =
-    withTransactionScope(context, this, db = null, transactionIsolation = null) {
+    withTransactionScope(context, this, db = null, transactionIsolation = null, readOnly = null) {
         suspendedTransactionAsyncInternal(false, statement).await()
     }
 
@@ -102,10 +103,11 @@ suspend fun <T> suspendedTransactionAsync(
     context: CoroutineContext? = null,
     db: Database? = null,
     transactionIsolation: Int? = null,
+    readOnly: Boolean? = null,
     statement: suspend Transaction.() -> T
 ): Deferred<T> {
     val currentTransaction = TransactionManager.currentOrNull()
-    return withTransactionScope(context, null, db, transactionIsolation) {
+    return withTransactionScope(context, null, db, transactionIsolation, readOnly) {
         suspendedTransactionAsyncInternal(!holdsSameTransaction(currentTransaction), statement)
     }
 }
@@ -129,6 +131,7 @@ private suspend fun <T> withTransactionScope(
     currentTransaction: Transaction?,
     db: Database? = null,
     transactionIsolation: Int?,
+    readOnly: Boolean?,
     body: suspend TransactionScope.() -> T
 ): T {
     val currentScope = coroutineContext[TransactionScope]
@@ -137,7 +140,10 @@ private suspend fun <T> withTransactionScope(
         val manager = currentDatabase?.transactionManager ?: TransactionManager.manager
 
         val tx = lazy(LazyThreadSafetyMode.NONE) {
-            currentTransaction ?: manager.newTransaction(transactionIsolation ?: manager.defaultIsolationLevel)
+            currentTransaction ?: manager.newTransaction(
+                isolation = transactionIsolation ?: manager.defaultIsolationLevel,
+                readOnly = readOnly ?: manager.defaultReadOnly
+            )
         }
 
         val element = TransactionCoroutineElement(tx, manager)

exposed-tests/build.gradle.kts

@@ -38,6 +38,7 @@ dependencies {
     compileOnly(libs.h2)
     testCompileOnly(libs.sqlite.jdbc)
     testImplementation(libs.logcaptor)
+    testImplementation(libs.kotlinx.coroutines.test)
 }
 
 tasks.withType<Test>().configureEach {

exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/postgresql/ConnectionPoolTests.kt

@@ -2,6 +2,7 @@ package org.jetbrains.exposed.sql.tests.postgresql
 
 import com.zaxxer.hikari.HikariConfig
 import com.zaxxer.hikari.HikariDataSource
+import kotlinx.coroutines.test.runTest
 import org.jetbrains.exposed.dao.id.IntIdTable
 import org.jetbrains.exposed.exceptions.ExposedSQLException
 import org.jetbrains.exposed.sql.Database
@@ -13,12 +14,13 @@ import org.jetbrains.exposed.sql.tests.shared.assertEquals
 import org.jetbrains.exposed.sql.tests.shared.assertTrue
 import org.jetbrains.exposed.sql.tests.shared.expectException
 import org.jetbrains.exposed.sql.transactions.TransactionManager
+import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction
 import org.jetbrains.exposed.sql.transactions.transaction
 import org.junit.Assert
+import org.junit.Assert.assertNotNull
 import org.junit.Assume
 import org.junit.Test
 import java.sql.Connection
-import kotlin.test.assertNotNull
 
 class ConnectionPoolTests : LogDbInTestName() {
     private val hikariDataSourcePG by lazy {
@@ -62,19 +64,36 @@ class ConnectionPoolTests : LogDbInTestName() {
     fun testReadOnlyModeWithHikariAndPostgres() {
         Assume.assumeTrue(TestDB.POSTGRESQL in TestDB.enabledDialects())
 
-        val testTable = object : IntIdTable("HIKARI_TESTER") { }
+        // read only mode should be set directly by hikari config
+        transaction(db = hikariPG) {
+            assertTrue(getReadOnlyMode())
 
-        fun Transaction.getReadOnlyMode(): Boolean {
-            val mode = exec("SHOW transaction_read_only;") {
-                it.next()
-                it.getBoolean(1)
+            // table cannot be created in read-only mode
+            expectException<ExposedSQLException> {
+                SchemaUtils.create(TestTable)
             }
-            assertNotNull(mode)
-            return mode
         }
 
+        // transaction setting should override hikari config
+        transaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE, readOnly = false, db = hikariPG) {
+            Assert.assertFalse(getReadOnlyMode())
+
+            // table can now be created and dropped
+            SchemaUtils.create(TestTable)
+            SchemaUtils.drop(TestTable)
+        }
+
+        TransactionManager.closeAndUnregister(hikariPG)
+    }
+
+    @Test
+    fun testSuspendedReadOnlyModeWithHikariAndPostgres() = runTest {
+        Assume.assumeTrue(TestDB.POSTGRESQL in TestDB.enabledDialects())
+
+        val testTable = object : IntIdTable("HIKARI_TESTER") { }
+
         // read only mode should be set directly by hikari config
-        transaction(db = hikariPG) {
+        newSuspendedTransaction(db = hikariPG) {
             assertTrue(getReadOnlyMode())
 
             // table cannot be created in read-only mode
@@ -84,7 +103,7 @@ class ConnectionPoolTests : LogDbInTestName() {
         }
 
         // transaction setting should override hikari config
-        transaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE, readOnly = false, db = hikariPG) {
+        newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE, readOnly = false, db = hikariPG) {
             Assert.assertFalse(getReadOnlyMode())
 
             // table can now be created and dropped
@@ -95,3 +114,14 @@ class ConnectionPoolTests : LogDbInTestName() {
         TransactionManager.closeAndUnregister(hikariPG)
     }
 }
+
+private val TestTable = object : IntIdTable("HIKARI_TESTER") { }
+
+private fun Transaction.getReadOnlyMode(): Boolean {
+    val mode = exec("SHOW transaction_read_only;") {
+        it.next()
+        it.getBoolean(1)
+    }
+    assertNotNull(mode)
+    return mode == true
+}

exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/ThreadLocalManagerTest.kt

@@ -1,6 +1,8 @@
 package org.jetbrains.exposed.sql.tests.shared
 
+import kotlinx.coroutines.test.runTest
 import org.jetbrains.exposed.dao.id.IntIdTable
+import org.jetbrains.exposed.exceptions.ExposedSQLException
 import org.jetbrains.exposed.sql.Database
 import org.jetbrains.exposed.sql.SchemaUtils
 import org.jetbrains.exposed.sql.insert
@@ -9,6 +11,7 @@ import org.jetbrains.exposed.sql.tests.DatabaseTestsBase
 import org.jetbrains.exposed.sql.tests.TestDB
 import org.jetbrains.exposed.sql.tests.shared.dml.DMLTestsData
 import org.jetbrains.exposed.sql.transactions.TransactionManager
+import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction
 import org.jetbrains.exposed.sql.transactions.inTopLevelTransaction
 import org.jetbrains.exposed.sql.transactions.transaction
 import org.jetbrains.exposed.sql.transactions.transactionManager
@@ -48,11 +51,7 @@ class ThreadLocalManagerTest : DatabaseTestsBase() {
 
     @Test
     fun testReadOnly() {
-        // Explanation: MariaDB driver never set readonly to true, MSSQL silently ignores the call, SQLite does not
-        // promise anything, H2 has very limited functionality
-        val excludeSettings = TestDB.ALL_H2 + TestDB.ALL_MARIADB +
-            listOf(TestDB.SQLITE, TestDB.SQLSERVER, TestDB.ORACLE)
-        withTables(excludeSettings = excludeSettings, RollbackTable) {
+        withTables(excludeSettings = READ_ONLY_EXCLUDED_VENDORS, RollbackTable) {
             assertFails {
                 inTopLevelTransaction(db.transactionManager.defaultIsolationLevel, true) {
                     maxAttempts = 1
@@ -61,8 +60,39 @@ class ThreadLocalManagerTest : DatabaseTestsBase() {
             }.message?.run { assertTrue(contains("read-only")) } ?: fail("message should not be null")
         }
     }
+
+    @Test
+    fun testSuspendedReadOnly() = runTest {
+        Assume.assumeFalse(dialect in READ_ONLY_EXCLUDED_VENDORS)
+
+        val database = dialect.connect()
+        newSuspendedTransaction(db = database, readOnly = true) {
+            expectException<ExposedSQLException> {
+                SchemaUtils.create(RollbackTable)
+            }
+        }
+
+        transaction(db = database) {
+            SchemaUtils.create(RollbackTable)
+        }
+
+        newSuspendedTransaction(db = database, readOnly = true) {
+            expectException<ExposedSQLException> {
+                RollbackTable.insert { it[value] = "random-something" }
+            }
+        }
+
+        transaction(db = database) {
+            SchemaUtils.drop(RollbackTable)
+        }
+    }
 }
 
 object RollbackTable : IntIdTable("rollbackTable") {
     val value = varchar("value", 20)
 }
+
+// Explanation: MariaDB driver never set readonly to true, MSSQL silently ignores the call, SQLite does not
+// promise anything, H2 has very limited functionality
+private val READ_ONLY_EXCLUDED_VENDORS =
+    TestDB.ALL_H2 + TestDB.ALL_MARIADB + listOf(TestDB.SQLITE, TestDB.SQLSERVER, TestDB.ORACLE)

gradle/libs.versions.toml

@@ -42,6 +42,7 @@ detekt-formatting = { group = "io.gitlab.arturbosch.detekt", name = "detekt-form
 
 kotlinx-coroutines = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinCoroutines" }
 kotlinx-coroutines-debug = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-debug", version.ref = "kotlinCoroutines" }
+kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "kotlinCoroutines" }
 kotlinx-jvm-datetime = { group = "org.jetbrains.kotlinx", name = "kotlinx-datetime-jvm", version.ref = "kotlinx-datetime" }
 kotlinx-serialization = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerialization" }