More docs on transactions, one more transaction spec

Author: deusaquilus

README.md

@@ -398,6 +398,77 @@ try {
 }
 ```
 
+### How transactions work under the hood (coroutines-aware)
+
+Terpal controllers are implemented to be coroutine-first. Instead of relying on thread-local storage or
+manually passing a JDBC Connection (or driver session) around, Terpal attaches the current session and
+transaction state to the CoroutineContext. This makes the correct connection automatically available to
+all suspend functions that run within the same coroutine scope (and its children), even if those
+functions hop threads on Dispatchers.IO.
+
+Key pieces involved (from the controller core):
+- CoroutineSession(session, sessionKey): A CoroutineContext element that stores the current driver session
+  (e.g. a JDBC Connection). When you call ctx.withConnection { ... } or enter a ctx.transaction { ... },
+  Terpal installs a CoroutineSession into the context using withContext(... + Dispatchers.IO).
+- CoroutineTransaction: A CoroutineContext element that marks that a transaction is in progress. The
+  outer transaction installs this marker and is responsible for commit/rollback. Nested transactions
+  detect the marker and reuse the same connection and enclosing transaction, avoiding starting a second
+  physical transaction.
+
+Because these are regular CoroutineContext elements, the session/transaction information is propagated to
+child coroutines created with coroutineScope/withContext/launch within the same parent scope. No thread-local
+is required, and you never need to pass a Connection by hand.
+
+Practical implications:
+- Inside ctx.transaction { ... } you can call .run() directly on queries/actions without passing ctx; the
+  correct connection is discovered from the coroutine context.
+- Suspending and switching threads (e.g. to Dispatchers.IO) does not lose the connection—the context element
+  comes along for the ride.
+- Flows: When you stream results, Terpal uses flowOn with the same CoroutineSession so the same connection is
+  used consistently for the pipeline, and it is properly closed at completion.
+
+### Nested transactions
+
+Terpal supports nesting transaction blocks. The semantics are:
+- The first (outermost) transaction actually begins the database transaction and is responsible for
+  committing or rolling back.
+- Inner transaction blocks detect that a transaction is already in progress via CoroutineTransaction and
+  simply execute within the same connection/transaction scope. They do not commit independently; any failure
+  that escapes to the outer block will cause the outer transaction to roll back.
+
+Example:
+```kotlin
+ctx.transaction {
+  // Outer transaction started
+  insertPerson(1, "Joe")
+
+  // Inner block sees the active transaction and reuses it
+  ctx.transaction {
+    insertPerson(2, "Jim")
+  }
+
+  // If an exception is thrown here, both inserts are rolled back together
+}
+```
+
+### Launching child coroutines inside a transaction
+
+Since Terpal stores the connection/transaction in the CoroutineContext, launching child coroutines inside a
+transaction is safe as long as they remain children of the transaction scope. All of them will transparently
+see and use the same connection.
+
+```kotlin
+ctx.transaction {
+  coroutineScope {
+    launch { Sql("INSERT INTO Person (id, firstName, lastName) VALUES (3, 'Ann', 'Smith')").action().run() }
+    launch { Sql("INSERT INTO Person (id, firstName, lastName) VALUES (4, 'Bob', 'Jones')").action().run() }
+  }
+  // Both launches used the same connection/transaction
+}
+```
+
+If any child fails and the exception escapes the transaction block, the whole transaction is rolled back.
+
 
 ## Custom Parameters
 When a variable used in a Sql clause e.g. `Sql("... $dollar_sign_variable ...")` it needs

terpal-sql-jdbc/src/test/kotlin/io/exoquery/sql/postgres/TransactionSpec.kt

@@ -9,6 +9,8 @@ import io.exoquery.sql.run
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.FreeSpec
 import io.kotest.matchers.shouldBe
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.launch
 import kotlinx.serialization.Serializable
 
 class TransactionSpec: FreeSpec({
@@ -61,5 +63,19 @@ class TransactionSpec: FreeSpec({
       }
       select().runOn(ctx) shouldBe listOf(joe)
     }
+    "child coroutines share the same transaction connection" {
+      val ann = Person(3, "Ann", "Smith", 333)
+      val bob = Person(4, "Bob", "Jones", 444)
+
+      ctx.transaction {
+        coroutineScope {
+          launch { insert(ann).run() }
+          launch { insert(bob).run() }
+        }
+        // Both launches used the same connection/transaction
+      }
+
+      select().runOn(ctx).toSet() shouldBe setOf(ann, bob)
+    }
   }
 })