Safe Haskell	None
Language	Haskell2010

Hasql.Postgres

Description

This module contains everything required to use "hasql" with Postgres. For information on how it should be used consult the "hasql" docs.

Please note that there is a few limitations inflicted by Postgres, encoding which in the type system would seriously burden the API, so it was decided to make it the user's responsibility to make sure that certain conditions are satisfied during the runtime. Particularly this concerns the CxValue instances of Maybe, [] and Vector. For details consult the docs on those instances.

Synopsis

Documentation

data Postgres Source

A connection to PostgreSQL.

Instances

Cx Postgres
CxTx Postgres
CxValue Postgres Bool	Maps to `bool`.
CxValue Postgres Char	Maps to `char`. Note that it supports UTF-8 values.
CxValue Postgres Double	Maps to `float8`.
CxValue Postgres Float	Maps to `float4`.
CxValue Postgres Int	Maps to `int8`.
CxValue Postgres Int8	Maps to `int2`.
CxValue Postgres Int16	Maps to `int2`.
CxValue Postgres Int32	Maps to `int4`.
CxValue Postgres Int64	Maps to `int8`.
CxValue Postgres Word	Maps to `int8`.
CxValue Postgres Word8	Maps to `int2`.
CxValue Postgres Word16	Maps to `int2`.
CxValue Postgres Word32	Maps to `int4`.
CxValue Postgres Word64	Maps to `int8`.
CxValue Postgres ByteString	Maps to `bytea`.
CxValue Postgres Scientific	Maps to `numeric`.
CxValue Postgres Text	Maps to `text`.
CxValue Postgres UTCTime	Maps to `timestamptz`. 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.
CxValue Postgres Value	Maps to `json`. Only works for PostgreSQL versions >= 9.2.
CxValue Postgres UUID	Maps to `uuid`.
CxValue Postgres DiffTime	Maps to `interval`.
CxValue Postgres Day	Maps to `date`.
CxValue Postgres TimeOfDay	Maps to `time`.
CxValue Postgres LocalTime	Maps to `timestamp`.
CxValue Postgres Unknown	Maps to `unknown`.
(Mapping a, ArrayMapping a) => CxValue Postgres [a]	Maps to Postgres arrays. LIMITATION 1 In multidimensional lists all rows of a dimension must have the same length. E.g., the following is a corrupt value: [[1,2], [3]] The following is a valid one: [[1,2], [3,4], [5,6]] LIMITATION 2 `Maybe` cannot be used to wrap an intermediate level in a multidimensional list. E.g., the following is a corrupt type: [Maybe [a]] However, both the first level list and the value are allowed to be wrapped in `Maybe`. So the following is a valid type: Maybe [[[Maybe a]]] NOTICE Also, please note that since `String` is just an alias to `[Char]`, it will be mapped to an array of characters. So if you want to map to a textual type use `Text` instead.
Mapping a => CxValue Postgres (Maybe a)	Maps to the same type as the underlying value, encoding `Nothing` as NULL. LIMITATION Multilevel `Maybe`s are not supported. E.g., a value `Just Nothing` of type `(Maybe (Maybe a))` will be encoded the same way as `Nothing`.
(Mapping a, ArrayMapping a) => CxValue Postgres (Vector a)	Maps to Postgres' arrays. Same rules as for the list instance apply. Consult its docs for details.
CxValue Postgres (TimeOfDay, TimeZone)	Maps to `timetz`. Unlike with `timestamptz`, Postgres does store the timezone information for `timetz`. However the "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.
type CxError Postgres = CxError
type CxSettings Postgres = Settings
data ResultValue Postgres = ResultValue !Environment !(Maybe ByteString)
data StmtParam Postgres = StmtParam !Oid !(Environment -> Maybe ByteString)
type TxError Postgres = TxError

data Settings Source

Connection settings.

Constructors

ParamSettings ByteString Word16 ByteString ByteString ByteString	A host, a port, a user, a password and a database.
StringSettings ByteString	All settings encoded in a single byte string according to the PostgreSQL format.

Instances

Show Settings

data CxError Source

Constructors

CantConnect (Maybe ByteString)	Impossible to connect. A clarification might be given in the attached byte string.
UnsupportedVersion Int	Server is running an unsupported version of Postgres. The parameter is the version in such a format, where a value `80105` identifies a version `8.1.5`.

Instances

Eq CxError
Show CxError

data TxError Source

Constructors

NoResult !(Maybe ByteString)	Received no response from the database.
ErroneousResult !ByteString !ByteString !(Maybe ByteString) !(Maybe ByteString)	An error reported by the DB. Code, message, details, hint. The SQLSTATE code for the error. The SQLSTATE code identifies the type of error that has occurred; it can be used by front-end applications to perform specific operations (such as error handling) in response to a particular database error. For a list of the possible SQLSTATE codes, see Appendix A. This field is not localizable, and is always present. The primary human-readable error message (typically one line). Always present. Detail: an optional secondary error message carrying more detail about the problem. Might run to multiple lines. Hint: an optional suggestion 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.
NotInTransaction	An attempt to perform an action, which requires a transaction context, without one. Currently it's only raised when trying to stream without establishing a transaction.

Instances

Eq TxError
Show TxError

newtype Unknown Source

A wrapper around a ByteString, which identifies the value with the PostgreSQL's "unknown" type, thus leaving the choice of the type to Postgres. The bytestring needs to be encoded according to the Postgres binary format of the type it expects.

Essentially this is a low-level hook into the phases of encoding and decoding of values with custom codecs. The "postgresql-binary" library is your toolchain when dealing with this type.

Constructors

Unknown ByteString

Instances

CxValue Postgres Unknown

Maps to unknown.