postgresql-simple-0.2.4.1: Mid-Level PostgreSQL client library

Portability | portable
Stability | experimental
Maintainer | Leon P Smith <leon@melding-monads.com>
Safe Haskell | None

Database.PostgreSQL.Simple.FromField

Description

The `FromField` typeclass, for converting a single value in a row returned by a SQL query into a more useful Haskell representation.

A Haskell numeric type is considered to be compatible with all PostgreSQL numeric types that are less accurate than it. For instance, the Haskell `Double` type is compatible with the PostgreSQL's 32-bit `Int` type because it can represent a `Int` exactly. On the other hand, since a `Double` might lose precision if representing a 64-bit `BigInt`, the two are not considered compatible.

Synopsis

- class FromField a where
  - fromField :: FieldParser a
- type FieldParser a = Field -> Maybe ByteString -> Ok a
- data ResultError
  - = Incompatible {
    - errSQLType :: String
    - errHaskellType :: String
    - errMessage :: String
    }
  - | UnexpectedNull {
    - errSQLType :: String
    - errHaskellType :: String
    - errMessage :: String
    }
  - | ConversionFailed {
    - errSQLType :: String
    - errHaskellType :: String
    - errMessage :: String
    }
- returnError :: forall a err. (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok a
- data Field
- typename :: Field -> ByteString
- name :: Field -> Maybe ByteString
- tableOid :: Field -> Oid
- tableColumn :: Field -> Int
- format :: Field -> Format
- typeOid :: Field -> Oid
- newtype Oid = Oid CUInt
- data Format
  - = Text
  - | Binary

# Documentation

class FromField a where

A type that may be converted from a SQL type.

Methods

fromField :: FieldParser a

Convert a SQL value to a Haskell value.

Returns a list of exceptions if the conversion fails. In the case of library instances, this will usually be a single `ResultError`, but may be a `UnicodeException`.

Implementations of `fromField` should not retain any references to the `Field` nor the `ByteString` arguments after the result has been evaluated to WHNF. Such a reference causes the entire `LibPQ.`Result`` to be retained.

For example, the instance for `ByteString` uses `copy` to avoid such a reference, and that using bytestring functions such as `drop` and `takeWhile` alone will also trigger this memory leak.

Instances

FromField Bool |
FromField Double |
FromField Float |
FromField Int |
FromField Int16 |
FromField Int32 |
FromField Int64 |
FromField Integer |
FromField ByteString |
FromField Text |
FromField Text |
FromField ByteString |
FromField Oid |
FromField LocalTime |
FromField ZonedTime |
FromField TimeOfDay |
FromField UTCTime |
FromField Day |
FromField Date |
FromField ZonedTimestamp |
FromField UTCTimestamp |
FromField LocalTimestamp |
FromField Null |
FromField [Char] |
FromField (Ratio Integer) |
FromField a => FromField (Maybe a) |
FromField (Binary ByteString) |
FromField (Binary ByteString) |
(FromField a, FromField b) => FromField (Either a b) |

type FieldParser a = Field -> Maybe ByteString -> Ok a

data ResultError

Exception thrown if conversion from a SQL value to a Haskell value fails.

Constructors

Incompatible | The SQL and Haskell types are not compatible.

Fields

errSQLType :: String
errHaskellType :: String
errMessage :: String

UnexpectedNull | A SQL `NULL` was encountered when the Haskell type did not permit it.

Fields

errSQLType :: String
errHaskellType :: String
errMessage :: String

ConversionFailed | The SQL value could not be parsed, or could not be represented as a valid Haskell value, or an unexpected low-level error occurred (e.g. mismatch between metadata and actual data in a row).

Fields

errSQLType :: String
errHaskellType :: String
errMessage :: String

Instances

Eq ResultError |
Show ResultError |
Typeable ResultError |
Exception ResultError |

returnError :: forall a err. (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok a

Given one of the constructors from `ResultError`, the field, and an `errMessage`, this fills in the other fields in the exception value and returns it in a 'Left . SomeException' constructor.

data Field

A Field represents metadata about a particular field

You don't particularly want to retain these structures for a long period of time, as they will retain the entire query result, not just the field metadata

typename :: Field -> ByteString

name :: Field -> Maybe ByteString

tableOid :: Field -> Oid

tableColumn :: Field -> Int

format :: Field -> Format

typeOid :: Field -> Oid

newtype Oid

Constructors

Oid CUInt |

Instances

Eq Oid |
Ord Oid |
Read Oid |
Show Oid |
Storable Oid |
ToField Oid |
FromField Oid |

data Format

Constructors

Text |
Binary |

Instances

Enum Format |
Eq Format |
Ord Format |
Show Format |