| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Database.PostgreSQL.Tx
Synopsis
- data TxM r a
- class TxEnv a r where
- lookupTxEnv :: r -> a
- type family TxEnvs (xs :: [*]) r :: Constraint where ...
- askTxEnv :: TxEnv a r => TxM r a
- throwExceptionTx :: Exception e => e -> TxM r a
- mapExceptionTx :: (Exception e, Exception e') => (e -> Maybe e') -> TxM r a -> TxM r a
- data TxException = TxException {
- errcode :: Maybe String
- cause :: SomeException
- shouldRetryTx :: TxException -> Bool
Introduction
postgresql-tx provides a transaction monad - TxM. When arbitrary IO is
attempted to be performed within TxM, a type error is generated. Arbitrary
IO can still be performed when neccessary, but users must explicitly
opt-in to this via the Database.PostgreSQL.Tx.Unsafe module's unsafe*
functions.
Note that posgresql-tx has no dependencies on any specific
postgres-related database libraries. This library defines the TxM monad
and the infrastructure necessary to adapt specific database libraries for
TxM compatiblity. The idea is that an adaptor library provides a means to
convert a specific database library's implementation monad into TxM.
Application authors can then freely mix TxM database functions together
even if the implementations of these database functions are using different
underlying database libraries, e.g. postgresql-query , squeal-postgresql,
postgresql-simple, etc.
Transaction monad
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.
Since: 0.2.0.0
Instances
| Monad (TxM r) Source # | |
| Functor (TxM r) Source # | |
| MonadFail (TxM r) Source # | |
Defined in Database.PostgreSQL.Tx.Internal | |
| Applicative (TxM r) Source # | |
| (TypeError ('Text "MonadIO is banned in TxM; use 'unsafeRunIOInTxM' if you are sure this is safe IO") :: Constraint) => MonadIO (TxM r) Source # | The Since: 0.1.0.0 |
Defined in Database.PostgreSQL.Tx.Internal | |
| Semigroup a => Semigroup (TxM r a) Source # | |
| Monoid a => Monoid (TxM r a) Source # | |
Transaction environment
class TxEnv a r where Source #
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!
Since: 0.2.0.0
Methods
lookupTxEnv :: r -> a Source #
Acquire a value a via the reader environment r which assists in
running a TxM in a transaction.
Since: 0.2.0.0
type family TxEnvs (xs :: [*]) r :: Constraint where ... Source #
Type family which allows for specifying several TxEnv constraints as
a type-level list.
Since: 0.2.0.0
Exceptions
throwExceptionTx :: Exception e => e -> TxM r a Source #
Throw an exception.
Since: 0.2.0.0
mapExceptionTx :: (Exception e, Exception e') => (e -> Maybe e') -> TxM r a -> TxM r a Source #
Catch an exception and map it to another exception type before rethrowing.
Since: 0.2.0.0
data TxException Source #
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.
Constructors
| TxException | |
Fields
| |
Instances
| Show TxException Source # | |
Defined in Database.PostgreSQL.Tx.Internal Methods showsPrec :: Int -> TxException -> ShowS # show :: TxException -> String # showList :: [TxException] -> ShowS # | |
| Exception TxException Source # | |
Defined in Database.PostgreSQL.Tx.Internal Methods toException :: TxException -> SomeException # fromException :: SomeException -> Maybe TxException # displayException :: TxException -> String # | |
shouldRetryTx :: TxException -> Bool Source #
Useful as a predicate to indicate when to retry transactions which are
run at isolation level serializable