| Portability | portable |
|---|---|
| Stability | experimental |
| Maintainer | Leon P Smith <leon@melding-monads.com> |
| Safe Haskell | Safe-Infered |
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.
- class FromField a where
- fromField :: FieldParser a
- type FieldParser a = Field -> Maybe ByteString -> Ok a
- data ResultError
- = Incompatible { }
- | UnexpectedNull { }
- | ConversionFailed { }
- 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
Documentation
A type that may be converted from a SQL type.
Methods
fromField :: FieldParser aSource
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. to be retained.
Result
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
type FieldParser a = Field -> Maybe ByteString -> Ok aSource
data ResultError Source
Exception thrown if conversion from a SQL value to a Haskell value fails.
Constructors
| Incompatible | The SQL and Haskell types are not compatible. |
Fields
| |
| UnexpectedNull | A SQL |
Fields
| |
| 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
| |
returnError :: forall a err. (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok aSource
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.
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 -> ByteStringSource
name :: Field -> Maybe ByteStringSource
tableColumn :: Field -> IntSource
newtype Oid