HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulepostgresql-simple-0.7.0.0Haskell2010

Database.PostgreSQL.Simple.FromField

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 <$> field, although this idiom is additionally compatible with PostgreSQL's int8 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.

  • 8 types
  • 1 class
  • 17 values
classclass 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.

    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.

Instances48FromField, …
  • FromField ValueDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    json, jsonb

  • FromField ByteStringDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    bytea, name, text, "char", bpchar, varchar, unknown

  • FromField ByteStringDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    bytea, name, text, "char", bpchar, varchar, unknown

  • FromField IntegerDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4, int8

  • FromField Int16Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2

  • FromField Int32Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4

  • FromField Int64Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4, int8

  • FromField BoolDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    bool

  • FromField CharDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    "char", bpchar

  • FromField DoubleDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4, float4, float8 (Uses attoparsec's double routine, for better accuracy convert to Scientific or Rational first)

  • FromField FloatDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, float4 (Uses attoparsec's double routine, for better accuracy convert to Scientific or Rational first)

  • FromField IntDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4, and if compiled as 64-bit code, int8 as well. This library was compiled as 64-bit code.

  • FromField OidDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    oid

  • FromField HStoreListDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.HStore.Implementation

    hstore

  • FromField HStoreMapDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.HStore.Implementation
  • FromField DateDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    date

  • FromField LocalTimestampDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    timestamp

  • FromField UTCTimestampDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    timestamptz

  • FromField ZonedTimestampDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    timestamptz

  • FromField NullDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    compatible with any data type, but the value must be null

  • FromField ScientificDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4, int8, float4, float8, numeric

  • FromField TextDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    name, text, "char", bpchar, varchar

  • FromField TextDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    name, text, "char", bpchar, varchar

  • FromField DayDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    date

  • FromField UTCTimeDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    timestamptz

  • FromField CalendarDiffTimeDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    interval. Requires you to configure intervalstyle as iso_8601.

    You can configure intervalstyle on every connection with a SET command, but for better performance you may want to configure it permanently in the file found with SHOW config_file; .

  • FromField LocalTimeDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    timestamp

  • FromField TimeOfDayDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    time

  • FromField ZonedTimeDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    timestamptz

  • FromField UUIDDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    uuid

  • FromField ()Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    void

  • FromField (CI Text)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    citext

  • FromField (CI Text)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    citext

  • FromField (Ratio Integer)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    int2, int4, int8, float4, float8, numeric

  • FromField (Binary ByteString)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    bytea

  • FromField (Binary ByteString)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    bytea

  • FromField [Char]Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    name, text, "char", bpchar, varchar

  • FromField a => FromField (Identity a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
  • FromField a => FromField (IORef a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    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)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    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 => FromField (Maybe a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    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.

  • (FromJSON a, Typeable a) => FromField (Aeson a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Newtypes
  • (FromField a, Typeable a) => FromField (PGRange a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Range
  • (FromField a, Typeable a) => FromField (PGArray a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    any postgresql array whose elements are compatible with type a

  • (FromField a, Typeable a) => FromField (Vector a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
  • (FromField a, Typeable a) => FromField (IOVector a)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
  • (FromField a, FromField b) => FromField (Either a b)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    Compatible with both types. Conversions to type b are preferred, the conversion to type a will be tried after the Right conversion fails.

  • FromField a => FromField (Const a b)Defined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
newtypenewtype Conversion a
#
Instances5Monad, Functor, Applicative, Alternative, MonadPlus
  • Monad ConversionDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Internal
  • Functor ConversionDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Internal
  • Applicative ConversionDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Internal
  • Alternative ConversionDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Internal
  • MonadPlus ConversionDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.Internal
datadata ResultError
#

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

Constructors

Instances3Eq, Show, Exception
  • Eq ResultErrorDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
  • Show ResultErrorDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
  • Exception ResultErrorDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField
datadata 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

valuetypename :: Field -> Conversion ByteString
#

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.

datadata TypeInfo
#

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

Constructors

Instances1Show
  • Show TypeInfoDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.TypeInfo.Types
valuename :: Field -> Maybe ByteString
#

Returns the name of the column. This is often determined by a table definition, but it can be set using an as clause.

valuetableOid :: Field -> Maybe Oid
#

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.

valuetableColumn :: Field -> Int
#

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.

valueformat :: Field -> Format
#

This returns whether the data was returned in a binary or textual format. Analogous to libpq's PQfformat.

valuetypeOid :: Field -> Oid
#

This returns the type oid associated with the column. Analogous to libpq's PQftype.

newtypenewtype Oid
#

Constructors

Instances7Eq, Ord, Read, Show, Storable, FromField, …
  • Eq OidDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Oid
  • Ord OidDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Oid
  • Read OidDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Oid
  • Show OidDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Oid
  • Storable OidDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Oid
  • FromField OidDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.FromField

    oid

  • ToField OidDefined in postgresql-simple-0.7.0.0 · Database.PostgreSQL.Simple.ToField
datadata Format
#
TextBinary
Instances6Enum, Eq, Ord, Show, FromCInt, ToCInt
  • Enum FormatDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Enums
  • Eq FormatDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Enums
  • Ord FormatDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Enums
  • Show FormatDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Enums
  • FromCInt FormatDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Enums
  • ToCInt FormatDefined in postgresql-libpq-0.11.0.0 · Database.PostgreSQL.LibPQ.Enums
valueattoFieldParser
  1. :: Typeable a
  2. => (Oid -> Bool)

    Predicate for whether the postgresql type oid is compatible with this parser

  3. -> Parser a

    An attoparsec parser.

  4. -> 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)
valuefromJSONField :: (FromJSON a, Typeable a) => FieldParser a
#

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 (Maybe Foo) will return Nothing on the json null value, and return an exception on SQL null value. Alternatively, one could write optionalField fromJSONField that will return Nothing on SQL null, and otherwise will call fromJSONField :: FieldParser Foo and then return Just the result value, or return its exception. If one would like to return Nothing 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