Database.PostgreSQL.PQTypes.Deriving

Helpers, to be used with deriving via (-XDerivingVia).

newtype SQLEnum a

Helper newtype to be used with deriving via to derive (PQFormat, ToSQL, FromSQL) instances for enums, given an instance of EnumEncoding.

Hint: non-trivial Enum instances can be derived using the 'generic-data' package!

>>> :{
data Colours = Blue | Black | Red | Mauve | Orange
  deriving (Eq, Show, Enum, Bounded)
instance EnumEncoding Colours where
  type EnumBase Colours = Int16
  encodeEnum = \case
    Blue   -> 1
    Black  -> 7
    Red    -> 2
    Mauve  -> 6
    Orange -> 3
:}

Note: To get SQL-specific instances use DerivingVia:

data Colours = ...
  ...
  deriving (PQFormat, ToSQL, FromSQL) via SQLEnum Colours

>>> isInjective (encodeEnum @Colours)
True

>>> decodeEnum @Colours 7
Right Black

>>> decodeEnum @Colours 42
Left [(1,3),(6,7)]

Constructors

SQLEnum a

Instances

(EnumEncoding a, PQFormat (EnumBase a), ToSQL (EnumBase a)) => ToSQL (SQLEnum a)

Defined in Database.PostgreSQL.PQTypes.Deriving

Associated Types

type PQDest (SQLEnum a)

Methods

toSQL :: SQLEnum a -> ParamAllocator -> (Ptr (PQDest (SQLEnum a)) -> IO r) -> IO r

(EnumEncoding a, PQFormat (EnumBase a), FromSQL (EnumBase a), Show (EnumBase a), Typeable (EnumBase a)) => FromSQL (SQLEnum a)

Defined in Database.PostgreSQL.PQTypes.Deriving

Associated Types

type PQBase (SQLEnum a)

Methods

fromSQL :: Maybe (PQBase (SQLEnum a)) -> IO (SQLEnum a)

PQFormat (EnumBase a) => PQFormat (SQLEnum a)

Defined in Database.PostgreSQL.PQTypes.Deriving

Methods

pqFormat :: ByteString

pqFormat0 :: ByteString

pqVariables :: Int

type PQDest (SQLEnum a)

Defined in Database.PostgreSQL.PQTypes.Deriving

type PQDest (SQLEnum a) = PQDest (EnumBase a)

type PQBase (SQLEnum a)

Defined in Database.PostgreSQL.PQTypes.Deriving

type PQBase (SQLEnum a) = PQBase (EnumBase a)

class (Enum a, Bounded a, Enum (EnumBase a), Ord (EnumBase a)) => EnumEncoding a where

Minimal complete definition

encodeEnum

Associated Types

type EnumBase a

Methods

encodeEnum :: a -> EnumBase a

Encode a as a base type.

decodeEnum :: EnumBase a -> Either [(EnumBase a, EnumBase a)] a

Decode base type to an a. If the conversion fails, a list of valid ranges is returned instead.

Note: The default implementation looks up values in decodeEnumMap and can be overwritten for performance if necessary.

decodeEnumMap :: Map (EnumBase a) a

Include the inverse map as a top-level part of the EnumEncoding instance to ensure it is only computed once by GHC.

newtype SQLEnumAsText a

A special case of SQLEnum, where the enum is to be encoded as text (SQLEnum can't be used because of the Enum constraint on the domain of encodeEnum).

>>> :{
data Person = Alfred | Bertrand | Charles
  deriving (Eq, Show, Enum, Bounded)
instance EnumAsTextEncoding Person where
  encodeEnumAsText = \case
    Alfred   -> "alfred"
    Bertrand -> "bertrand"
    Charles  -> "charles"
:}

Note: To get SQL-specific instances use DerivingVia:

data Person = ...
  ...
  deriving (PQFormat, ToSQL, FromSQL) via SQLEnumAsText Person

>>> isInjective (encodeEnumAsText @Person)
True

>>> decodeEnumAsText @Person "bertrand"
Right Bertrand

>>> decodeEnumAsText @Person "batman"
Left ["alfred","bertrand","charles"]

Constructors

SQLEnumAsText a

Instances

EnumAsTextEncoding a => ToSQL (SQLEnumAsText a)

Defined in Database.PostgreSQL.PQTypes.Deriving

Associated Types

type PQDest (SQLEnumAsText a)

Methods

toSQL :: SQLEnumAsText a -> ParamAllocator -> (Ptr (PQDest (SQLEnumAsText a)) -> IO r) -> IO r

EnumAsTextEncoding a => FromSQL (SQLEnumAsText a)

Defined in Database.PostgreSQL.PQTypes.Deriving

Associated Types

type PQBase (SQLEnumAsText a)

Methods

fromSQL :: Maybe (PQBase (SQLEnumAsText a)) -> IO (SQLEnumAsText a)

EnumAsTextEncoding a => PQFormat (SQLEnumAsText a)

Defined in Database.PostgreSQL.PQTypes.Deriving

Methods

pqFormat :: ByteString

pqFormat0 :: ByteString

pqVariables :: Int

type PQDest (SQLEnumAsText a)

Defined in Database.PostgreSQL.PQTypes.Deriving

type PQDest (SQLEnumAsText a) = PQDest Text

type PQBase (SQLEnumAsText a)

Defined in Database.PostgreSQL.PQTypes.Deriving

type PQBase (SQLEnumAsText a) = PQBase Text

class (Enum a, Bounded a) => EnumAsTextEncoding a where

Minimal complete definition

encodeEnumAsText

Methods

encodeEnumAsText :: a -> Text

Encode a as Text.

decodeEnumAsText :: Text -> Either [Text] a

Decode Text to an a. If the conversion fails, a list of valid values is returned instead.

Note: The default implementation looks up values in decodeEnumAsTextMap and can be overwritten for performance if necessary.

decodeEnumAsTextMap :: Map Text a

Include the inverse map as a top-level part of the SQLEnumTextEncoding instance to ensure it is only computed once by GHC.

For use in doctests.

isInjective :: (Enum a, Bounded a, Eq a, Eq b) => (a -> b) -> Bool

To be used in doctests to prove injectivity of encoding functions.

>>> isInjective (id :: Bool -> Bool)
True

>>> isInjective (\(_ :: Bool) -> False)
False