Hasql.Pipeline

Documentation

data Pipeline a

Composable abstraction over the execution of queries in the pipeline mode.

It allows you to issue multiple queries to the server in much fewer network transactions. If the amounts of sent and received data do not surpass the buffer sizes in the driver and on the server it will be just a single roundtrip. Typically the buffer size is 8KB.

This execution mode is much more efficient than running queries directly from Session, because in session every statement execution involves a dedicated network roundtrip. An obvious question rises then: why not execute all queries like that?

In situations where the parameters depend on the result of another query it is impossible to execute them in parallel, because the client needs to receive the results of one query before sending the request to execute the next. This reasoning is essentially the same as the one for the difference between Applicative and Monad. That's why Pipeline does not have the Monad instance.

To execute Pipeline lift it into Session via pipeline.

Examples

Insert-Many or Batch-Insert

You can use pipeline to turn a single-row insert query into an efficient multi-row insertion session. In effect this should be comparable in performance to issuing a single multi-row insert statement.

Given the following definition in a Statements module:

insertOrder :: Statement OrderDetails OrderId

You can lift it into the following session

insertOrders :: [OrderDetails] -> Session [OrderId]
insertOrders orders =
  pipeline $
    forM orders $ \order ->
      statement order Statements.insertOrder

Combining Queries

Given the following definitions in a Statements module:

selectOrderDetails :: Statement OrderId (Maybe OrderDetails)
selectOrderProducts :: Statement OrderId [OrderProduct]
selectOrderFinancialTransactions :: Statement OrderId [FinancialTransaction]

You can combine them into a session using the ApplicativeDo extension as follows:

selectEverythingAboutOrder :: OrderId -> Session (Maybe OrderDetails, [OrderProduct], [FinancialTransaction])
selectEverythingAboutOrder orderId =
  pipeline $ do
    details <- statement orderId Statements.selectOrderDetails
    products <- statement orderId Statements.selectOrderProducts
    transactions <- statement orderId Statements.selectOrderFinancialTransactions
    pure (details, products, transactions)

Instances

Applicative Pipeline

Defined in Hasql.Pipeline.Core

Methods

pure :: a -> Pipeline a

(<*>) :: Pipeline (a -> b) -> Pipeline a -> Pipeline b

liftA2 :: (a -> b -> c) -> Pipeline a -> Pipeline b -> Pipeline c

(*>) :: Pipeline a -> Pipeline b -> Pipeline b

(<*) :: Pipeline a -> Pipeline b -> Pipeline a

Functor Pipeline

Defined in Hasql.Pipeline.Core

Methods

fmap :: (a -> b) -> Pipeline a -> Pipeline b

(<$) :: a -> Pipeline b -> Pipeline a

statement :: params -> Statement params result -> Pipeline result

Execute a statement in pipelining mode.