{-# LANGUAGE CPP, DeriveDataTypeable, DeriveFunctor #-}{-# LANGUAGE FlexibleInstances, TypeSynonymInstances #-}{-# LANGUAGE PatternGuards, ScopedTypeVariables #-}{-# LANGUAGE RecordWildCards, TemplateHaskell #-}{- |
Module: Database.PostgreSQL.Simple.FromField
Copyright: (c) 2011 MailRank, Inc.
(c) 2011-2013 Leon P Smith
License: BSD3
Maintainer: Leon P Smith <leon@melding-monads.com>
Stability: experimental
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.
-}moduleDatabase.PostgreSQL.Simple.FromField(FromField(..),FieldParser,Conversion(),runConversion,conversionMap,conversionError,ResultError(..),returnError,Field,typename,TypeInfo(..),Attribute(..),typeInfo,typeInfoByOid,name,tableOid,tableColumn,format,typeOid,PQ.Oid(..),PQ.Format(..),fromJSONField)where#include "MachDeps.h"importControl.Applicative(Applicative,(<|>),(<$>),pure)importControl.Concurrent.MVar(MVar,newMVar)importControl.Exception(Exception)importqualifiedData.AesonasJSONimportData.Attoparsec.Char8hiding(Result)importData.ByteString(ByteString)importqualifiedData.ByteString.Char8asBimportData.Int(Int16,Int32,Int64)importData.IORef(IORef,newIORef)importData.Ratio(Ratio)importData.Time(UTCTime,ZonedTime,LocalTime,Day,TimeOfDay)importData.Typeable(Typeable,typeOf)importData.Vector(Vector)importData.Vector.Mutable(IOVector)importqualifiedData.VectorasVimportDatabase.PostgreSQL.Simple.InternalimportDatabase.PostgreSQL.Simple.CompatimportDatabase.PostgreSQL.Simple.OkimportDatabase.PostgreSQL.Simple.TypesimportDatabase.PostgreSQL.Simple.TypeInfoasTIimportqualifiedDatabase.PostgreSQL.Simple.TypeInfo.StaticasTIimportDatabase.PostgreSQL.Simple.TypeInfo.MacroasTIimportDatabase.PostgreSQL.Simple.TimeimportDatabase.PostgreSQL.Simple.ArraysasArraysimportqualifiedDatabase.PostgreSQL.LibPQasPQimportqualifiedData.ByteStringasSBimportqualifiedData.ByteString.Char8asB8importqualifiedData.ByteString.LazyasLBimportqualifiedData.TextasSTimportqualifiedData.Text.EncodingasSTimportqualifiedData.Text.LazyasLTimportData.UUID(UUID)importqualifiedData.UUIDasUUID-- | Exception thrown if conversion from a SQL value to a Haskell-- value fails.dataResultError=Incompatible{errSQLType::String,errSQLTableOid::MaybePQ.Oid,errSQLField::String,errHaskellType::String,errMessage::String}-- ^ The SQL and Haskell types are not compatible.|UnexpectedNull{errSQLType::String,errSQLTableOid::MaybePQ.Oid,errSQLField::String,errHaskellType::String,errMessage::String}-- ^ A SQL @NULL@ was encountered when the Haskell-- type did not permit it.|ConversionFailed{errSQLType::String,errSQLTableOid::MaybePQ.Oid,errSQLField::String,errHaskellType::String,errMessage::String}-- ^ 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).deriving(Eq,Show,Typeable)instanceExceptionResultErrorleft::Exceptiona=>a->Conversionbleft=conversionErrortypeFieldParsera=Field->MaybeByteString->Conversiona-- | A type that may be converted from a SQL type.classFromFieldawherefromField::FieldParsera-- ^ 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.'PQ.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.'PQ.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.-- | 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.typename::Field->ConversionByteStringtypenamefield=typname<$>typeInfofieldtypeInfo::Field->ConversionTypeInfotypeInfoField{..}=Conversion$\conn->doOk<$>(getTypeInfoconn=<<PQ.ftyperesultcolumn)typeInfoByOid::PQ.Oid->ConversionTypeInfotypeInfoByOidoid=Conversion$\conn->doOk<$>(getTypeInfoconnoid)-- | Returns the name of the column. This is often determined by a table-- definition, but it can be set using an @as@ clause.name::Field->MaybeByteStringnameField{..}=unsafeDupablePerformIO(PQ.fnameresultcolumn)-- | 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@.tableOid::Field->MaybePQ.OidtableOidField{..}=toMaybeOid(unsafeDupablePerformIO(PQ.ftableresultcolumn))wheretoMaybeOidx=ifx==PQ.invalidOidthenNothingelseJustx-- | 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@.tableColumn::Field->InttableColumnField{..}=fromCol(unsafeDupablePerformIO(PQ.ftablecolresultcolumn))wherefromCol(PQ.Colx)=fromIntegralx-- | This returns whether the data was returned in a binary or textual format.-- Analogous to libpq's @PQfformat@.format::Field->PQ.FormatformatField{..}=unsafeDupablePerformIO(PQ.fformatresultcolumn)-- | voidinstanceFromField()wherefromFieldf_bs|typeOidf/=$(inlineTypoidTI.void)=returnErrorIncompatiblef""|otherwise=pure()-- | 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.instance(FromFielda)=>FromField(Maybea)wherefromField_Nothing=pureNothingfromFieldfbs=Just<$>fromFieldfbs-- | compatible with any data type, but the value must be nullinstanceFromFieldNullwherefromField_Nothing=pureNullfromFieldf(Just_)=returnErrorConversionFailedf"data is not null"-- | boolinstanceFromFieldBoolwherefromFieldfbs|typeOidf/=$(inlineTypoidTI.bool)=returnErrorIncompatiblef""|bs==Nothing=returnErrorUnexpectedNullf""|bs==Just"t"=pureTrue|bs==Just"f"=pureFalse|otherwise=returnErrorConversionFailedf""-- | \"char\"instanceFromFieldCharwherefromFieldfbs=iftypeOidf/=$(inlineTypoidTI.char)thenreturnErrorIncompatiblef""elsecasebsofNothing->returnErrorUnexpectedNullf""Justbs->ifB.lengthbs/=1thenreturnErrorConversionFailedf"length not 1"elsereturn$!(B.headbs)-- | int2instanceFromFieldInt16wherefromField=attook16$signeddecimal-- | int2, int4instanceFromFieldInt32wherefromField=attook32$signeddecimal#if WORD_SIZE_IN_BITS < 64-- | int2, int4, and if compiled as 64-bit code, int8 as well.-- This library was compiled as 32-bit code.#else-- | int2, int4, and if compiled as 64-bit code, int8 as well.-- This library was compiled as 64-bit code.#endifinstanceFromFieldIntwherefromField=attookInt$signeddecimal-- | int2, int4, int8instanceFromFieldInt64wherefromField=attook64$signeddecimal-- | int2, int4, int8instanceFromFieldIntegerwherefromField=attook64$signeddecimal-- | int2, float4instanceFromFieldFloatwherefromField=attook(realToFrac<$>double)whereok=$(mkCompats[TI.float4,TI.int2])-- | int2, int4, float4, float8instanceFromFieldDoublewherefromField=attookdoublewhereok=$(mkCompats[TI.float4,TI.float8,TI.int2,TI.int4])-- | int2, int4, float4, float8, numericinstanceFromField(RatioInteger)wherefromField=attookrationalwhereok=$(mkCompats[TI.float4,TI.float8,TI.int2,TI.int4,TI.numeric])unBinary::Binaryt->tunBinary(Binaryx)=x-- | bytea, name, text, \"char\", bpchar, varchar, unknowninstanceFromFieldSB.ByteStringwherefromFieldfdat=iftypeOidf==$(inlineTypoidTI.bytea)thenunBinary<$>fromFieldfdatelsedoFromFieldfokText'puredat-- | oidinstanceFromFieldPQ.OidwherefromFieldfdat=PQ.Oid<$>atto(==$(inlineTypoidTI.oid))decimalfdat-- | bytea, name, text, \"char\", bpchar, varchar, unknowninstanceFromFieldLB.ByteStringwherefromFieldfdat=LB.fromChunks.(:[])<$>fromFieldfdatunescapeBytea::Field->SB.ByteString->Conversion(BinarySB.ByteString)unescapeByteafstr=caseunsafeDupablePerformIO(PQ.unescapeByteastr)ofNothing->returnErrorConversionFailedf"unescapeBytea failed"Juststr->pure(Binarystr)-- | byteainstanceFromField(BinarySB.ByteString)wherefromFieldfdat=caseformatfofPQ.Text->doFromFieldfokBinary(unescapeByteaf)datPQ.Binary->doFromFieldfokBinary(pure.Binary)dat-- | byteainstanceFromField(BinaryLB.ByteString)wherefromFieldfdat=Binary.LB.fromChunks.(:[]).unBinary<$>fromFieldfdat-- | name, text, \"char\", bpchar, varcharinstanceFromFieldST.TextwherefromFieldf=doFromFieldfokText$(eitherleftpure.ST.decodeUtf8')-- FIXME: check character encoding-- | name, text, \"char\", bpchar, varcharinstanceFromFieldLT.TextwherefromFieldfdat=LT.fromStrict<$>fromFieldfdat-- | name, text, \"char\", bpchar, varcharinstanceFromField[Char]wherefromFieldfdat=ST.unpack<$>fromFieldfdat-- | timestamptzinstanceFromFieldUTCTimewherefromField=ff$(inlineTypoidTI.timestamptz)"UTCTime"parseUTCTime-- | timestamptzinstanceFromFieldZonedTimewherefromField=ff$(inlineTypoidTI.timestamptz)"ZonedTime"parseZonedTime-- | timestampinstanceFromFieldLocalTimewherefromField=ff$(inlineTypoidTI.timestamp)"LocalTime"parseLocalTime-- | dateinstanceFromFieldDaywherefromField=ff$(inlineTypoidTI.date)"Day"parseDay-- | timeinstanceFromFieldTimeOfDaywherefromField=ff$(inlineTypoidTI.time)"TimeOfDay"parseTimeOfDay-- | timestamptzinstanceFromFieldUTCTimestampwherefromField=ff$(inlineTypoidTI.timestamptz)"UTCTimestamp"parseUTCTimestamp-- | timestamptzinstanceFromFieldZonedTimestampwherefromField=ff$(inlineTypoidTI.timestamptz)"ZonedTimestamp"parseZonedTimestamp-- | timestampinstanceFromFieldLocalTimestampwherefromField=ff$(inlineTypoidTI.timestamp)"LocalTimestamp"parseLocalTimestamp-- | dateinstanceFromFieldDatewherefromField=ff$(inlineTypoidTI.date)"Date"parseDateff::PQ.Oid->String->(B8.ByteString->EitherStringa)->Field->MaybeB8.ByteString->ConversionaffcompatOidhsTypeparsefmstr=iftypeOidf/=compatOidthenerrIncompatible""elsecasemstrofNothing->errUnexpectedNull""Juststr->caseparsestrofLeftmsg->errConversionFailedmsgRightval->returnvalwhereerrerrCmsg=dotypnam<-typenamefleft$errC(B8.unpacktypnam)(tableOidf)(maybe""B8.unpack(namef))hsTypemsg{-# INLINE ff #-}-- | Compatible with both types. Conversions to type @b@ are-- preferred, the conversion to type @a@ will be tried after-- the 'Right' conversion fails.instance(FromFielda,FromFieldb)=>FromField(Eitherab)wherefromFieldfdat=(Right<$>fromFieldfdat)<|>(Left<$>fromFieldfdat)-- | any postgresql array whose elements are compatible with type @a@instance(FromFielda,Typeablea)=>FromField(PGArraya)wherefromFieldfmdat=doinfo<-typeInfofcaseinfoofTI.Array{}->casemdatofNothing->returnErrorUnexpectedNullf""Justdat->docaseparseOnly(fromArrayinfof)datofLefterr->returnErrorConversionFailedferrRightconv->PGArray<$>conv_->returnErrorIncompatiblef""fromArray::(FromFielda)=>TypeInfo->Field->Parser(Conversion[a])fromArraytypeInfof=sequence.(parseIt<$>)<$>arraydelimwheredelim=typdelim(typelemtypeInfo)fElem=f{typeOid=typoid(typelemtypeInfo)}parseItitem=(fromFieldf'.Just.fmtdelim)itemwheref'|Arrays.Array_<-item=f|otherwise=fEleminstance(FromFielda,Typeablea)=>FromField(Vectora)wherefromFieldfv=V.fromList.fromPGArray<$>fromFieldfvinstance(FromFielda,Typeablea)=>FromField(IOVectora)wherefromFieldfv=liftConversion.V.unsafeThaw=<<fromFieldfv-- | uuidinstanceFromFieldUUIDwherefromFieldfmbs=iftypeOidf/=$(inlineTypoidTI.uuid)thenreturnErrorIncompatiblef""elsecasembsofNothing->returnErrorUnexpectedNullf""Justbs->caseUUID.fromASCIIBytesbsofNothing->returnErrorConversionFailedf"Invalid UUID"Justuuid->pureuuid-- | jsoninstanceFromFieldJSON.ValuewherefromFieldfmbs=iftypeOidf/=$(inlineTypoidTI.json)thenreturnErrorIncompatiblef""elsecasembsofNothing->returnErrorUnexpectedNullf""Justbs->#if MIN_VERSION_aeson(0,6,3)caseJSON.eitherDecodeStrict'bsof#elsif MIN_VERSION_bytestring(0,10,0)caseJSON.eitherDecode'$LB.fromStrictbsof#elsecaseJSON.eitherDecode'$LB.fromChunks[bs]of#endifLefterr->returnErrorConversionFailedferrRightval->pureval-- | Parse a field to a JSON 'JSON.Value' and convert that into a-- Haskell value using 'JSON.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.fromJSONField::(JSON.FromJSONa,Typeablea)=>FieldParserafromJSONFieldfmbBs=dovalue<-fromFieldfmbBscaseJSON.fromJSONvalueofJSON.Errorerr->returnErrorConversionFailedf$"JSON decoding error: "++errJSON.Successx->purex-- | 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.instanceFromFielda=>FromField(IORefa)wherefromFieldfv=liftConversion.newIORef=<<fromFieldfv-- | 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.instanceFromFielda=>FromField(MVara)wherefromFieldfv=liftConversion.newMVar=<<fromFieldfvtypeCompat=PQ.Oid->BoolokText,okText',okBinary,ok16,ok32,ok64,okInt::CompatokText=$(mkCompats[TI.name,TI.text,TI.char,TI.bpchar,TI.varchar])okText'=$(mkCompats[TI.name,TI.text,TI.char,TI.bpchar,TI.varchar,TI.unknown])okBinary=(==$(inlineTypoidTI.bytea))ok16=(==$(inlineTypoidTI.int2))ok32=$(mkCompats[TI.int2,TI.int4])ok64=$(mkCompats[TI.int2,TI.int4,TI.int8])#if WORD_SIZE_IN_BITS < 64okInt=ok32#elseokInt=ok64#endifdoFromField::foralla.(Typeablea)=>Field->Compat->(ByteString->Conversiona)->MaybeByteString->ConversionadoFromFieldfisCompatcvt(Justbs)|isCompat(typeOidf)=cvtbs|otherwise=returnErrorIncompatiblef"types incompatible"doFromFieldf___=returnErrorUnexpectedNullf""-- | 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.returnError::forallaerr.(Typeablea,Exceptionerr)=>(String->MaybePQ.Oid->String->String->String->err)->Field->String->ConversionareturnErrormkErrfmsg=dotypnam<-typenamefleft$mkErr(B.unpacktypnam)(tableOidf)(maybe""B.unpack(namef))(show(typeOf(undefined::a)))msgatto::foralla.(Typeablea)=>Compat->Parsera->Field->MaybeByteString->Conversionaattotypesp0fdat=doFromFieldftypes(gop0)datwherego::Parsera->ByteString->Conversionagops=caseparseOnlypsofLefterr->returnErrorConversionFailedferrRightv->purev