-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A safe transaction monad for use with various PostgreSQL Haskell libraries.
--
-- Please see the README on GitHub at
-- https://github.com/simspace/postgresql-tx#readme
@package postgresql-tx
@version 0.3.0.0
module Database.PostgreSQL.Tx.Internal
-- | Unified exception type thrown from the database.
--
-- Each database backend may throw different types of exceptions. As a
-- user of postgresql-tx, ideally we should be able to detect
-- exceptions from the database without needing to catch the database
-- backend's exception type.
--
-- The errcode field allows us to introspect the postgresql
-- errcode; see
-- https://www.postgresql.org/docs/current/errcodes-appendix.html
--
-- If you need to inspect the exact exception thrown by a database
-- backend, use the cause field.
data TxException
TxException :: Maybe String -> SomeException -> TxException
[errcode] :: TxException -> Maybe String
[cause] :: TxException -> SomeException
-- | Type family which allows for specifying several TxEnv
-- constraints as a type-level list.
type family TxEnvs (xs :: [*]) r :: Constraint
-- | A type class for specifying how to acquire an environment value to be
-- used for running an implementation of a database library. For example,
-- your database library will likely require some sort of connection
-- value to discharge its effects; in this case, you'd want to define an
-- instance of TxEnv MyDBEnv Connection and use TxM
-- MyDBEnv as your monad for executing transactions.
--
-- Note that implementations should take care and ensure that multiple
-- instances are compatible with one another. For example, let's say you
-- have instances for both TxEnv E PgSimple.Connection and
-- TxEnv E LibPQ.Connection; if both of these implementations
-- are grabbing connections from a pool, you will end up with each of
-- those database libraries using different connections, and thus, would
-- be running in separate transactions!
class TxEnv a r
-- | Acquire a value a via the reader environment r which
-- assists in running a TxM in a transaction.
lookupTxEnv :: TxEnv a r => r -> a
-- | The transaction monad. Unifies all database integrations, regardless
-- of library, into a single monad. The r type parameter
-- represents the reader environment needed for applicable database
-- libraries. For example, postgresql-simple needs a
-- Connection to run its functions, so its interface will
-- require that we can obtain a Connection from the r
-- using the TxEnv type class.
newtype TxM r a
UnsafeTxM :: ReaderT r IO a -> TxM r a
-- | Convert a TxM action to raw ReaderT over IO. This
-- is provided only to give adaptor libraries access to the underlying
-- IO that TxM wraps.
[unsafeUnTxM] :: TxM r a -> ReaderT r IO a
-- | Run an IO action in TxM. Use this function with care -
-- arbitrary IO should only be run within a transaction when truly
-- necessary.
unsafeRunIOInTxM :: IO a -> TxM r a
-- | Construct a TxM using a reader function. Use this function with
-- care - arbitrary IO should only be run within a transaction
-- when truly necessary.
unsafeMkTxM :: (r -> IO a) -> TxM r a
-- | Similar to unsafeMkTxM but allows for constructing a TxM
-- with a reader function using a specific value from the environment.
-- Use this function with care - arbitrary IO should only be run
-- within a transaction when truly necessary.
unsafeMksTxM :: TxEnv a r => (a -> IO b) -> TxM r b
-- | Run a TxM to IO given the database runtime environment
-- r. Use of this function outside of test suites should be
-- rare.
unsafeRunTxM :: r -> TxM r a -> IO a
-- | Run a TxM action in IO via the provided runner function.
-- Use this function with care - arbitrary IO should only be run
-- within a transaction when truly necessary.
unsafeWithRunInIOTxM :: ((forall a. TxM r a -> IO a) -> IO b) -> TxM r b
askTxEnv :: TxEnv a r => TxM r a
-- | Analogous to lookupTxEnv but can be run in IO instead of
-- TxM.
unsafeLookupTxEnvIO :: TxEnv a r => r -> IO a
-- | Throw an exception.
throwExceptionTx :: Exception e => e -> TxM r a
-- | Catch an exception and map it to another exception type before
-- rethrowing.
mapExceptionTx :: (Exception e, Exception e') => (e -> Maybe e') -> TxM r a -> TxM r a
-- | PostgreSQL errcode for serialization_failure.
errcode'serialization_failure :: String
-- | PostgreSQL errcode for deadlock_detected.
errcode'deadlock_detected :: String
-- | Checks if the errcode of a TxException matches the
-- supplied predicate. If the errcode is Nothing, returns
-- False.
hasErrcode :: (String -> Bool) -> TxException -> Bool
-- | Useful as a predicate to indicate when to retry transactions which are
-- run at isolation level serializable
shouldRetryTx :: TxException -> Bool
-- | Construct a TxException from an errcode accessing
-- function and the cause exception.
--
-- Note that this function should only be used by libraries which are
-- implementing a database backend for postgresql-tx.
unsafeMkTxException :: Exception e => (e -> Maybe String) -> e -> TxException
instance GHC.Base.Monoid a => GHC.Base.Monoid (Database.PostgreSQL.Tx.Internal.TxM r a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Database.PostgreSQL.Tx.Internal.TxM r a)
instance Control.Monad.Fail.MonadFail (Database.PostgreSQL.Tx.Internal.TxM r)
instance GHC.Base.Monad (Database.PostgreSQL.Tx.Internal.TxM r)
instance GHC.Base.Applicative (Database.PostgreSQL.Tx.Internal.TxM r)
instance GHC.Base.Functor (Database.PostgreSQL.Tx.Internal.TxM r)
instance GHC.Show.Show Database.PostgreSQL.Tx.Internal.TxException
instance GHC.Exception.Type.Exception Database.PostgreSQL.Tx.Internal.TxException
instance (TypeError ...) => Control.Monad.IO.Class.MonadIO (Database.PostgreSQL.Tx.Internal.TxM r)
module Database.PostgreSQL.Tx
-- | The transaction monad. Unifies all database integrations, regardless
-- of library, into a single monad. The r type parameter
-- represents the reader environment needed for applicable database
-- libraries. For example, postgresql-simple needs a
-- Connection to run its functions, so its interface will
-- require that we can obtain a Connection from the r
-- using the TxEnv type class.
data TxM r a
-- | A type class for specifying how to acquire an environment value to be
-- used for running an implementation of a database library. For example,
-- your database library will likely require some sort of connection
-- value to discharge its effects; in this case, you'd want to define an
-- instance of TxEnv MyDBEnv Connection and use TxM
-- MyDBEnv as your monad for executing transactions.
--
-- Note that implementations should take care and ensure that multiple
-- instances are compatible with one another. For example, let's say you
-- have instances for both TxEnv E PgSimple.Connection and
-- TxEnv E LibPQ.Connection; if both of these implementations
-- are grabbing connections from a pool, you will end up with each of
-- those database libraries using different connections, and thus, would
-- be running in separate transactions!
class TxEnv a r
-- | Acquire a value a via the reader environment r which
-- assists in running a TxM in a transaction.
lookupTxEnv :: TxEnv a r => r -> a
-- | Type family which allows for specifying several TxEnv
-- constraints as a type-level list.
type family TxEnvs (xs :: [*]) r :: Constraint
askTxEnv :: TxEnv a r => TxM r a
-- | Throw an exception.
throwExceptionTx :: Exception e => e -> TxM r a
-- | Catch an exception and map it to another exception type before
-- rethrowing.
mapExceptionTx :: (Exception e, Exception e') => (e -> Maybe e') -> TxM r a -> TxM r a
-- | Unified exception type thrown from the database.
--
-- Each database backend may throw different types of exceptions. As a
-- user of postgresql-tx, ideally we should be able to detect
-- exceptions from the database without needing to catch the database
-- backend's exception type.
--
-- The errcode field allows us to introspect the postgresql
-- errcode; see
-- https://www.postgresql.org/docs/current/errcodes-appendix.html
--
-- If you need to inspect the exact exception thrown by a database
-- backend, use the cause field.
data TxException
TxException :: Maybe String -> SomeException -> TxException
[errcode] :: TxException -> Maybe String
[cause] :: TxException -> SomeException
-- | Useful as a predicate to indicate when to retry transactions which are
-- run at isolation level serializable
shouldRetryTx :: TxException -> Bool
module Database.PostgreSQL.Tx.HEnv
-- | Glorified hlist used to construct ad hoc tx runtime
-- environments.
data family HEnv (l :: [*])
infixr 2 `Cons`
-- | Construct an HEnv containing a single value.
singleton :: a -> HEnv '[a]
-- | Construct an HEnv from the given tuple i. Instances
-- support tuples of up to 16 elements.
fromTuple :: FromTuple i o => i -> HEnv o
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2) '[x1, x2]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3) '[x1, x2, x3]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4) '[x1, x2, x3, x4]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5) '[x1, x2, x3, x4, x5]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6) '[x1, x2, x3, x4, x5, x6]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7) '[x1, x2, x3, x4, x5, x6, x7]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8) '[x1, x2, x3, x4, x5, x6, x7, x8]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9) '[x1, x2, x3, x4, x5, x6, x7, x8, x9]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15]
instance Database.PostgreSQL.Tx.HEnv.FromTuple (x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16) '[x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16]
instance Database.PostgreSQL.Tx.HEnv.Select a xs => Database.PostgreSQL.Tx.Internal.TxEnv a (Database.PostgreSQL.Tx.HEnv.HEnv xs)
instance Database.PostgreSQL.Tx.HEnv.Select a (a : xs)
instance Database.PostgreSQL.Tx.HEnv.Select a xs => Database.PostgreSQL.Tx.HEnv.Select a (x : xs)
module Database.PostgreSQL.Tx.Unsafe
-- | Run an IO action in TxM. Use this function with care -
-- arbitrary IO should only be run within a transaction when truly
-- necessary.
unsafeRunIOInTxM :: IO a -> TxM r a
-- | Run a TxM action in IO via the provided runner function.
-- Use this function with care - arbitrary IO should only be run
-- within a transaction when truly necessary.
unsafeWithRunInIOTxM :: ((forall a. TxM r a -> IO a) -> IO b) -> TxM r b
-- | Convert a TxM action to raw ReaderT over IO. This
-- is provided only to give adaptor libraries access to the underlying
-- IO that TxM wraps.
unsafeUnTxM :: TxM r a -> ReaderT r IO a
-- | Run a TxM to IO given the database runtime environment
-- r. Use of this function outside of test suites should be
-- rare.
unsafeRunTxM :: r -> TxM r a -> IO a
-- | Construct a TxM using a reader function. Use this function with
-- care - arbitrary IO should only be run within a transaction
-- when truly necessary.
unsafeMkTxM :: (r -> IO a) -> TxM r a
-- | Similar to unsafeMkTxM but allows for constructing a TxM
-- with a reader function using a specific value from the environment.
-- Use this function with care - arbitrary IO should only be run
-- within a transaction when truly necessary.
unsafeMksTxM :: TxEnv a r => (a -> IO b) -> TxM r b
-- | Analogous to lookupTxEnv but can be run in IO instead of
-- TxM.
unsafeLookupTxEnvIO :: TxEnv a r => r -> IO a
-- | Construct a TxException from an errcode accessing
-- function and the cause exception.
--
-- Note that this function should only be used by libraries which are
-- implementing a database backend for postgresql-tx.
unsafeMkTxException :: Exception e => (e -> Maybe String) -> e -> TxException