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

Safe Haskell | None
Language | Haskell2010

Hasql.Decoders

Contents

- Result
  - Specialized multi-row results
  - Multi-row traversers
- Row
- Value
- Array
- Composite

Description

A DSL for declaration of result decoders.

Synopsis

- data Result a
- unit :: Result ()
- rowsAffected :: Result Int64
- singleRow :: Row a -> Result a
- maybeRow :: Row a -> Result (Maybe a)
- rowsVector :: Row a -> Result (Vector a)
- rowsList :: Row a -> Result [a]
- foldlRows :: (a -> b -> a) -> a -> Row b -> Result a
- foldrRows :: (b -> a -> a) -> a -> Row b -> Result a
- data Row a
- value :: Value a -> Row a
- nullableValue :: Value a -> Row (Maybe a)
- data Value a
- bool :: Value Bool
- int2 :: Value Int16
- int4 :: Value Int32
- int8 :: Value Int64
- float4 :: Value Float
- float8 :: Value Double
- numeric :: Value Scientific
- char :: Value Char
- text :: Value Text
- bytea :: Value ByteString
- date :: Value Day
- timestamp :: Value LocalTime
- timestamptz :: Value UTCTime
- time :: Value TimeOfDay
- timetz :: Value (TimeOfDay, TimeZone)
- interval :: Value DiffTime
- uuid :: Value UUID
- inet :: Value (NetAddr IP)
- json :: Value Value
- jsonBytes :: (ByteString -> Either Text a) -> Value a
- jsonb :: Value Value
- jsonbBytes :: (ByteString -> Either Text a) -> Value a
- array :: Array a -> Value a
- composite :: Composite a -> Value a
- hstore :: (forall m. Monad m => Int -> m (Text, Maybe Text) -> m a) -> Value a
- enum :: (Text -> Maybe a) -> Value a
- custom :: (Bool -> ByteString -> Either Text a) -> Value a
- data Array a
- arrayDimension :: (forall m. Monad m => Int -> m a -> m b) -> Array a -> Array b
- arrayValue :: Value a -> Array a
- arrayNullableValue :: Value a -> Array (Maybe a)
- data Composite a
- compositeValue :: Value a -> Composite a
- compositeNullableValue :: Value a -> Composite (Maybe a)

# Result

data Result a #

Decoder of a query result.

Instances

Functor Result # |
Methods fmap :: (a -> b) -> Result a -> Result b # (<$) :: a -> Result b -> Result a #
Default (Result Int64) # | Maps to `rowsAffected`.
Methods def :: Result Int64 #
Default (Row a) => Default (Result [a]) # | Maps to `(`rowsList` def)`.
Methods def :: Result [a] #
Default (Row a) => Default (Result (Maybe a)) # | Maps to `(`maybeRow` def)`.
Methods def :: Result (Maybe a) #
Default (Result ()) # | Maps to `unit`.
Methods def :: Result () #
Default (Row a) => Default (Result (Identity a)) # | Maps to `(fmap Identity (`singleRow` def)`.
Methods def :: Result (Identity a) #
Default (Row a) => Default (Result (Vector a)) # | Maps to `(`rowsVector` def)`.
Methods def :: Result (Vector a) #

unit :: Result () #

Decode no value from the result.

Useful for statements like `INSERT` or `CREATE`.

rowsAffected :: Result Int64 #

Get the amount of rows affected by such statements as `UPDATE` or `DELETE`.

singleRow :: Row a -> Result a #

Exactly one row. Will raise the `UnexpectedAmountOfRows` error if it's any other.

## Specialized multi-row results

maybeRow :: Row a -> Result (Maybe a) #

Maybe one row or none.

rowsVector :: Row a -> Result (Vector a) #

Zero or more rows packed into the vector.

It's recommended to prefer this function to `rowsList`, since it performs notably better.

rowsList :: Row a -> Result [a] #

Zero or more rows packed into the list.

## Multi-row traversers

foldlRows :: (a -> b -> a) -> a -> Row b -> Result a #

Foldl multiple rows.

foldrRows :: (b -> a -> a) -> a -> Row b -> Result a #

Foldr multiple rows.

# Row

data Row a #

Decoder of an individual row, which gets composed of column value decoders.

E.g.:

    x :: Row (Maybe Int64, Text, TimeOfDay)
    x =
      (,,) <$> nullableValue int8 <*> value text <*> value time

Instances

Monad Row # |
Methods (>>=) :: Row a -> (a -> Row b) -> Row b # (>>) :: Row a -> Row b -> Row b # return :: a -> Row a # fail :: String -> Row a #
Functor Row # |
Methods fmap :: (a -> b) -> Row a -> Row b # (<$) :: a -> Row b -> Row a #
Applicative Row # |
Methods pure :: a -> Row a # (<*>) :: Row (a -> b) -> Row a -> Row b # (*>) :: Row a -> Row b -> Row b # (<*) :: Row a -> Row b -> Row a #
Default (Value a) => Default (Row (Maybe a)) # |
Methods def :: Row (Maybe a) #
(Default (Value a1), Default (Value a2)) => Default (Row (a1, a2)) # |
Methods def :: Row (a1, a2) #
Default (Value a) => Default (Row (Identity a)) # |
Methods def :: Row (Identity a) #

value :: Value a -> Row a #

Lift an individual non-nullable value decoder to a composable row decoder.

nullableValue :: Value a -> Row (Maybe a) #

Lift an individual nullable value decoder to a composable row decoder.

# Value

data Value a #

Decoder of an individual value.

Instances

Functor Value # |
Methods fmap :: (a -> b) -> Value a -> Value b # (<$) :: a -> Value b -> Value a #
Default (Value Bool) # | Maps to `bool`.
Methods def :: Value Bool #
Default (Value Char) # | Maps to `char`.
Methods def :: Value Char #
Default (Value Double) # | Maps to `float8`.
Methods def :: Value Double #
Default (Value Float) # | Maps to `float4`.
Methods def :: Value Float #
Default (Value Int16) # | Maps to `int2`.
Methods def :: Value Int16 #
Default (Value Int32) # | Maps to `int4`.
Methods def :: Value Int32 #
Default (Value Int64) # | Maps to `int8`.
Methods def :: Value Int64 #
Default (Value (TimeOfDay, TimeZone)) # | Maps to `timetz`.
Methods def :: Value (TimeOfDay, TimeZone) #
Default (Value ByteString) # | Maps to `bytea`.
Methods def :: Value ByteString #
Default (Value Scientific) # | Maps to `numeric`.
Methods def :: Value Scientific #
Default (Value Text) # | Maps to `text`.
Methods def :: Value Text #
Default (Value UTCTime) # | Maps to `timestamptz`.
Methods def :: Value UTCTime #
Default (Value Value) # | Maps to `json`.
Methods def :: Value Value #
Default (Value UUID) # | Maps to `uuid`.
Methods def :: Value UUID #
Default (Value DiffTime) # | Maps to `interval`.
Methods def :: Value DiffTime #
Default (Value Day) # | Maps to `date`.
Methods def :: Value Day #
Default (Value TimeOfDay) # | Maps to `time`.
Methods def :: Value TimeOfDay #
Default (Value LocalTime) # | Maps to `timestamp`.
Methods def :: Value LocalTime #

bool :: Value Bool #

Decoder of the `BOOL` values.

int2 :: Value Int16 #

Decoder of the `INT2` values.

int4 :: Value Int32 #

Decoder of the `INT4` values.

int8 :: Value Int64 #

Decoder of the `INT8` values.

float4 :: Value Float #

Decoder of the `FLOAT4` values.

float8 :: Value Double #

Decoder of the `FLOAT8` values.

numeric :: Value Scientific #

Decoder of the `NUMERIC` values.

char :: Value Char #

Decoder of the `CHAR` values. Note that it supports UTF-8 values.

text :: Value Text #

Decoder of the `TEXT` values.

bytea :: Value ByteString #

Decoder of the `BYTEA` values.

date :: Value Day #

Decoder of the `DATE` values.

timestamp :: Value LocalTime #

Decoder of the `TIMESTAMP` values.

timestamptz :: Value UTCTime #

Decoder of the `TIMESTAMPTZ` values.

NOTICE

Postgres does not store the timezone information of `TIMESTAMPTZ`. Instead it stores a UTC value and performs silent conversions to the currently set timezone, when dealt with in the text format. However this library bypasses the silent conversions and communicates with Postgres using the UTC values directly.

time :: Value TimeOfDay #

Decoder of the `TIME` values.

timetz :: Value (TimeOfDay, TimeZone) #

Decoder of the `TIMETZ` values.

Unlike in case of `TIMESTAMPTZ`, Postgres does store the timezone information for `TIMETZ`. However the Haskell's "time" library does not contain any composite type, that fits the task, so we use a pair of `TimeOfDay` and `TimeZone` to represent a value on the Haskell's side.

interval :: Value DiffTime #

Decoder of the `INTERVAL` values.

uuid :: Value UUID #

Decoder of the `UUID` values.

inet :: Value (NetAddr IP) #

Decoder of the `INET` values.

json :: Value Value #

Decoder of the `JSON` values into a JSON AST.

jsonBytes :: (ByteString -> Either Text a) -> Value a #

Decoder of the `JSON` values into a raw JSON `ByteString`.

jsonb :: Value Value #

Decoder of the `JSONB` values into a JSON AST.

jsonbBytes :: (ByteString -> Either Text a) -> Value a #

Decoder of the `JSONB` values into a raw JSON `ByteString`.

array :: Array a -> Value a #

Lifts the `Array` decoder to the `Value` decoder.

composite :: Composite a -> Value a #

Lifts the `Composite` decoder to the `Value` decoder.

hstore :: (forall m. Monad m => Int -> m (Text, Maybe Text) -> m a) -> Value a #

A generic decoder of `HSTORE` values.

Here's how you can use it to construct a specific value:

    x :: Value [(Text, Maybe Text)]
    x =
      hstore replicateM

enum :: (Text -> Maybe a) -> Value a #

Given a partial mapping from text to value, produces a decoder of that value.

custom :: (Bool -> ByteString -> Either Text a) -> Value a #

Lifts a custom value decoder function to a `Value` decoder.

# Array

data Array a #

A generic array decoder.

Here's how you can use it to produce a specific array value decoder:

    x :: Value [[Text]]
    x =
      array (arrayDimension replicateM (arrayDimension replicateM (arrayValue text)))

Instances

Functor Array # |
Methods fmap :: (a -> b) -> Array a -> Array b # (<$) :: a -> Array b -> Array a #

arrayDimension :: (forall m. Monad m => Int -> m a -> m b) -> Array a -> Array b #

A function for parsing a dimension of an array. Provides support for multi-dimensional arrays.

Accepts:

- An implementation of the `replicateM` function (`Control.Monad.`replicateM``, `Data.Vector.`replicateM``), which determines the output value.
- A decoder of its components, which can be either another `arrayDimension`, `arrayValue` or `arrayNullableValue`.

arrayValue :: Value a -> Array a #

Lift a `Value` decoder into an `Array` decoder for parsing of non-nullable leaf values.

arrayNullableValue :: Value a -> Array (Maybe a) #

Lift a `Value` decoder into an `Array` decoder for parsing of nullable leaf values.

# Composite

data Composite a #

Composable decoder of composite values (rows, records).

Instances

Monad Composite # |
Methods (>>=) :: Composite a -> (a -> Composite b) -> Composite b # (>>) :: Composite a -> Composite b -> Composite b # return :: a -> Composite a # fail :: String -> Composite a #
Functor Composite # |
Methods fmap :: (a -> b) -> Composite a -> Composite b # (<$) :: a -> Composite b -> Composite a #
Applicative Composite # |
Methods pure :: a -> Composite a # (<*>) :: Composite (a -> b) -> Composite a -> Composite b # (*>) :: Composite a -> Composite b -> Composite b # (<*) :: Composite a -> Composite b -> Composite a #

compositeValue :: Value a -> Composite a #

Lift a `Value` decoder into a `Composite` decoder for parsing of non-nullable leaf values.

compositeNullableValue :: Value a -> Composite (Maybe a) #

Lift a `Value` decoder into a `Composite` decoder for parsing of nullable leaf values.