Database.Persist.Class.PersistField

persistent-2.14.6.3: 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 #

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 #

fromPersistValue :: PersistValue -> Either Text a #

#### Instances

Instances details

PersistField Html # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Html -> PersistValue # fromPersistValue :: PersistValue -> Either Text Html #
PersistField ByteString # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: ByteString -> PersistValue # fromPersistValue :: PersistValue -> Either Text ByteString #
PersistField Int16 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int16 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Int16 #
PersistField Int32 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int32 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Int32 #
PersistField Int64 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int64 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Int64 #
PersistField Int8 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int8 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Int8 #
PersistField Rational # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Rational -> PersistValue # fromPersistValue :: PersistValue -> Either Text Rational #
PersistField Word16 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word16 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Word16 #
PersistField Word32 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word32 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Word32 #
PersistField Word64 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word64 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Word64 #
PersistField Word8 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word8 -> PersistValue # fromPersistValue :: PersistValue -> Either Text Word8 #
PersistField OverflowNatural # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: OverflowNatural -> PersistValue # fromPersistValue :: PersistValue -> Either Text OverflowNatural #
PersistField PersistValue # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: PersistValue -> PersistValue # fromPersistValue :: PersistValue -> Either Text PersistValue #
PersistField Checkmark # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Checkmark -> PersistValue # fromPersistValue :: PersistValue -> Either Text Checkmark #
PersistField Text # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Text -> PersistValue # fromPersistValue :: PersistValue -> Either Text Text #
PersistField Text # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Text -> PersistValue # fromPersistValue :: PersistValue -> Either Text Text #
PersistField Day # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Day -> PersistValue # fromPersistValue :: PersistValue -> Either Text Day #
PersistField UTCTime # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: UTCTime -> PersistValue # fromPersistValue :: PersistValue -> Either Text UTCTime #
PersistField TimeOfDay # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: TimeOfDay -> PersistValue # fromPersistValue :: PersistValue -> Either Text TimeOfDay #
(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 # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Natural -> PersistValue # fromPersistValue :: PersistValue -> Either Text Natural #
PersistField Bool # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Bool -> PersistValue # fromPersistValue :: PersistValue -> Either Text Bool #
PersistField Double # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Double -> PersistValue # fromPersistValue :: PersistValue -> Either Text Double #
PersistField Int # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Int -> PersistValue # fromPersistValue :: PersistValue -> Either Text Int #
PersistField Word # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Word -> PersistValue # fromPersistValue :: PersistValue -> Either Text Word #
PersistField v => PersistField (IntMap v) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: IntMap v -> PersistValue # fromPersistValue :: PersistValue -> Either Text (IntMap v) #
(Ord a, PersistField a) => PersistField (Set a) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Set a -> PersistValue # fromPersistValue :: PersistValue -> Either Text (Set a) #
(PersistEntity record, PersistField record, PersistField (Key record)) => PersistField (Entity record) # |
Instance details Defined in Database.Persist.Class.PersistEntity Methods toPersistValue :: Entity record -> PersistValue # fromPersistValue :: PersistValue -> Either Text (Entity record) #
(BackendCompatible b s, PersistField (BackendKey b)) => PersistField (BackendKey (Compatible b s)) # |
Instance details Defined in Database.Persist.Compatible.Types Methods toPersistValue :: BackendKey (Compatible b s) -> PersistValue # fromPersistValue :: PersistValue -> Either Text (BackendKey (Compatible b s)) #
PersistField (BackendKey SqlReadBackend) # |
Instance details Defined in Database.Persist.Sql.Orphan.PersistStore Methods toPersistValue :: BackendKey SqlReadBackend -> PersistValue # fromPersistValue :: PersistValue -> Either Text (BackendKey SqlReadBackend) #
PersistField (BackendKey SqlWriteBackend) # |
Instance details Defined in Database.Persist.Sql.Orphan.PersistStore Methods toPersistValue :: BackendKey SqlWriteBackend -> PersistValue # fromPersistValue :: PersistValue -> Either Text (BackendKey SqlWriteBackend) #
PersistField (BackendKey SqlBackend) # |
Instance details Defined in Database.Persist.Sql.Orphan.PersistStore Methods toPersistValue :: BackendKey SqlBackend -> PersistValue # fromPersistValue :: PersistValue -> Either Text (BackendKey SqlBackend) #
PersistField a => PersistField (Vector a) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Vector a -> PersistValue # fromPersistValue :: PersistValue -> Either Text (Vector a) #
PersistField a => PersistField (Maybe a) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Maybe a -> PersistValue # fromPersistValue :: PersistValue -> Either Text (Maybe a) #
PersistField [Char] # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: [Char] -> PersistValue # fromPersistValue :: PersistValue -> Either Text [Char] #
PersistField a => PersistField [a] # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: [a] -> PersistValue # fromPersistValue :: PersistValue -> Either Text [a] #
HasResolution a => PersistField (Fixed a) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Fixed a -> PersistValue # fromPersistValue :: PersistValue -> Either Text (Fixed a) #
PersistField v => PersistField (Map Text v) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: Map Text v -> PersistValue # fromPersistValue :: PersistValue -> Either Text (Map Text v) #
(PersistField a, PersistField b) => PersistField (a, b) # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: (a, b) -> PersistValue # fromPersistValue :: PersistValue -> Either Text (a, b) #

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

FIXME Add documentation to that.

newtype OverflowNatural #

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 # |
Instance details Defined in Database.Persist.Class.PersistField Methods (+) :: OverflowNatural -> OverflowNatural -> OverflowNatural # (-) :: OverflowNatural -> OverflowNatural -> OverflowNatural # (*) :: OverflowNatural -> OverflowNatural -> OverflowNatural # negate :: OverflowNatural -> OverflowNatural # abs :: OverflowNatural -> OverflowNatural # signum :: OverflowNatural -> OverflowNatural # fromInteger :: Integer -> OverflowNatural #
Show OverflowNatural # |
Instance details Defined in Database.Persist.Class.PersistField Methods showsPrec :: Int -> OverflowNatural -> ShowS # show :: OverflowNatural -> String # showList :: [OverflowNatural] -> ShowS #
Eq OverflowNatural # |
Instance details Defined in Database.Persist.Class.PersistField Methods (==) :: OverflowNatural -> OverflowNatural -> Bool # (/=) :: OverflowNatural -> OverflowNatural -> Bool #
Ord OverflowNatural # |
Instance details Defined in Database.Persist.Class.PersistField Methods compare :: OverflowNatural -> OverflowNatural -> Ordering # (<) :: OverflowNatural -> OverflowNatural -> Bool # (<=) :: OverflowNatural -> OverflowNatural -> Bool # (>) :: OverflowNatural -> OverflowNatural -> Bool # (>=) :: OverflowNatural -> OverflowNatural -> Bool # max :: OverflowNatural -> OverflowNatural -> OverflowNatural # min :: OverflowNatural -> OverflowNatural -> OverflowNatural #
PersistField OverflowNatural # |
Instance details Defined in Database.Persist.Class.PersistField Methods toPersistValue :: OverflowNatural -> PersistValue # fromPersistValue :: PersistValue -> Either Text OverflowNatural #
PersistFieldSql OverflowNatural # | 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 #