Safe Haskell	None
Language	Haskell2010

Hasql.Decoders

Contents

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

Description

A DSL for declaration of result decoders.

Synopsis

data Result a
noResult :: Result ()
rowsAffected :: Result Int64
singleRow :: Row a -> Result a
rowMaybe :: Row a -> Result (Maybe a)
rowVector :: Row a -> Result (Vector a)
rowList :: 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
column :: NullableOrNot Value a -> Row a
data NullableOrNot (decoder :: Type -> Type) a
nonNullable :: decoder a -> NullableOrNot decoder a
nullable :: decoder a -> NullableOrNot decoder (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
varchar :: Value Text
bpchar :: 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 IPRange
macaddr :: Value (Word8, Word8, Word8, Word8, Word8, Word8)
json :: Value Value
jsonBytes :: (ByteString -> Either Text a) -> Value a
jsonb :: Value Value
jsonbBytes :: (ByteString -> Either Text a) -> Value a
int4range :: Value (Range Int32)
int8range :: Value (Range Int64)
numrange :: Value (Range Scientific)
tsrange :: Value (Range LocalTime)
tstzrange :: Value (Range UTCTime)
daterange :: Value (Range Day)
int4multirange :: Value (Multirange Int32)
int8multirange :: Value (Multirange Int64)
nummultirange :: Value (Multirange Scientific)
tsmultirange :: Value (Multirange LocalTime)
tstzmultirange :: Value (Multirange UTCTime)
datemultirange :: Value (Multirange Day)
citext :: Value Text
array :: Array a -> Value a
listArray :: NullableOrNot Value element -> Value [element]
vectorArray :: Vector vector element => NullableOrNot Value element -> Value (vector element)
composite :: Maybe Text -> Text -> Composite a -> Value a
record :: Composite a -> Value a
hstore :: (forall (m :: Type -> Type). Monad m => Int -> m (Text, Maybe Text) -> m a) -> Value a
enum :: Maybe Text -> Text -> (Text -> Maybe a) -> Value a
custom :: Maybe Text -> Text -> Maybe (Word32, Word32) -> [(Maybe Text, Text)] -> (((Maybe Text, Text) -> (Word32, Word32)) -> ByteString -> Either Text a) -> Value a
refine :: (a -> Either Text b) -> Value a -> Value b
data Array a
dimension :: (forall (m :: Type -> Type). Monad m => Int -> m a -> m b) -> Array a -> Array b
element :: NullableOrNot Value a -> Array a
data Composite a
field :: NullableOrNot Value a -> Composite a

Result

data Result a Source #

Decoder of a query result.

Instances

Instances details

Applicative Result Source #
Instance details Defined in Hasql.Engine.Decoders.Result Methods pure :: a -> Result a # (<>) :: Result (a -> b) -> Result a -> Result b # liftA2 :: (a -> b -> c) -> Result a -> Result b -> Result c # (>) :: Result a -> Result b -> Result b # (<*) :: Result a -> Result b -> Result a #
Functor Result Source #
Instance details Defined in Hasql.Engine.Decoders.Result Methods fmap :: (a -> b) -> Result a -> Result b # (<$) :: a -> Result b -> Result a #
Filterable Result Source #
Instance details Defined in Hasql.Engine.Decoders.Result Methods mapMaybe :: (a -> Maybe b) -> Result a -> Result b Source # catMaybes :: Result (Maybe a) -> Result a Source # filter :: (a -> Bool) -> Result a -> Result a Source # drain :: Result a -> Result b Source #

noResult :: Result () Source #

Decode no value from the result.

Useful for statements like INSERT or CREATE.

rowsAffected :: Result Int64 Source #

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

singleRow :: Row a -> Result a Source #

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

Specialized multi-row results

rowMaybe :: Row a -> Result (Maybe a) Source #

Maybe one row or none.

rowVector :: Row a -> Result (Vector a) Source #

Zero or more rows packed into the vector.

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

rowList :: Row a -> Result [a] Source #

Zero or more rows packed into the list.

Multi-row traversers

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

Foldl multiple rows.

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

Foldr multiple rows.

Row

data Row a Source #

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

x :: Row (Maybe Int64, Text, TimeOfDay)
x = (,,) <$> (column . nullable) int8 <*> (column . nonNullable) text <*> (column . nonNullable) time

Instances

Instances details

Applicative Row Source #
Instance details Defined in Hasql.Engine.Decoders.Row Methods pure :: a -> Row a # (<>) :: Row (a -> b) -> Row a -> Row b # liftA2 :: (a -> b -> c) -> Row a -> Row b -> Row c # (>) :: Row a -> Row b -> Row b # (<*) :: Row a -> Row b -> Row a #
Functor Row Source #
Instance details Defined in Hasql.Engine.Decoders.Row Methods fmap :: (a -> b) -> Row a -> Row b # (<$) :: a -> Row b -> Row a #
Filterable Row Source #
Instance details Defined in Hasql.Engine.Decoders.Row Methods mapMaybe :: (a -> Maybe b) -> Row a -> Row b Source # catMaybes :: Row (Maybe a) -> Row a Source # filter :: (a -> Bool) -> Row a -> Row a Source # drain :: Row a -> Row b Source #

column :: NullableOrNot Value a -> Row a Source #

Lift an individual value decoder to a composable row decoder.

Nullability

data NullableOrNot (decoder :: Type -> Type) a Source #

Extensional specification of nullability over a generic decoder.

nonNullable :: decoder a -> NullableOrNot decoder a Source #

Specify that a decoder produces a non-nullable value.

nullable :: decoder a -> NullableOrNot decoder (Maybe a) Source #

Specify that a decoder produces a nullable value.

Value

data Value a Source #

Value decoder.

Instances

Instances details

Functor Value Source #
Instance details Defined in Hasql.Codecs.Decoders.Value Methods fmap :: (a -> b) -> Value a -> Value b # (<$) :: a -> Value b -> Value a #
Filterable Value Source #
Instance details Defined in Hasql.Codecs.Decoders.Value Methods mapMaybe :: (a -> Maybe b) -> Value a -> Value b Source # catMaybes :: Value (Maybe a) -> Value a Source # filter :: (a -> Bool) -> Value a -> Value a Source # drain :: Value a -> Value b Source #

bool :: Value Bool Source #

Decoder of the BOOL values.

int2 :: Value Int16 Source #

Decoder of the INT2 values.

int4 :: Value Int32 Source #

Decoder of the INT4 values.

int8 :: Value Int64 Source #

Decoder of the INT8 values.

float4 :: Value Float Source #

Decoder of the FLOAT4 values.

float8 :: Value Double Source #

Decoder of the FLOAT8 values.

numeric :: Value Scientific Source #

Decoder of the NUMERIC values.

char :: Value Char Source #

Decoder of the CHAR values. Note that it supports Unicode values.

text :: Value Text Source #

Decoder of the TEXT values.

varchar :: Value Text Source #

Decoder of the VARCHAR values.

bpchar :: Value Text Source #

Decoder of BPCHAR or CHAR(n), CHARACTER(n) values.

bytea :: Value ByteString Source #

Decoder of the BYTEA values.

date :: Value Day Source #

Decoder of the DATE values.

timestamp :: Value LocalTime Source #

Decoder of the TIMESTAMP values.

timestamptz :: Value UTCTime Source #

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 Source #

Decoder of the TIME values.

timetz :: Value (TimeOfDay, TimeZone) Source #

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 Source #

Decoder of the INTERVAL values.

uuid :: Value UUID Source #

Decoder of the UUID values.

inet :: Value IPRange Source #

Decoder of the INET values.

macaddr :: Value (Word8, Word8, Word8, Word8, Word8, Word8) Source #

Decoder of the MACADDR values.

Represented as a 6-tuple of Word8 values in big endian order. If you use ip library consider using it with fromOctets.

(\(a,b,c,d,e,f) -> fromOctets a b c d e f) <$> macaddr

json :: Value Value Source #

Decoder of the JSON values into a JSON AST.

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

Decoder of the JSON values into a raw JSON ByteString.

jsonb :: Value Value Source #

Decoder of the JSONB values into a JSON AST.

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

Decoder of the JSONB values into a raw JSON ByteString.

int4range :: Value (Range Int32) Source #

Decoder of the INT4RANGE values.

int8range :: Value (Range Int64) Source #

Decoder of the INT8RANGE values.

numrange :: Value (Range Scientific) Source #

Decoder of the NUMRANGE values.

tsrange :: Value (Range LocalTime) Source #

Decoder of the TSRANGE values.

tstzrange :: Value (Range UTCTime) Source #

Decoder of the TSTZRANGE values.

daterange :: Value (Range Day) Source #

Decoder of the DATERANGE values.

int4multirange :: Value (Multirange Int32) Source #

Decoder of the INT4MULTIRANGE values.

int8multirange :: Value (Multirange Int64) Source #

Decoder of the INT8MULTIRANGE values.

nummultirange :: Value (Multirange Scientific) Source #

Decoder of the NUMMULTIRANGE values.

tsmultirange :: Value (Multirange LocalTime) Source #

Decoder of the TSMULTIRANGE values.

tstzmultirange :: Value (Multirange UTCTime) Source #

Decoder of the TSTZMULTIRANGE values.

datemultirange :: Value (Multirange Day) Source #

Decoder of the DATEMULTIRANGE values.

citext :: Value Text Source #

Decoder of the CITEXT values.

Requires the citext extension to be installed in the database.

array :: Array a -> Value a Source #

Lift an Array decoder to a Value decoder.

listArray :: NullableOrNot Value element -> Value [element] Source #

Lift a value decoder of element into a unidimensional array decoder producing a list.

This function is merely a shortcut to the following expression:

(array . dimension Control.Monad.replicateM . element)

Please notice that in case of multidimensional arrays nesting listArray decoder won't work. You have to explicitly construct the array decoder using array.

vectorArray :: Vector vector element => NullableOrNot Value element -> Value (vector element) Source #

Lift a value decoder of element into a unidimensional array decoder producing a generic vector.

This function is merely a shortcut to the following expression:

(array . dimension Data.Vector.Generic.replicateM . element)

Please notice that in case of multidimensional arrays nesting vectorArray decoder won't work. You have to explicitly construct the array decoder using array.

composite :: Maybe Text -> Text -> Composite a -> Value a Source #

Lift a Composite decoder to a Value decoder for named composite types.

This function is for named composite types where the type name is known. For anonymous composite types (like those created with ROW constructor), use record instead.

record :: Composite a -> Value a Source #

Lift a Composite decoder to a Value decoder for unnamed composite types.

This is useful for decoding anonymous composites (like those created with ROW constructor) where no type name is required. Postgres will handle the type automatically.

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

Binary 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 Source #

Arguments

:: Maybe Text	Schema name.
-> Text	Type name.
-> (Text -> Maybe a)	Mapping from text to value.
-> Value a

Given a partial mapping from text to value, produces a decoder of that value for a named enum type.

custom Source #

Arguments

:: Maybe Text	Schema name.
-> Text	Type name.
-> Maybe (Word32, Word32)	Possible static OIDs for the type. The first is for scalar values the second is for arrays. When unspecified, the OIDs will be automatically determined at runtime by looking up by name.
-> [(Maybe Text, Text)]	Other named types whose OIDs are needed for deserializing. E.g., when decoding composite types you can check the OIDs of its fields against the ones specified by Postgres. When any of the requested types is missing in the database an error will be raised upon the statement execution.
-> (((Maybe Text, Text) -> (Word32, Word32)) -> ByteString -> Either Text a)	Deserialization function in the context of resolved OIDs of the types requested in the previous parameter. It's safe to assume that all of the requested types will be present. In case you run the provided lookup function with unmentioned type names it will produce OID of 0 for them, standing for unknown type in Postgres.
-> Value a

Low level API for defining custom value decoders.

refine :: (a -> Either Text b) -> Value a -> Value b Source #

Refine a value decoder, lifting the possible error to the session level.

Array

data Array a Source #

Binary generic array decoder.

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

x :: Value [[Text]]
x = array (dimension replicateM (dimension replicateM (element (nonNullable text))))

Instances

Instances details

Functor Array Source #
Instance details Defined in Hasql.Codecs.Decoders.Array Methods fmap :: (a -> b) -> Array a -> Array b # (<$) :: a -> Array b -> Array a #

dimension :: (forall (m :: Type -> Type). Monad m => Int -> m a -> m b) -> Array a -> Array b Source #

Binary 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.
Binary decoder of its components, which can be either another dimension or element.

element :: NullableOrNot Value a -> Array a Source #

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

Composite

data Composite a Source #

Composable decoder of composite values (rows, records).

Instances

Instances details

Applicative Composite Source #
Instance details Defined in Hasql.Codecs.Decoders.Composite Methods pure :: a -> Composite a # (<>) :: Composite (a -> b) -> Composite a -> Composite b # liftA2 :: (a -> b -> c) -> Composite a -> Composite b -> Composite c # (>) :: Composite a -> Composite b -> Composite b # (<*) :: Composite a -> Composite b -> Composite a #
Functor Composite Source #
Instance details Defined in Hasql.Codecs.Decoders.Composite Methods fmap :: (a -> b) -> Composite a -> Composite b # (<$) :: a -> Composite b -> Composite a #

field :: NullableOrNot Value a -> Composite a Source #

Lift a Value decoder into a Composite decoder for parsing of component values.