persistent-2.14.6.0: Type-safe, multi-backend data serialization.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Database.Persist.Class.PersistField

Synopsis

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 ErrorMessage
 deriving (Eq, Show, PersistFieldSql)

mkSSN :: ErrorMessage -> Either ErrorMessage 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 PersistValues 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 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 Html # 
Instance details

Defined in Database.Persist.Class.PersistField

PersistField ByteString # 
Instance details

Defined in Database.Persist.Class.PersistField

Methods

toPersistValue :: ByteString -> PersistValue #

fromPersistValue :: PersistValue -> Either Text ByteString #

PersistField OverflowNatural # 
Instance details

Defined in Database.Persist.Class.PersistField

PersistField PersistValue # 
Instance details

Defined in Database.Persist.Class.PersistField

PersistField Checkmark # 
Instance details

Defined in Database.Persist.Class.PersistField

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 Text0 Text #

PersistField Day # 
Instance details

Defined in Database.Persist.Class.PersistField

PersistField UTCTime # 
Instance details

Defined in Database.Persist.Class.PersistField

PersistField TimeOfDay # 
Instance details

Defined in Database.Persist.Class.PersistField

(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

PersistField (BackendKey SqlReadBackend) # 
Instance details

Defined in Database.Persist.Sql.Orphan.PersistStore

PersistField (BackendKey SqlWriteBackend) # 
Instance details

Defined in Database.Persist.Sql.Orphan.PersistStore

PersistField (BackendKey SqlBackend) # 
Instance details

Defined in Database.Persist.Sql.Orphan.PersistStore

PersistField a => PersistField (Vector a) # 
Instance details

Defined in Database.Persist.Class.PersistField

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

Instances

Instances details
Num OverflowNatural # 
Instance details

Defined in Database.Persist.Class.PersistField

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

Ord OverflowNatural # 
Instance details

Defined in Database.Persist.Class.PersistField

PersistField OverflowNatural # 
Instance details

Defined in Database.Persist.Class.PersistField

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 #