Orville.PostgreSQL.Monad.MonadOrville

Since: 1.0.0.0

Documentation

class (HasOrvilleState m, MonadOrvilleControl m, MonadIO m) => MonadOrville m

MonadOrville is the typeclass that most Orville operations require to do anything that connects to the database. MonadOrville itself is empty, but it lists all the required typeclasses as superclass constraints so that it can be used instead of listing all the constraints on every function.

If you want to be able to run Orville operations directly in your own application's Monad stack, a good starting place is to add

   instance MonadOrville MyApplicationMonad
 

to your module and then let the compiler tell you what instances you are missing from the superclasses.

Since: 1.0.0.0

Instances

MonadOrville Orville

Defined in Orville.PostgreSQL.Monad.Orville

(MonadOrvilleControl m, MonadIO m) => MonadOrville (ReaderT OrvilleState m)

Defined in Orville.PostgreSQL.Internal.MonadOrville

class MonadOrvilleControl m where

MonadOrvilleControl presents the interface that Orville will use to lift low-level IO operations that cannot be lifted via liftIO (i.e. those where the IO parameter is contravariant rather than covariant).

For application monads built using only ReaderT and IO, this can be trivially implemented (or derived), using the ReaderT instance that is provided here. If your monad stack is sufficiently complicated, you may need to use the unliftio package as a stepping stone to implementing MonadOrvilleControl. If your monad uses features that unliftio cannot support (e.g. the State monad or continuations), then you may need to use monad-control instead.

See UnliftIO for functions that can be used as the implementation of the methods below for monads that implement MonadUnliftIO.

Since: 1.0.0.0

Methods

liftWithConnection :: (forall a. (Connection -> IO a) -> IO a) -> (Connection -> m b) -> m b

Orville will use this function to lift the acquisition of connections from the resource pool into the application monad.

Since: 1.0.0.0

liftCatch :: Exception e => (forall a. IO a -> (e -> IO a) -> IO a) -> m b -> (e -> m b) -> m b

Orville will use this function to lift exception catches into the application monad.

Since: 1.0.0.0

liftMask :: (forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b) -> ((forall a. m a -> m a) -> m c) -> m c

Orville will use this function to lift mask calls into the application monad to guarantee resource cleanup is executed even when asynchronous exceptions are thrown.

Since: 1.0.0.0

Instances

MonadOrvilleControl IO

Defined in Orville.PostgreSQL.Internal.MonadOrville

Methods

liftWithConnection :: (forall a. (Connection -> IO a) -> IO a) -> (Connection -> IO b) -> IO b

liftCatch :: Exception e => (forall a. IO a -> (e -> IO a) -> IO a) -> IO b -> (e -> IO b) -> IO b

liftMask :: (forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b) -> ((forall a. IO a -> IO a) -> IO c) -> IO c

MonadOrvilleControl Orville

Defined in Orville.PostgreSQL.Monad.Orville

Methods

liftWithConnection :: (forall a. (Connection -> IO a) -> IO a) -> (Connection -> Orville b) -> Orville b

liftCatch :: Exception e => (forall a. IO a -> (e -> IO a) -> IO a) -> Orville b -> (e -> Orville b) -> Orville b

liftMask :: (forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b) -> ((forall a. Orville a -> Orville a) -> Orville c) -> Orville c

MonadOrvilleControl m => MonadOrvilleControl (ReaderT state m)

Defined in Orville.PostgreSQL.Internal.MonadOrville

Methods

liftWithConnection :: (forall a. (Connection -> IO a) -> IO a) -> (Connection -> ReaderT state m b) -> ReaderT state m b

liftCatch :: Exception e => (forall a. IO a -> (e -> IO a) -> IO a) -> ReaderT state m b -> (e -> ReaderT state m b) -> ReaderT state m b

liftMask :: (forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b) -> ((forall a. ReaderT state m a -> ReaderT state m a) -> ReaderT state m c) -> ReaderT state m c

withConnection :: MonadOrville m => (Connection -> m a) -> m a

withConnection should be used to receive a Connection handle for executing queries against the database from within an application monad using Orville. For the "outermost" call of withConnection, a connection will be acquired from the resource pool. Additional calls to withConnection that happen inside the 'm a' that uses the connection will return the same Connection. When the 'm a' finishes, the connection will be returned to the pool. If 'm a' throws an exception, the pool's exception handling will take effect, generally destroying the connection in case it was the source of the error.

Since: 1.0.0.0

withConnection_ :: MonadOrville m => m a -> m a

withConnection_ is a convenience version of withConnection for those that don't need the actual connection handle. You might want to use this function even without using the handle because it ensures that all the Orville operations performed by the action passed to it occur on the same connection. Orville uses connection pooling, so unless you use either withConnection or withTransaction, each database operation may be performed on a different connection.

Since: 1.0.0.0