@@ -398,34 +398,34 @@ try {
398398}
399399```
400400
401- ### How transactions work under the hood (coroutines-aware)
402-
403- Terpal controllers are implemented to be coroutine-first. Instead of relying on thread-local storage or
404- manually passing a JDBC Connection (or driver session) around, Terpal attaches the current session and
405- transaction state to the CoroutineContext. This makes the correct connection automatically available to
406- all suspend functions that run within the same coroutine scope (and its children), even if those
407- functions hop threads on Dispatchers.IO.
408-
409- Key pieces involved (from the controller core):
410- - CoroutineSession(session, sessionKey): A CoroutineContext element that stores the current driver session
411- (e.g. a JDBC Connection). When you call ctx.withConnection { ... } or enter a ctx.transaction { ... },
412- Terpal installs a CoroutineSession into the context using withContext(... + Dispatchers.IO).
413- - CoroutineTransaction: A CoroutineContext element that marks that a transaction is in progress. The
414- outer transaction installs this marker and is responsible for commit/rollback. Nested transactions
415- detect the marker and reuse the same connection and enclosing transaction, avoiding starting a second
416- physical transaction.
417-
418- Because these are regular CoroutineContext elements, the session/transaction information is propagated to
419- child coroutines created with coroutineScope/withContext/launch within the same parent scope. No thread-local
420- is required, and you never need to pass a Connection by hand.
421-
422- Practical implications:
423- - Inside ctx.transaction { ... } you can call .run() directly on queries/actions without passing ctx; the
424- correct connection is discovered from the coroutine context.
425- - Suspending and switching threads (e.g. to Dispatchers.IO) does not lose the connection—the context element
426- comes along for the ride.
427- - Flows: When you stream results, Terpal uses flowOn with the same CoroutineSession so the same connection is
428- used consistently for the pipeline, and it is properly closed at completion.
401+ > ### How transactions work under the hood (coroutines-aware)
402+ >
403+ > Terpal controllers are implemented to be coroutine-first. Instead of relying on thread-local storage or
404+ > manually passing a JDBC Connection (or driver session) around, Terpal attaches the current session and
405+ > transaction state to the CoroutineContext. This makes the correct connection automatically available to
406+ > all suspend functions that run within the same coroutine scope (and its children), even if those
407+ > functions hop threads on Dispatchers.IO.
408+ >
409+ > Key pieces involved (from the controller core):
410+ > - CoroutineSession(session, sessionKey): A CoroutineContext element that stores the current driver session
411+ > (e.g. a JDBC Connection). When you call ctx.withConnection { ... } or enter a ctx.transaction { ... },
412+ > Terpal installs a CoroutineSession into the context using withContext(... + Dispatchers.IO).
413+ > - CoroutineTransaction: A CoroutineContext element that marks that a transaction is in progress. The
414+ > outer transaction installs this marker and is responsible for commit/rollback. Nested transactions
415+ > detect the marker and reuse the same connection and enclosing transaction, avoiding starting a second
416+ > physical transaction.
417+ >
418+ > Because these are regular CoroutineContext elements, the session/transaction information is propagated to
419+ > child coroutines created with coroutineScope/withContext/launch within the same parent scope. No thread-local
420+ > is required, and you never need to pass a Connection by hand.
421+ >
422+ > Practical implications:
423+ > - Inside ctx.transaction { ... } you can call .run() directly on queries/actions without passing ctx; the
424+ > correct connection is discovered from the coroutine context.
425+ > - Suspending and switching threads (e.g. to Dispatchers.IO) does not lose the connection—the context element
426+ > comes along for the ride.
427+ > - Flows: When you stream results, Terpal uses flowOn with the same CoroutineSession so the same connection is
428+ > used consistently for the pipeline, and it is properly closed at completion.
429429
430430### Nested transactions
431431
0 commit comments