hpgsql-0.4.0: src/Hpgsql/Encoding.hs
-- |
--
-- = Encoding and decoding fields and rows
--
-- This module contains a collection of functions, classes, and instances that can
-- help you build encoders and decoders for your Haskell types.
--
-- Here's an example:
--
-- > data Person = Person { name :: Text, born :: Day, heightMeters :: Double }
-- > deriving stock Generic
-- > deriving anyclass FromPgRow
-- >
-- > persons :: [Person] <- query conn "SELECT * FROM persons"
--
-- Note that Hpgsql's `RowDecoder` does not have a `Monad` instance because that allows it to
-- type check query results and field counts only once per query instead of paying that price
-- for every field of every row. If you need to write a row decoder that is monadic, check "Hpgsql.Encoding.RowDecoderMonadic".
--
-- = Manually derived row decoders
--
-- You can use `fieldRowDecoder` for each field in manually derived row decoders.
-- For example:
--
-- > data Car = Car { model :: Text, year :: Maybe Int, inGoodCondition :: Bool }
-- >
-- > instance FromPgRow Car where
-- > rowDecoder = Car <$> fieldRowDecoder
-- > <*> fieldRowDecoder
-- > <*> fieldRowDecoder
--
-- In our benchmarks hand written FromPgRow instances aren't any more performant than Generically derived ones.
--
-- Noteworthy is you should not use `singleField fieldDecoder` when you can use `fieldRowDecoder` instead. Hpgsql has rewrite rules to make this replacement when compiling with -O1, but under -O0 the latter is much faster.
module Hpgsql.Encoding
( -- * Decoding
FromPgField (fieldDecoder, fieldRowDecoder), -- Do not export other methods so we can change them
FieldDecoder (..),
FieldInfo (..),
FromPgRow (..),
RowDecoder (..), -- TODO: We should consider not exporting everything to give us freedom
singleField,
nullableField,
genericFromPgRow,
-- * Encoding
-- | Keep in mind that Haskell's `Int` is an `Int64` on most
-- hardware, which is a mismatch for the commonly used 32-bit
-- `integer` PostgreSQL type.
-- This is not a problem when decoding because Hpgsql can decode
-- `integer` into Haskell's `Int`, but when encoding PostgreSQL
-- will understandably not accept a larger type.
ToPgField (..),
FieldEncoder (..),
ToPgRow (..),
RowEncoder (..),
EncodingContext (..),
genericToPgRow,
-- * PostgreSQL enums
LowerCasedPgEnum (..),
genericEnumFieldDecoder,
genericEnumFieldEncoder,
-- * PostgreSQL composite types
compositeTypeDecoder,
compositeTypeEncoder,
-- * Driving PostgreSQL type inference
typeFieldDecoder,
typeFieldEncoder,
typeOidWithName,
typeMustBeNamed,
-- * Others
rawBytesFieldDecoder,
untypedFieldEncoder,
toPgVectorField,
arrayField,
)
where
import Hpgsql.Encoding.Internal