haddock

Author: arybczak

src/Database/PostgreSQL/PQTypes/Internal/State.hs

@@ -39,6 +39,14 @@ data ConnectionState cdata
   | Acquired !IsolationLevel !Permissions !Connection !cdata
   | Finalized
 
+-- Note: initConnectionState and finalizeConnectionState are invoked inside
+-- bracket and run with asynchronous exceptions softly masked. However, both of
+-- them may run queries that start/finish a transaction. Running queries is a
+-- blocking (and thus interruptible) operation, but if these queries are
+-- interrupted with an asynchronous exception, then a connection is leaked, so
+-- they need to be run with asynchronous exceptions hard masked with
+-- uninterruptibleMask.
+
 initConnectionState
   :: MonadBase IO m
   => InternalConnectionSource m cdata

src/Database/PostgreSQL/PQTypes/Transaction.hs

@@ -91,6 +91,10 @@ rollback = uninterruptibleMask_ $ do
       runSQL_ "ROLLBACK"
       begin
 
+-- | Run a block of code without an open transaction.
+--
+-- This function is unsafe in the 'AcquireAndHold' mode because running it
+-- commits the transaction in progress, so the atomicity guarantee is lost.
 unsafeWithoutTransaction
   :: (HasCallStack, MonadDB m, MonadMask m)
   => m a

src/Database/PostgreSQL/PQTypes/Transaction/Settings.hs

@@ -44,9 +44,17 @@ data IsolationLevel = DefaultLevel | ReadCommitted | RepeatableRead | Serializab
 data Permissions = DefaultPermissions | ReadOnly | ReadWrite
   deriving (Eq, Ord, Show)
 
+-- | Acquisition mode of a database connection.
 data ConnectionAcquisitionMode
   = AcquireOnDemand
+  -- ^ Acquire a connection on demand, i.e. only when a query needs to be
+  -- run. This mode allows you to have a 'MonadDB' constraint in scope without
+  -- holding onto connections and keeping transactions open, but allows only
+  -- execution of read only queries.
   | AcquireAndHold !IsolationLevel !Permissions
+  -- ^ Acquire a connection, start a transaction with a given isolation level
+  -- and permissions and hold onto it for the duration of a 'MonadDB' constraint
+  -- in scope.
   deriving (Eq, Ord, Show)
 
 -- | Default transaction settings.