| Copyright | (c) 2011 MailRank Inc. (c) 2011-2013 Leon P Smith |
|---|---|
| License | BSD3 |
| Maintainer | Leon P Smith <leon@melding-monads.com> |
| Stability | experimental |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
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.
Note that each instance of FromField is documented by a list of
compatible postgresql types.
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 PostgreSQL's 64-bit
bigint, the two are not considered compatible.
Note that the Float and Double instances use attoparsec's double
conversion routine, which sacrifices some accuracy for speed. If you
need accuracy, consider first converting data to a Scientific or Rational
type, and then converting to a floating-point type. If you are defining
your own FromRow instances, this can be
achieved simply by
fromRational <$> fieldint8 and numeric
types. If this is unacceptable, you may find
fieldWith useful.
Also note that while converting to a Double through the Scientific type
is likely somewhat faster than converting through the Rational type,
the Scientific type has no way to represent NaN and ±Infinity values.
Thus, if you need precision conversion of regular floating point values
and the possibility of receiving these special values from the backend,
stick with Rational.
Because FromField is a typeclass, one may provide conversions to
additional Haskell types without modifying postgresql-simple. This is
particularly useful for supporting PostgreSQL types that postgresql-simple
does not support out-of-box. Here's an example of what such an instance
might look like for a UUID type that implements the Read class:
import Data.UUID ( UUID )
import Database.PostgreSQL.Simple.FromField
( FromField (fromField) , typeOid, returnError, ResultError (..) )
import Database.PostgreSQL.Simple.TypeInfo.Static (typoid, uuid)
import qualified Data.ByteString.Char8 as B
instance FromField UUID where
fromField f mdata =
if typeOid f /= typoid uuid
then returnError Incompatible f ""
else case B.unpack `fmap` mdata of
Nothing -> returnError UnexpectedNull f ""
Just dat ->
case [ x | (x,t) <- reads dat, ("","") <- lex t ] of
[x] -> return x
_ -> returnError ConversionFailed f dat
Note that because PostgreSQL's uuid type is built into postgres and is
not provided by an extension, the typeOid of uuid does not change and
thus we can examine it directly. One could hard-code the type oid, or
obtain it by other means, but in this case we simply pull it out of the
static table provided by postgresql-simple.
On the other hand if the type is provided by an extension, such as
PostGIS or hstore, then the typeOid is not stable and can vary from
database to database. In this case it is recommended that FromField
instances use typename instead.
Synopsis
- class FromField a where
- fromField :: FieldParser a
- type FieldParser a = Field -> Maybe ByteString -> Conversion a
- data Conversion a
- runConversion :: Conversion a -> Connection -> IO (Ok a)
- conversionMap :: (Ok a -> Ok b) -> Conversion a -> Conversion b
- conversionError :: Exception err => err -> Conversion a
- data ResultError
- = Incompatible { }
- | UnexpectedNull { }
- | ConversionFailed { }
- returnError :: forall a err. (Typeable a, Exception err) => (String -> Maybe Oid -> String -> String -> String -> err) -> Field -> String -> Conversion a
- data Field
- typename :: Field -> Conversion ByteString
- data TypeInfo
- = Basic {
- typoid :: !Oid
- typcategory :: !Char
- typdelim :: !Char
- typname :: !ByteString
- | Array {
- typoid :: !Oid
- typcategory :: !Char
- typdelim :: !Char
- typname :: !ByteString
- typelem :: !TypeInfo
- | Range {
- typoid :: !Oid
- typcategory :: !Char
- typdelim :: !Char
- typname :: !ByteString
- rngsubtype :: !TypeInfo
- | Composite {
- typoid :: !Oid
- typcategory :: !Char
- typdelim :: !Char
- typname :: !ByteString
- typrelid :: !Oid
- attributes :: !(Vector Attribute)
- = Basic {
- data Attribute = Attribute {
- attname :: !ByteString
- atttype :: !TypeInfo
- typeInfo :: Field -> Conversion TypeInfo
- typeInfoByOid :: Oid -> Conversion TypeInfo
- name :: Field -> Maybe ByteString
- tableOid :: Field -> Maybe Oid
- tableColumn :: Field -> Int
- format :: Field -> Format
- typeOid :: Field -> Oid
- newtype Oid = Oid CUInt
- data Format
- pgArrayFieldParser :: Typeable a => FieldParser a -> FieldParser (PGArray a)
- attoFieldParser :: forall a. Typeable a => (Oid -> Bool) -> Parser a -> FieldParser a
- optionalField :: FieldParser a -> FieldParser (Maybe a)
- fromJSONField :: (FromJSON a, Typeable a) => FieldParser a
- fromFieldJSONByteString :: Field -> Maybe ByteString -> Conversion ByteString
Documentation
class FromField a where Source #
A type that may be converted from a SQL type.
Methods
fromField :: FieldParser a Source #
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.
Note that retaining any reference to the Field argument causes
the entire LibPQ. to be retained. Thus, implementations
of ResultfromField should return results that do not refer to this value
after the result have been evaluated to WHNF.
Note that as of postgresql-simple-0.4.0.0, the ByteString value
has already been copied out of the LibPQ. before it has
been passed to ResultfromField. This is because for short strings, it's
cheaper to copy the string than to set up a finalizer.
Instances
type FieldParser a = Field -> Maybe ByteString -> Conversion a Source #
data Conversion a Source #
Instances
runConversion :: Conversion a -> Connection -> IO (Ok a) Source #
conversionMap :: (Ok a -> Ok b) -> Conversion a -> Conversion b Source #
conversionError :: Exception err => err -> Conversion a Source #
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
| |
Instances
| Exception ResultError Source # | |
Defined in Database.PostgreSQL.Simple.FromField Methods toException :: ResultError -> SomeException # fromException :: SomeException -> Maybe ResultError # displayException :: ResultError -> String # | |
| Show ResultError Source # | |
Defined in Database.PostgreSQL.Simple.FromField Methods showsPrec :: Int -> ResultError -> ShowS # show :: ResultError -> String # showList :: [ResultError] -> ShowS # | |
| Eq ResultError Source # | |
Defined in Database.PostgreSQL.Simple.FromField | |
returnError :: forall a err. (Typeable a, Exception err) => (String -> Maybe Oid -> String -> String -> String -> err) -> Field -> String -> Conversion a Source #
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 -> Conversion ByteString Source #
Returns the data type name. This is the preferred way of identifying types that do not have a stable type oid, such as types provided by extensions to PostgreSQL.
More concretely, it returns the typname column associated with the
type oid in the pg_type table. First, postgresql-simple will check
the built-in, static table. If the type oid is not there,
postgresql-simple will check a per-connection cache, and then
finally query the database's meta-schema.
A structure representing some of the metadata regarding a PostgreSQL
type, mostly taken from the pg_type table.
Constructors
| Basic | |
Fields
| |
| Array | |
Fields
| |
| Range | |
Fields
| |
| Composite | |
Fields
| |
Constructors
| Attribute | |
Fields
| |
typeInfoByOid :: Oid -> Conversion TypeInfo Source #
name :: Field -> Maybe ByteString Source #
Returns the name of the column. This is often determined by a table
definition, but it can be set using an as clause.
tableOid :: Field -> Maybe Oid Source #
Returns the name of the object id of the table associated with the
column, if any. Returns Nothing when there is no such table;
for example a computed column does not have a table associated with it.
Analogous to libpq's PQftable.
tableColumn :: Field -> Int Source #
If the column has a table associated with it, this returns the
number of the associated table column. Table columns have
nonzero numbers. Zero is returned if the specified column is not
a simple reference to a table column, or when using pre-3.0
protocol. Analogous to libpq's PQftablecol.
format :: Field -> Format Source #
This returns whether the data was returned in a binary or textual format.
Analogous to libpq's PQfformat.
typeOid :: Field -> Oid Source #
This returns the type oid associated with the column. Analogous
to libpq's PQftype.
pgArrayFieldParser :: Typeable a => FieldParser a -> FieldParser (PGArray a) Source #
Arguments
| :: forall a. Typeable a | |
| => (Oid -> Bool) | Predicate for whether the postgresql type oid is compatible with this parser |
| -> Parser a | An attoparsec parser. |
| -> FieldParser a |
Construct a field parser from an attoparsec parser. An Incompatible error is thrown if the
PostgreSQL oid does not match the specified predicate.
instance FromField Int16 where fromField = attoFieldParser ok16 (signed decimal)
Since: 0.6.3
optionalField :: FieldParser a -> FieldParser (Maybe a) Source #
fromJSONField :: (FromJSON a, Typeable a) => FieldParser a Source #
Parse a field to a JSON Value and convert that into a
Haskell value using the FromJSON instance.
This can be used as the default implementation for the fromField
method for Haskell types that have a JSON representation in
PostgreSQL.
The Typeable constraint is required to show more informative
error messages when parsing fails.
Note that fromJSONField :: FieldParser ( will return
Maybe Foo)Nothingnull value, and return an exception on SQL null
value. Alternatively, one could write optionalField fromJSONFieldNothing on SQL null, and otherwise will call
fromJSONField :: FieldParser Foo and then return JustNothing on both the SQL null and json null values,
one way to do it would be to write
\f mv -> join <$> optionalField fromJSONField f mv
fromFieldJSONByteString :: Field -> Maybe ByteString -> Conversion ByteString Source #
Return the JSON ByteString directly
Since: 0.6.3