hasql- A very efficient PostgreSQL driver and a flexible mapping API

Safe HaskellNone





data Query a b Source

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 (Int64, Int64) Int64
selectSum =
  Hasql.Query sql encoder decoder True
    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.


Query !ByteString !(Params a) !(Result b) !Bool 


data ResultsError Source

An error of the result-decoder.


ClientError !(Maybe ByteString)

An error on the client-side, with a message generated by the "libpq" library. Usually indicates problems with connection.

ResultError !ResultError

Decoder error details.

data ResultError Source

Decoder error details.


ServerError !ByteString !ByteString !(Maybe ByteString) !(Maybe ByteString)

An error reported by the DB. Consists of the following: Code, message, details, hint.

  • Code. The SQLSTATE code for the error. It's recommended to use the "postgresql-error-codes" package to work with those.
  • Message. The primary human-readable error message (typically one line). Always present.
  • Details. An optional secondary error message carrying more detail about the problem. Might run to multiple lines.
  • Hint. An optional suggestion on what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. Might run to multiple lines.
UnexpectedResult !Text

The database returned an unexpected result. Indicates an improper statement or a schema mismatch.

RowError !Int !RowError

An error of the row reader, preceded by the index of the row.

UnexpectedAmountOfRows !Int

An unexpected amount of rows.

data RowError Source

An error during the decoding of a specific row.



Appears on the attempt to parse more columns than there are in the result.


Appears on the attempt to parse a NULL as some value.

ValueError !Text

Appears when a wrong value parser is used. Comes with the error details.

run :: Query a b -> a -> Connection -> IO (Either ResultsError b) Source

Execute the query, producing either a deserialization failure or a successful result.