Database.Persist.TH

This module provides utilities for creating backends. Regular users do not need to use this module.

Parse entity defs

persistWith :: PersistSettings -> QuasiQuoter

Converts a quasi-quoted syntax into a list of entity definitions, to be used as input to the template haskell generation code (mkPersist).

persistUpperCase :: QuasiQuoter

Apply persistWith to upperCaseSettings.

persistLowerCase :: QuasiQuoter

Apply persistWith to lowerCaseSettings.

persistFileWith :: PersistSettings -> FilePath -> Q Exp

Same as persistWith, but uses an external file instead of a quasiquotation.

persistManyFileWith :: PersistSettings -> [FilePath] -> Q Exp

Same as persistFileWith, but uses several external files instead of one. Splitting your Persistent definitions into multiple modules can potentially dramatically speed up compile times.

Examples

Split your Persistent definitions into multiple files (models1, models2), then create a new module for each new file and run mkPersist there:

-- Model1.hs
share
    [mkPersist sqlSettings]
    $(persistFileWith lowerCaseSettings "models1")

-- Model2.hs
share
    [mkPersist sqlSettings]
    $(persistFileWith lowerCaseSettings "models2")

Use persistManyFileWith to create your migrations:

-- Migrate.hs
share
    [mkMigrate "migrateAll"]
    $(persistManyFileWith lowerCaseSettings ["models1","models2"]) 

Tip: To get the same import behavior as if you were declaring all your models in one file, import your new files as Name into another file, then export module Name.

This approach may be used in the future to reduce memory usage during compilation, but so far we've only seen mild reductions.

See persistent#778 and persistent#791 for more details.

Since: 2.5.4

Turn EntityDefs into types

mkPersist :: MkPersistSettings -> [EntityDef] -> Q [Dec]

Create data types and appropriate PersistEntity instances for the given EntityDefs. Works well with the persist quasi-quoter.

data MkPersistSettings

Settings to be passed to the mkPersist function.

mpsBackend :: MkPersistSettings -> Type

Which database backend we're using.

When generating data types, each type is given a generic version- which works with any backend- and a type synonym for the commonly used backend. This is where you specify that commonly used backend.

mpsGeneric :: MkPersistSettings -> Bool

Create generic types that can be used with multiple backends. Good for reusable code, but makes error messages harder to understand. Default: False.

mpsPrefixFields :: MkPersistSettings -> Bool

Prefix field names with the model name. Default: True.

mpsEntityJSON :: MkPersistSettings -> Maybe EntityJSON

Generate ToJSON/FromJSON instances for each model types. If it's Nothing, no instances will be generated. Default:

 Just EntityJSON
     { entityToJSON = 'keyValueEntityToJSON
     , entityFromJSON = 'keyValueEntityFromJSON
     }

mpsGenerateLenses :: MkPersistSettings -> Bool

Instead of generating normal field accessors, generator lens-style accessors.

Default: False

Since: 1.3.1

data EntityJSON

Constructors

EntityJSON

Fields

• entityToJSON :: Name

  Name of the toJSON implementation for Entity a.

• entityFromJSON :: Name

  Name of the fromJSON implementation for Entity a.

mkPersistSettings

Arguments

:: Type

Value for mpsBackend

-> MkPersistSettings

Create an MkPersistSettings with default values.

sqlSettings :: MkPersistSettings

Use the SqlPersist backend.

sqlOnlySettings :: MkPersistSettings

Deprecated: use sqlSettings

Same as sqlSettings.

Since: 1.1.1

Various other TH functions

mkMigrate :: String -> [EntityDef] -> Q [Dec]

Creates a single function to perform all migrations for the entities defined here. One thing to be aware of is dependencies: if you have entities with foreign references, make sure to place those definitions after the entities they reference.

mkSave :: String -> [EntityDef] -> Q [Dec]

Save the EntityDefs passed in under the given name.

mkDeleteCascade :: MkPersistSettings -> [EntityDef] -> Q [Dec]

Generate a DeleteCascade instance for the given EntityDefs.

share :: [[EntityDef] -> Q [Dec]] -> [EntityDef] -> Q [Dec]

Apply the given list of functions to the same EntityDefs.

This function is useful for cases such as:

>>> share [mkSave "myDefs", mkPersist sqlSettings] [persistLowerCase|...|]

derivePersistField :: String -> Q [Dec]

Automatically creates a valid PersistField instance for any datatype that has valid Show and Read instances. Can be very convenient for Enum types.

derivePersistFieldJSON :: String -> Q [Dec]

Automatically creates a valid PersistField instance for any datatype that has valid ToJSON and FromJSON instances. For a datatype T it generates instances similar to these:

   instance PersistField T where
       toPersistValue = PersistByteString . L.toStrict . encode
       fromPersistValue = (left T.pack) . eitherDecodeStrict' <=< fromPersistValue
   instance PersistFieldSql T where
       sqlType _ = SqlString

persistFieldFromEntity :: MkPersistSettings -> EntityDef -> Q [Dec]

produce code similar to the following:

  instance PersistEntity e => PersistField e where
     toPersistValue = PersistMap $ zip columNames (map toPersistValue . toPersistFields)
     fromPersistValue (PersistMap o) =
         let columns = HM.fromList o
         in fromPersistValues $ map (name ->
           case HM.lookup name columns of
             Just v -> v
             Nothing -> PersistNull
     fromPersistValue x = Left $ "Expected PersistMap, received: " ++ show x
     sqlType _ = SqlString

Internal

packPTH :: String -> Text

lensPTH :: (s -> a) -> (s -> b -> t) -> Lens s t a b

parseReferences :: PersistSettings -> Text -> Q Exp

Since: 2.5.3

Orphan instances

Lift' a => Lift a

Methods

lift :: a -> Q Exp

Lift EntityDef

Methods

lift :: EntityDef -> Q Exp

Lift HaskellName

Methods

lift :: HaskellName -> Q Exp

Lift DBName

Methods

lift :: DBName -> Q Exp

Lift FieldType

Methods

lift :: FieldType -> Q Exp

Lift FieldDef

Methods

lift :: FieldDef -> Q Exp

Lift ReferenceDef

Methods

lift :: ReferenceDef -> Q Exp

Lift EmbedEntityDef

Methods

lift :: EmbedEntityDef -> Q Exp

Lift EmbedFieldDef

Methods

lift :: EmbedFieldDef -> Q Exp

Lift UniqueDef

Methods

lift :: UniqueDef -> Q Exp

Lift CompositeDef

Methods

lift :: CompositeDef -> Q Exp

Lift ForeignDef

Methods

lift :: ForeignDef -> Q Exp

Lift SqlType

Methods

lift :: SqlType -> Q Exp

Lift PersistFilter

Methods

lift :: PersistFilter -> Q Exp

Lift PersistUpdate

Methods

lift :: PersistUpdate -> Q Exp