hasql-0.19.18: An efficient PostgreSQL driver and a flexible mapping API

Safe Haskell | None
Language | Haskell2010

Hasql.Query

Synopsis

- data Query a b
- statement :: ByteString -> Params a -> Result b -> Bool -> Query a b

# Documentation

data Query a b #

An abstraction over parametric queries.

It is composable using the standard interfaces of the category theory, which it has instances of. E.g., here's how you can compose queries using the Arrow notation:

    -- |
    -- Given an Update query,
    -- which uses the @fmap (> 0) rowsAffected@ decoder
    -- to detect, whether it had any effect,
    -- and an Insert query,
    -- produces a query which performs Upsert.
    composeUpsert :: Query a Bool -> Query a () -> Query a ()
    composeUpsert update insert =
      proc params -> do
        updated <- update -< params
        if updated
          then returnA -< ()
          else insert -< params

Instances

Arrow Query # |
Methods arr :: (b -> c) -> Query b c # first :: Query b c -> Query (b, d) (c, d) # second :: Query b c -> Query (d, b) (d, c) # (***) :: Query b c -> Query b' c' -> Query (b, b') (c, c') # (&&&) :: Query b c -> Query b c' -> Query b (c, c') #
ArrowChoice Query # |
Methods left :: Query b c -> Query (Either b d) (Either c d) # right :: Query b c -> Query (Either d b) (Either d c) # (+++) :: Query b c -> Query b' c' -> Query (Either b b') (Either c c') # (|||) :: Query b d -> Query c d -> Query (Either b c) d #
ArrowApply Query # |
Methods app :: Query (Query b c, b) c #
ArrowLoop Query # |
Methods loop :: Query (b, d) (c, d) -> Query b c #
Profunctor Query # |
Methods dimap :: (a -> b) -> (c -> d) -> Query b c -> Query a d # lmap :: (a -> b) -> Query b c -> Query a c # rmap :: (b -> c) -> Query a b -> Query a c # (#.) :: Coercible * c b => (b -> c) -> Query a b -> Query a c # (.#) :: Coercible * b a => Query b c -> (a -> b) -> Query a c #
Functor (Query a) # |
Methods fmap :: (a -> b) -> Query a a -> Query a b # (<$) :: a -> Query a b -> Query a a #
Category * Query # |
Methods id :: cat a a # (.) :: cat b c -> cat a b -> cat a c #

statement :: ByteString -> Params a -> Result b -> Bool -> Query a b #

A specification of a strictly single-statement query, which can be parameterized and prepared.

Consists of the following:

- SQL template,
- params encoder,
- result decoder,
- a flag, determining whether it should be prepared.

The SQL template must be formatted according to Postgres' standard, with any non-ASCII characters of the template encoded using UTF-8. According to the format, parameters must be referred to using the positional notation, as in the following: `$1`, `$2`, `$3` and etc. Those references must be used to refer to the values of the `Params` encoder.

Following is an example of the declaration of a prepared statement with its associated codecs.

    selectSum :: Hasql.Query.Query (Int64, Int64) Int64
    selectSum =
      Hasql.Query.statement sql encoder decoder True
      where
        sql =
          "select ($1 + $2)"
        encoder =
          contramap fst (Hasql.Encoders.value Hasql.Encoders.int8) <>
          contramap snd (Hasql.Encoders.value Hasql.Encoders.int8)
        decoder =
          Hasql.Decoders.singleRow (Hasql.Decoders.value Hasql.Decoders.int8)

The statement above accepts a product of two parameters of type `Int64` and produces a single result of type `Int64`.