-- 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.2.0.0
module Database.PostgreSQL.Tx.Internal
data TxErrorType
TxSerializationFailure :: TxErrorType
TxDeadlockDetected :: TxErrorType
-- | PostgreSQL errcode, if applicable.
TxOtherError :: Maybe String -> TxErrorType
data TxException
TxException :: TxErrorType -> SomeException -> TxException
[errorType] :: TxException -> TxErrorType
[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
shouldRetryTx :: TxException -> Bool
fromSqlState :: Maybe String -> TxErrorType
unsafeMkTxException :: Exception e => (e -> Maybe String) -> e -> TxException
unsafeMkTxException' :: Exception e => (e -> TxErrorType) -> 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.Classes.Eq Database.PostgreSQL.Tx.Internal.TxErrorType
instance GHC.Show.Show Database.PostgreSQL.Tx.Internal.TxErrorType
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
data TxException
TxException :: TxErrorType -> SomeException -> TxException
[errorType] :: TxException -> TxErrorType
[cause] :: TxException -> SomeException
data TxErrorType
TxSerializationFailure :: TxErrorType
TxDeadlockDetected :: TxErrorType
-- | PostgreSQL errcode, if applicable.
TxOtherError :: Maybe String -> TxErrorType
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
unsafeMkTxException :: Exception e => (e -> Maybe String) -> e -> TxException