persistent-2.17.1.0: Type-safe, multi-backend data serialization.

Safe Haskell | None
Language | Haskell2010

Database.Persist.Class.PersistField

Synopsis

- class PersistField a where
  - toPersistValue :: a -> PersistValue
  - fromPersistValue :: PersistValue -> Either Text a
- getPersistMap :: PersistValue -> Either Text [(Text, PersistValue)]
- newtype OverflowNatural = OverflowNatural {
  - unOverflowNatural :: Natural
  }

# Documentation

class PersistField a where Source #

This class teaches Persistent how to take a custom type and marshal it to and from a `PersistValue`, allowing it to be stored in a database.

#### Examples

Expand

##### Simple Newtype

You can use `newtype` to add more type safety/readability to a basis type like `ByteString`. In these cases, just derive `PersistField` and `PersistFieldSql`:

    {-# LANGUAGE GeneralizedNewtypeDeriving #-}

    newtype HashedPassword = HashedPassword ByteString
      deriving (Eq, Show, PersistField, PersistFieldSql)

##### Smart Constructor Newtype

In this example, we create a `PersistField` instance for a newtype following the "Smart Constructor" pattern.

    {-# LANGUAGE GeneralizedNewtypeDeriving #-}
    import qualified Data.Text as T
    import qualified Data.Char as C

    -- | An American Social Security Number
    newtype SSN = SSN Text
     deriving (Eq, Show, PersistFieldSql)

    mkSSN :: Text -> Either Text SSN
    mkSSN t = if (T.length t == 9) && (T.all C.isDigit t)
     then Right $ SSN t
     else Left $ "Invalid SSN: " <> t

    instance PersistField SSN where
      toPersistValue (SSN t) = PersistText t
      fromPersistValue (PersistText t) = mkSSN t
      -- Handle cases where the database does not give us PersistText
      fromPersistValue x = Left $ "File.hs: When trying to deserialize an SSN: expected PersistText, received: " <> T.pack (show x)

Tips:

- This file contain dozens of `PersistField` instances you can look at for examples.
- Typically custom `PersistField` instances will only accept a single `PersistValue` constructor in `fromPersistValue`.
- Internal `PersistField` instances accept a wide variety of `PersistValue`s to accomodate e.g. storing booleans as integers, booleans or strings.
- If you're making a custom instance and using a SQL database, you'll also need `PersistFieldSql` to specify the type of the database column.

Methods

toPersistValue :: a -> PersistValue Source #

fromPersistValue :: PersistValue -> Either Text a Source #

#### Instances

Instances details

PersistField Html Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Html -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Html Source #
PersistField ByteString Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: ByteString -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text ByteString Source #
PersistField Int16 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int16 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Int16 Source #
PersistField Int32 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int32 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Int32 Source #
PersistField Int64 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int64 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Int64 Source #
PersistField Int8 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int8 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Int8 Source #
PersistField Rational Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Rational -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Rational Source #
PersistField Word16 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word16 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Word16 Source #
PersistField Word32 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word32 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Word32 Source #
PersistField Word64 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word64 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Word64 Source #
PersistField Word8 Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word8 -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Word8 Source #
PersistField OverflowNatural Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: OverflowNatural -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text OverflowNatural Source #
PersistField PersistValue Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: PersistValue -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text PersistValue Source #
PersistField Checkmark Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Checkmark -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Checkmark Source #
PersistField Text Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Text -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Text Source #
PersistField Text Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Text -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Text Source #
PersistField Day Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Day -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Day Source #
PersistField UTCTime Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: UTCTime -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text UTCTime Source #
PersistField TimeOfDay Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: TimeOfDay -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text TimeOfDay Source #

(TypeError ((((('Text "The instance of PersistField for the Natural type was removed." ':$$: 'Text "Please see the documentation for OverflowNatural if you want to ") ':$$: 'Text "continue using the old behavior or want to see documentation on ") ':$$: 'Text "why the instance was removed.") ':$$: 'Text "") ':$$: 'Text "This error instance will be removed in a future release.") :: Constraint) => PersistField Natural Source #

Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Natural -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Natural Source #
PersistField Bool Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Bool -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Bool Source #
PersistField Double Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Double -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Double Source #
PersistField Int Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Int Source #
PersistField Word Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text Word Source #
PersistField v => PersistField (IntMap v) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: IntMap v -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (IntMap v) Source #
(Ord a, PersistField a) => PersistField (Set a) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Set a -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (Set a) Source #
(PersistEntity record, PersistField record, PersistField (Key record)) => PersistField (Entity record) Source # |
Instance details Defined in Database.Persist.Class.PersistEntity Methods toPersistValue :: Entity record -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (Entity record) Source #
(BackendCompatible b s, PersistField (BackendKey b)) => PersistField (BackendKey (Compatible b s)) Source # |
Instance details Defined in Database.Persist.Compatible.Types Methods toPersistValue :: BackendKey (Compatible b s) -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (BackendKey (Compatible b s)) Source #
PersistField (BackendKey SqlReadBackend) Source # |
Instance details Defined in Database.Persist.Sql.Orphan.PersistStore Methods toPersistValue :: BackendKey SqlReadBackend -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (BackendKey SqlReadBackend) Source #
PersistField (BackendKey SqlWriteBackend) Source # |
Instance details Defined in Database.Persist.Sql.Orphan.PersistStore Methods toPersistValue :: BackendKey SqlWriteBackend -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (BackendKey SqlWriteBackend) Source #
PersistField (BackendKey SqlBackend) Source # |
Instance details Defined in Database.Persist.Sql.Orphan.PersistStore Methods toPersistValue :: BackendKey SqlBackend -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (BackendKey SqlBackend) Source #
PersistField a => PersistField (Vector a) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Vector a -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (Vector a) Source #
PersistField a => PersistField (Maybe a) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Maybe a -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (Maybe a) Source #
PersistField [Char] Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: [Char] -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text [Char] Source #
PersistField a => PersistField [a] Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: [a] -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text [a] Source #
HasResolution a => PersistField (Fixed a) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Fixed a -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (Fixed a) Source #
PersistField v => PersistField (Map Text v) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Map Text v -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (Map Text v) Source #
(PersistField a, PersistField b) => PersistField (a, b) Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: (a, b) -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text (a, b) Source #

getPersistMap :: PersistValue -> Either Text [(Text, PersistValue)] Source #

FIXME Add documentation to that.

newtype OverflowNatural Source #

Prior to `persistent-2.11.0`, we provided an instance of `PersistField` for the `Natural` type. This was in error, because `Natural` represents an infinite value, and databases don't have reasonable types for this.

The instance for `Natural` used the `Int64` underlying type, which will cause underflow and overflow errors. This type has the exact same code in the instances, and will work seamlessly.

A more appropriate type for this is the `Word` series of types from Data.Word. These have a bounded size, are guaranteed to be non-negative, and are quite efficient for the database to store.

Since: 2.11.0

Constructors

OverflowNatural |

Fields

- unOverflowNatural :: Natural

#### Instances

Instances details

Num OverflowNatural Source # |

Instance details

Defined in Database.Persist.Class.PersistField

Methods

(+) :: OverflowNatural -> OverflowNatural -> OverflowNatural Source #

(-) :: OverflowNatural -> OverflowNatural -> OverflowNatural Source #

(*) :: OverflowNatural -> OverflowNatural -> OverflowNatural Source #

negate :: OverflowNatural -> OverflowNatural Source #

abs :: OverflowNatural -> OverflowNatural Source #

signum :: OverflowNatural -> OverflowNatural Source #

fromInteger :: Integer -> OverflowNatural Source #

Show OverflowNatural Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods showsPrec :: Int -> OverflowNatural -> ShowS Source # show :: OverflowNatural -> String Source # showList :: [OverflowNatural] -> ShowS Source #
Eq OverflowNatural Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods (==) :: OverflowNatural -> OverflowNatural -> Bool Source # (/=) :: OverflowNatural -> OverflowNatural -> Bool Source #
Ord OverflowNatural Source # |

Instance details

Defined in Database.Persist.Class.PersistField

Methods

compare :: OverflowNatural -> OverflowNatural -> Ordering Source #

(<) :: OverflowNatural -> OverflowNatural -> Bool Source #

(<=) :: OverflowNatural -> OverflowNatural -> Bool Source #

(>) :: OverflowNatural -> OverflowNatural -> Bool Source #

(>=) :: OverflowNatural -> OverflowNatural -> Bool Source #

max :: OverflowNatural -> OverflowNatural -> OverflowNatural Source #

min :: OverflowNatural -> OverflowNatural -> OverflowNatural Source #

PersistField OverflowNatural Source # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: OverflowNatural -> PersistValue Source # fromPersistValue :: PersistValue -> Either Text OverflowNatural Source #
PersistFieldSql OverflowNatural Source # | This type uses the `SqlInt64` version, which will exhibit overflow and underflow behavior. Additionally, it permits negative values in the database, which isn't ideal. Since: 2.11.0
Instance details Defined in Database.Persist.Sql.Class Methods sqlType :: Proxy OverflowNatural -> SqlType Source #