Documentation

Evidence that a data-structure determines an atomic, retryable database transaction.

isolation and mode are properties of the transaction, not of the call site: whether an operation needs Serializable is a fact about what it does, and a caller reaching for toSessionWithUnboundedRetries or toSessionWithoutRetries cannot override or forget them.

The defaults are the conservative ones (Serializable and Write), so the safe case is free and every relaxation is explicit and reviewable in the instance. The opposite defaults would make an under-isolated transaction invisible.

A composite transaction declares the join of its components by hand, using IsolationLevel and Mode's Semigroup instances:

instance IsTransaction Composite where
  isolation = isolation \@Part1 <> isolation \@Part2
  mode = mode \@Part1 <> mode \@Part2

The two identities are deliberately opposite, because a reader who learns one will guess the other wrong:

• mempty is minBound (ReadCommitted and Read), so that a component with no opinion never downgrades a component that has one.
• An omitted class method defaults to Serializable and Write, so that an author who never considered the question gets the safe answer.

Both are conservative, by opposite rules. The join is declared explicitly rather than derived, so changing which components make up a composite requires updating these declarations as well.

Example of such a module

module MusicCatalogueDb.Transactions.InsertAlbumWithTracks where

import Hasql.Mapping.IsTransaction
import qualified Hasql.Transaction as Transaction
import qualified MusicCatalogueDb.Statements.InsertAlbum as InsertAlbum
import qualified MusicCatalogueDb.Statements.InsertTrack as InsertTrack
import Prelude

data InsertAlbumWithTracks = InsertAlbumWithTracks
  { album :: InsertAlbum.InsertAlbum,
    tracks :: [InsertTrack.InsertTrack]
  }

type InsertAlbumWithTracksResult = InsertAlbum.InsertAlbumResult

instance IsTransaction InsertAlbumWithTracks where
  type Result InsertAlbumWithTracks = InsertAlbumWithTracksResult
  isolation = ReadCommitted -- inserts only fresh rows, so no anomaly exposure
  transaction params = do
    albumId <- Transaction.statement params.album InsertAlbum.statement
    for_ params.tracks \track ->
      Transaction.statement track InsertTrack.statement
    pure albumId

For reference see the Postgres' documentation.

Runs the transaction with its declared isolation and mode, retrying it indefinitely on serialization failures and deadlocks.

hasql-transaction's retry is a fix loop with no backoff and no cap: a Serializable transaction under sustained contention can spin indefinitely, holding a connection and never surfacing an error. Prefer toSessionWithoutRetries with your own bounded retry loop unless that is an acceptable risk for the operation.

Runs the transaction with its declared isolation and mode, without retrying it on failure.