-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An efficient PostgreSQL driver with a flexible mapping API
--   
--   Root of the "hasql" ecosystem. For details and tutorials see <a>the
--   readme</a>.
--   
--   The API comes free from all kinds of exceptions. All error-reporting
--   is explicit and is presented using the <a>Either</a> type.
@package hasql
@version 1.6.1.1


-- | A DSL for declaration of statement parameter encoders.
--   
--   For compactness of names all the types defined here imply being an
--   encoder. E.g., the <a>Array</a> type is an <b>encoder</b> of arrays,
--   not the data-structure itself.
module Hasql.Encoders

-- | Encoder of some representation of a parameters product.
--   
--   Has instances of <a>Contravariant</a>, <a>Divisible</a> and
--   <a>Monoid</a>, which you can use to compose multiple parameters
--   together. E.g.,
--   
--   <pre>
--   someParamsEncoder :: <a>Params</a> (Int64, Maybe Text)
--   someParamsEncoder =
--     (<a>fst</a> <a>&gt;$&lt;</a> <a>param</a> (<a>nonNullable</a> <a>int8</a>)) <a>&lt;&gt;</a>
--     (<a>snd</a> <a>&gt;$&lt;</a> <a>param</a> (<a>nullable</a> <a>text</a>))
--   </pre>
--   
--   As a general solution for tuples of any arity, instead of <a>fst</a>
--   and <a>snd</a>, consider the functions of the <tt>contrazip</tt>
--   family from the "contravariant-extras" package. E.g., here's how you
--   can achieve the same as the above:
--   
--   <pre>
--   someParamsEncoder :: <a>Params</a> (Int64, Maybe Text)
--   someParamsEncoder =
--     <tt>contrazip2</tt> (<a>param</a> (<a>nonNullable</a> <a>int8</a>)) (<a>param</a> (<a>nullable</a> <a>text</a>))
--   </pre>
--   
--   Here's how you can implement encoders for custom composite types:
--   
--   <pre>
--   data Person = Person { name :: Text, gender :: Gender, age :: Int }
--   
--   data Gender = Male | Female
--   
--   personParams :: <a>Params</a> Person
--   personParams =
--     (name <a>&gt;$&lt;</a> <a>param</a> (<a>nonNullable</a> <a>text</a>)) <a>&lt;&gt;</a>
--     (gender <a>&gt;$&lt;</a> <a>param</a> (<a>nonNullable</a> genderValue)) <a>&lt;&gt;</a>
--     (<a>fromIntegral</a> . age <a>&gt;$&lt;</a> <a>param</a> (<a>nonNullable</a> <a>int8</a>))
--   
--   genderValue :: <a>Value</a> Gender
--   genderValue = <a>enum</a> genderText <a>text</a> where
--     genderText gender = case gender of
--       Male -&gt; "male"
--       Female -&gt; "female"
--   </pre>
data Params a

-- | No parameters. Same as <a>mempty</a> and <a>conquered</a>.
noParams :: Params ()

-- | Lift a single parameter encoder, with its nullability specified,
--   associating it with a single placeholder.
param :: NullableOrNot Value a -> Params a

-- | Extensional specification of nullability over a generic encoder.
data NullableOrNot encoder a

-- | Specify that an encoder produces a non-nullable value.
nonNullable :: encoder a -> NullableOrNot encoder a

-- | Specify that an encoder produces a nullable value.
nullable :: encoder a -> NullableOrNot encoder (Maybe a)

-- | Value encoder.
data Value a

-- | Encoder of <tt>BOOL</tt> values.
bool :: Value Bool

-- | Encoder of <tt>INT2</tt> values.
int2 :: Value Int16

-- | Encoder of <tt>INT4</tt> values.
int4 :: Value Int32

-- | Encoder of <tt>INT8</tt> values.
int8 :: Value Int64

-- | Encoder of <tt>FLOAT4</tt> values.
float4 :: Value Float

-- | Encoder of <tt>FLOAT8</tt> values.
float8 :: Value Double

-- | Encoder of <tt>NUMERIC</tt> values.
numeric :: Value Scientific

-- | Encoder of <tt>CHAR</tt> values.
--   
--   Note that it supports Unicode values and identifies itself under the
--   <tt>TEXT</tt> OID because of that.
char :: Value Char

-- | Encoder of <tt>TEXT</tt> values.
text :: Value Text

-- | Encoder of <tt>BYTEA</tt> values.
bytea :: Value ByteString

-- | Encoder of <tt>DATE</tt> values.
date :: Value Day

-- | Encoder of <tt>TIMESTAMP</tt> values.
timestamp :: Value LocalTime

-- | Encoder of <tt>TIMESTAMPTZ</tt> values.
timestamptz :: Value UTCTime

-- | Encoder of <tt>TIME</tt> values.
time :: Value TimeOfDay

-- | Encoder of <tt>TIMETZ</tt> values.
timetz :: Value (TimeOfDay, TimeZone)

-- | Encoder of <tt>INTERVAL</tt> values.
interval :: Value DiffTime

-- | Encoder of <tt>UUID</tt> values.
uuid :: Value UUID

-- | Encoder of <tt>INET</tt> values.
inet :: Value (NetAddr IP)

-- | Encoder of <tt>JSON</tt> values from JSON AST.
json :: Value Value

-- | Encoder of <tt>JSON</tt> values from raw JSON.
jsonBytes :: Value ByteString

-- | Encoder of <tt>JSON</tt> values from raw JSON as lazy ByteString.
jsonLazyBytes :: Value ByteString

-- | Encoder of <tt>JSONB</tt> values from JSON AST.
jsonb :: Value Value

-- | Encoder of <tt>JSONB</tt> values from raw JSON.
jsonbBytes :: Value ByteString

-- | Encoder of <tt>JSONB</tt> values from raw JSON as lazy ByteString.
jsonbLazyBytes :: Value ByteString

-- | Given a function, which maps a value into a textual enum label used on
--   the DB side, produces an encoder of that value.
enum :: (a -> Text) -> Value a

-- | Identifies the value with the PostgreSQL's "unknown" type, thus
--   leaving it up to Postgres to infer the actual type of the value.
--   
--   The value transimitted is any value encoded in the Postgres' Text data
--   format. For reference, see the <a>Formats and Format Codes</a> section
--   of the Postgres' documentation.
--   
--   <b>Warning:</b> Do not use this as part of composite encoders like
--   <a>array</a> since it is the only encoder that doesn't use the binary
--   format.
unknown :: Value ByteString

-- | Lift an array encoder into a parameter encoder.
array :: Array a -> Value a

-- | Lift a value encoder of element into a unidimensional array encoder of
--   a foldable value.
--   
--   This function is merely a shortcut to the following expression:
--   
--   <pre>
--   (<a>array</a> . <a>dimension</a> <a>foldl'</a> . <a>element</a>)
--   </pre>
--   
--   You can use it like this:
--   
--   <pre>
--   vectorOfInts :: Value (Vector Int64)
--   vectorOfInts = <a>foldableArray</a> (<a>nonNullable</a> <a>int8</a>)
--   </pre>
--   
--   Please notice that in case of multidimensional arrays nesting
--   <a>foldableArray</a> encoder won't work. You have to explicitly
--   construct the array encoder using <a>array</a>.
foldableArray :: Foldable foldable => NullableOrNot Value element -> Value (foldable element)

-- | Generic array encoder.
--   
--   Here's an example of its usage:
--   
--   <pre>
--   someParamsEncoder :: <a>Params</a> [[Int64]]
--   someParamsEncoder = <a>param</a> (<a>nonNullable</a> (<a>array</a> (<a>dimension</a> <a>foldl'</a> (<a>dimension</a> <a>foldl'</a> (<a>element</a> (<a>nonNullable</a> <a>int8</a>))))))
--   </pre>
--   
--   Please note that the PostgreSQL <tt>IN</tt> keyword does not accept an
--   array, but rather a syntactical list of values, thus this encoder is
--   not suited for that. Use a <tt>value = ANY($1)</tt> condition instead.
data Array a

-- | Lifts a <a>Value</a> encoder into an <a>Array</a> encoder.
element :: NullableOrNot Value a -> Array a

-- | Encoder of an array dimension, which thus provides support for
--   multidimensional arrays.
--   
--   Accepts:
--   
--   <ul>
--   <li>An implementation of the left-fold operation, such as
--   <tt>Data.Foldable.<a>foldl'</a></tt>, which determines the input
--   value.</li>
--   <li>A component encoder, which can be either another <a>dimension</a>
--   or <a>element</a>.</li>
--   </ul>
dimension :: (forall a. (a -> b -> a) -> a -> c -> a) -> Array b -> Array c


-- | A DSL for declaration of result decoders.
module Hasql.Decoders

-- | Decoder of a query result.
data Result a

-- | Decode no value from the result.
--   
--   Useful for statements like <tt>INSERT</tt> or <tt>CREATE</tt>.
noResult :: Result ()

-- | Get the amount of rows affected by such statements as <tt>UPDATE</tt>
--   or <tt>DELETE</tt>.
rowsAffected :: Result Int64

-- | Exactly one row. Will raise the <a>UnexpectedAmountOfRows</a> error if
--   it's any other.
singleRow :: Row a -> Result a

-- | Maybe one row or none.
rowMaybe :: Row a -> Result (Maybe a)

-- | Zero or more rows packed into the vector.
--   
--   It's recommended to prefer this function to <a>rowList</a>, since it
--   performs notably better.
rowVector :: Row a -> Result (Vector a)

-- | Zero or more rows packed into the list.
rowList :: Row a -> Result [a]

-- | Foldl multiple rows.
foldlRows :: (a -> b -> a) -> a -> Row b -> Result a

-- | Foldr multiple rows.
foldrRows :: (b -> a -> a) -> a -> Row b -> Result a

-- | Decoder of an individual row, which gets composed of column value
--   decoders.
--   
--   E.g.:
--   
--   <pre>
--   x :: <a>Row</a> (Maybe Int64, Text, TimeOfDay)
--   x = (,,) <a>&lt;$&gt;</a> (<a>column</a> . <a>nullable</a>) <a>int8</a> <a>&lt;*&gt;</a> (<a>column</a> . <a>nonNullable</a>) <a>text</a> <a>&lt;*&gt;</a> (<a>column</a> . <a>nonNullable</a>) <a>time</a>
--   </pre>
data Row a

-- | Lift an individual value decoder to a composable row decoder.
column :: NullableOrNot Value a -> Row a

-- | Extensional specification of nullability over a generic decoder.
data NullableOrNot decoder a

-- | Specify that a decoder produces a non-nullable value.
nonNullable :: decoder a -> NullableOrNot decoder a

-- | Specify that a decoder produces a nullable value.
nullable :: decoder a -> NullableOrNot decoder (Maybe a)

-- | Decoder of a value.
data Value a

-- | Decoder of the <tt>BOOL</tt> values.
bool :: Value Bool

-- | Decoder of the <tt>INT2</tt> values.
int2 :: Value Int16

-- | Decoder of the <tt>INT4</tt> values.
int4 :: Value Int32

-- | Decoder of the <tt>INT8</tt> values.
int8 :: Value Int64

-- | Decoder of the <tt>FLOAT4</tt> values.
float4 :: Value Float

-- | Decoder of the <tt>FLOAT8</tt> values.
float8 :: Value Double

-- | Decoder of the <tt>NUMERIC</tt> values.
numeric :: Value Scientific

-- | Decoder of the <tt>CHAR</tt> values. Note that it supports Unicode
--   values.
char :: Value Char

-- | Decoder of the <tt>TEXT</tt> values.
text :: Value Text

-- | Decoder of the <tt>BYTEA</tt> values.
bytea :: Value ByteString

-- | Decoder of the <tt>DATE</tt> values.
date :: Value Day

-- | Decoder of the <tt>TIMESTAMP</tt> values.
timestamp :: Value LocalTime

-- | Decoder of the <tt>TIMESTAMPTZ</tt> values.
--   
--   <i>NOTICE</i>
--   
--   Postgres does not store the timezone information of
--   <tt>TIMESTAMPTZ</tt>. 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.
timestamptz :: Value UTCTime

-- | Decoder of the <tt>TIME</tt> values.
time :: Value TimeOfDay

-- | Decoder of the <tt>TIMETZ</tt> values.
--   
--   Unlike in case of <tt>TIMESTAMPTZ</tt>, Postgres does store the
--   timezone information for <tt>TIMETZ</tt>. However the Haskell's "time"
--   library does not contain any composite type, that fits the task, so we
--   use a pair of <tt>TimeOfDay</tt> and <tt>TimeZone</tt> to represent a
--   value on the Haskell's side.
timetz :: Value (TimeOfDay, TimeZone)

-- | Decoder of the <tt>INTERVAL</tt> values.
interval :: Value DiffTime

-- | Decoder of the <tt>UUID</tt> values.
uuid :: Value UUID

-- | Decoder of the <tt>INET</tt> values.
inet :: Value (NetAddr IP)

-- | Decoder of the <tt>JSON</tt> values into a JSON AST.
json :: Value Value

-- | Decoder of the <tt>JSON</tt> values into a raw JSON <a>ByteString</a>.
jsonBytes :: (ByteString -> Either Text a) -> Value a

-- | Decoder of the <tt>JSONB</tt> values into a JSON AST.
jsonb :: Value Value

-- | Decoder of the <tt>JSONB</tt> values into a raw JSON
--   <a>ByteString</a>.
jsonbBytes :: (ByteString -> Either Text a) -> Value a

-- | Lift an <a>Array</a> decoder to a <a>Value</a> decoder.
array :: Array a -> Value a

-- | Lift a value decoder of element into a unidimensional array decoder
--   producing a list.
--   
--   This function is merely a shortcut to the following expression:
--   
--   <pre>
--   (<a>array</a> . <a>dimension</a> Control.Monad.<a>replicateM</a> . <a>element</a>)
--   </pre>
--   
--   Please notice that in case of multidimensional arrays nesting
--   <a>listArray</a> decoder won't work. You have to explicitly construct
--   the array decoder using <a>array</a>.
listArray :: NullableOrNot Value element -> Value [element]

-- | 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:
--   
--   <pre>
--   (<a>array</a> . <a>dimension</a> Data.Vector.Generic.<a>replicateM</a> . <a>element</a>)
--   </pre>
--   
--   Please notice that in case of multidimensional arrays nesting
--   <a>vectorArray</a> decoder won't work. You have to explicitly
--   construct the array decoder using <a>array</a>.
vectorArray :: Vector vector element => NullableOrNot Value element -> Value (vector element)

-- | Lift a <a>Composite</a> decoder to a <a>Value</a> decoder.
composite :: Composite a -> Value a

-- | A generic decoder of <tt>HSTORE</tt> values.
--   
--   Here's how you can use it to construct a specific value:
--   
--   <pre>
--   x :: Value [(Text, Maybe Text)]
--   x = hstore <a>replicateM</a>
--   </pre>
hstore :: (forall m. Monad m => Int -> m (Text, Maybe Text) -> m a) -> Value a

-- | Given a partial mapping from text to value, produces a decoder of that
--   value.
enum :: (Text -> Maybe a) -> Value a

-- | Lift a custom value decoder function to a <a>Value</a> decoder.
custom :: (Bool -> ByteString -> Either Text a) -> Value a

-- | Refine a value decoder, lifting the possible error to the session
--   level.
refine :: (a -> Either Text b) -> Value a -> Value b

-- | A generic array decoder.
--   
--   Here's how you can use it to produce a specific array value decoder:
--   
--   <pre>
--   x :: <a>Value</a> [[Text]]
--   x = <a>array</a> (<a>dimension</a> <a>replicateM</a> (<a>dimension</a> <a>replicateM</a> (<a>element</a> (<a>nonNullable</a> <a>text</a>))))
--   </pre>
data Array a

-- | A function for parsing a dimension of an array. Provides support for
--   multi-dimensional arrays.
--   
--   Accepts:
--   
--   <ul>
--   <li>An implementation of the <tt>replicateM</tt> function
--   (<tt>Control.Monad.<a>replicateM</a></tt>,
--   <tt>Data.Vector.<a>replicateM</a></tt>), which determines the output
--   value.</li>
--   <li>A decoder of its components, which can be either another
--   <a>dimension</a> or <a>element</a>.</li>
--   </ul>
dimension :: (forall m. Monad m => Int -> m a -> m b) -> Array a -> Array b

-- | Lift a <a>Value</a> decoder into an <a>Array</a> decoder for parsing
--   of leaf values.
element :: NullableOrNot Value a -> Array a

-- | Composable decoder of composite values (rows, records).
data Composite a

-- | Lift a <a>Value</a> decoder into a <a>Composite</a> decoder for
--   parsing of component values.
field :: NullableOrNot Value a -> Composite a


-- | This module provides a low-level effectful API dealing with the
--   connections to the database.
module Hasql.Connection

-- | A single connection to the database.
data Connection

-- | Possible details of the connection acquistion error.
type ConnectionError = Maybe ByteString

-- | Acquire a connection using the provided settings encoded according to
--   the PostgreSQL format.
acquire :: Settings -> IO (Either ConnectionError Connection)

-- | Release the connection.
release :: Connection -> IO ()

-- | All settings encoded in a single byte-string according to <a>the
--   PostgreSQL format</a>.
type Settings = ByteString

-- | Encode a host, a port, a user, a password and a database into the
--   PostgreSQL settings byte-string.
settings :: ByteString -> Word16 -> ByteString -> ByteString -> ByteString -> Settings

-- | Execute an operation on the raw <tt>libpq</tt> <a>Connection</a>.
--   
--   The access to the connection is exclusive.
withLibPQConnection :: Connection -> (Connection -> IO a) -> IO a

module Hasql.Statement

-- | Specification of a strictly single-statement query, which can be
--   parameterized and prepared.
--   
--   Consists of the following:
--   
--   <ul>
--   <li>SQL template,</li>
--   <li>params encoder,</li>
--   <li>result decoder,</li>
--   <li>a flag, determining whether it should be prepared.</li>
--   </ul>
--   
--   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 a
--   positional notation, as in the following: <tt>$1</tt>, <tt>$2</tt>,
--   <tt>$3</tt> and etc. Those references must be used in accordance with
--   the order in which the value encoders are specified in <a>Params</a>.
--   
--   Following is an example of a declaration of a prepared statement with
--   its associated codecs.
--   
--   <pre>
--   selectSum :: <a>Statement</a> (Int64, Int64) Int64
--   selectSum = <a>Statement</a> sql encoder decoder True where
--     sql = "select ($1 + $2)"
--     encoder =
--       (<a>fst</a> <a>&gt;$&lt;</a> Encoders.<a>param</a> (Encoders.<a>nonNullable</a> Encoders.<a>int8</a>)) <a>&lt;&gt;</a>
--       (<a>snd</a> <a>&gt;$&lt;</a> Encoders.<a>param</a> (Encoders.<a>nonNullable</a> Encoders.<a>int8</a>))
--     decoder = Decoders.<a>singleRow</a> (Decoders.<a>column</a> (Decoders.<a>nonNullable</a> Decoders.<a>int8</a>))
--   </pre>
--   
--   The statement above accepts a product of two parameters of type
--   <a>Int64</a> and produces a single result of type <a>Int64</a>.
data Statement a b
Statement :: ByteString -> Params a -> Result b -> Bool -> Statement a b

-- | Refine a result of a statement, causing the running session to fail
--   with the <tt>UnexpectedResult</tt> error in case of refinement
--   failure.
--   
--   This function is especially useful for refining the results of
--   statements produced with <a>the "hasql-th" library</a>.
refineResult :: (a -> Either Text b) -> Statement params a -> Statement params b
instance GHC.Base.Functor (Hasql.Statement.Statement a)
instance Data.Profunctor.Unsafe.Profunctor Hasql.Statement.Statement

module Hasql.Session

-- | A batch of actions to be executed in the context of a database
--   connection.
data Session a

-- | Possibly a multi-statement query, which however cannot be
--   parameterized or prepared, nor can any results of it be collected.
sql :: ByteString -> Session ()

-- | Parameters and a specification of a parametric single-statement query
--   to apply them to.
statement :: params -> Statement params result -> Session result

-- | Executes a bunch of commands on the provided connection.
run :: Session a -> Connection -> IO (Either QueryError a)

-- | An error during the execution of a query. Comes packed with the query
--   template and a textual representation of the provided params.
data QueryError
QueryError :: ByteString -> [Text] -> CommandError -> QueryError

-- | An error of some command in the session.
data CommandError

-- | An error on the client-side, with a message generated by the "libpq"
--   library. Usually indicates problems with connection.
ClientError :: Maybe ByteString -> CommandError

-- | Some error with a command result.
ResultError :: ResultError -> CommandError

-- | An error with a command result.
data ResultError

-- | An error reported by the DB.
ServerError :: ByteString -> ByteString -> Maybe ByteString -> Maybe ByteString -> Maybe Int -> ResultError

-- | The database returned an unexpected result. Indicates an improper
--   statement or a schema mismatch.
UnexpectedResult :: Text -> ResultError

-- | An error of the row reader, preceded by the indexes of the row and
--   column.
RowError :: Int -> Int -> RowError -> ResultError

-- | An unexpected amount of rows.
UnexpectedAmountOfRows :: Int -> ResultError

-- | An error during the decoding of a specific row.
data RowError

-- | Appears on the attempt to parse more columns than there are in the
--   result.
EndOfInput :: RowError

-- | Appears on the attempt to parse a <tt>NULL</tt> as some value.
UnexpectedNull :: RowError

-- | Appears when a wrong value parser is used. Comes with the error
--   details.
ValueError :: Text -> RowError
