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. 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.

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

Documentation

class FromField a whereSource

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.

Note that retaining any reference to the Field argument causes the entire LibPQ.Result to be retained. Thus, implementations of fromField 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.Result before it has been passed to fromField. This is because for short strings, it's cheaper to copy the string than to set up a finalizer.

Instances

FromField Bool	bool
FromField Char	"char"
FromField Double	int2, int4, float4, float8
FromField Float	int2, float4
FromField Int	int2, int4, and if compiled as 64-bit code, int8 as well. This library was compiled as 64-bit code.
FromField Int16	int2
FromField Int32	int2, int4
FromField Int64	int2, int4, int8
FromField Integer	int2, int4, int8
FromField ()	void
FromField ByteString	bytea, name, text, "char", bpchar, varchar, unknown
FromField ByteString	bytea, name, text, "char", bpchar, varchar, unknown
FromField Text	name, text, "char", bpchar, varchar
FromField UTCTime	timestamptz
FromField Value	json
FromField Text	name, text, "char", bpchar, varchar
FromField Oid	oid
FromField LocalTime	timestamp
FromField ZonedTime	timestamptz
FromField TimeOfDay	time
FromField Day	date
FromField UUID	uuid
FromField Date	date
FromField ZonedTimestamp	timestamptz
FromField UTCTimestamp	timestamptz
FromField LocalTimestamp	timestamp
FromField Null	compatible with any data type, but the value must be null
FromField HStoreMap
FromField HStoreList	hstore
FromField [Char]	name, text, "char", bpchar, varchar
FromField (Ratio Integer)	int2, int4, float4, float8, numeric
FromField a => FromField (Maybe a)	For dealing with null values. Compatible with any postgresql type compatible with type `a`. Note that the type is not checked if the value is null, although it is inadvisable to rely on this behavior.
FromField a => FromField (IORef a)	Compatible with the same set of types as `a`. Note that modifying the `IORef` does not have any effects outside the local process on the local machine.
FromField a => FromField (MVar a)	Compatible with the same set of types as `a`. Note that modifying the `MVar` does not have any effects outside the local process on the local machine.
(FromField a, Typeable a) => FromField (Vector a)
(FromField a, Typeable a) => FromField (IOVector a)
(FromField a, Typeable a) => FromField (PGArray a)	any postgresql array whose elements are compatible with type `a`
FromField (Binary ByteString)	bytea
FromField (Binary ByteString)	bytea
(FromField a, FromField b) => FromField (Either a b)	Compatible with both types. Conversions to type `b` are preferred, the conversion to type `a` will be tried after the `Right` conversion fails.

type FieldParser a = Field -> Maybe ByteString -> Conversion aSource

data Conversion a Source

Instances

Monad Conversion
Functor Conversion
MonadPlus Conversion
Applicative Conversion
Alternative Conversion

runConversion :: Conversion a -> Connection -> IO (Ok a)Source

conversionMap :: (Ok a -> Ok b) -> Conversion a -> Conversion bSource

conversionError :: Exception err => err -> Conversion 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 errSQLType :: String errSQLTableOid :: Maybe Oid errSQLField :: String errHaskellType :: String errMessage :: String
UnexpectedNull	A SQL `NULL` was encountered when the Haskell type did not permit it.
Fields errSQLType :: String errSQLTableOid :: Maybe Oid errSQLField :: 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 errSQLTableOid :: Maybe Oid errSQLField :: String errHaskellType :: String errMessage :: String

Instances

Eq ResultError
Show ResultError
Typeable ResultError
Exception ResultError

returnError :: forall a err. (Typeable a, Exception err) => (String -> Maybe Oid -> String -> String -> String -> err) -> Field -> String -> Conversion 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.

data Field Source

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.

data TypeInfo Source

A structure representing some of the metadata regarding a PostgreSQL type, mostly taken from the pg_type table.

Constructors

Basic
Fields typoid :: !Oid typcategory :: !Char typdelim :: !Char typname :: !ByteString
Array
Fields typoid :: !Oid typcategory :: !Char typdelim :: !Char typname :: !ByteString typelem :: !TypeInfo
Range
Fields typoid :: !Oid typcategory :: !Char typdelim :: !Char typname :: !ByteString rngsubtype :: !TypeInfo
Composite
Fields typoid :: !Oid typcategory :: !Char typdelim :: !Char typname :: !ByteString typrelid :: !Oid attributes :: !(Vector Attribute)

Instances

Show TypeInfo

data Attribute Source

Constructors

Attribute
Fields attname :: !ByteString atttype :: !TypeInfo

Instances

Show Attribute

typeInfo :: Field -> Conversion TypeInfo Source

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 off the associated table column. Numbering starts from 0. 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.

newtype Oid

Constructors

Oid CUInt

Instances

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

data Format

Constructors

Text
Binary

Instances

Enum Format
Eq Format
Ord Format
Show Format

fromJSONField :: (FromJSON a, Typeable a) => FieldParser aSource

Parse a field to a JSON Value and convert that into a Haskell value using fromJSON.

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.