This module defines the functions and datatypes used throughout the framework. Most of them are for internal use
- class PersistField v => PersistEntity v where
- data Fields v :: * -> * -> *
- entityDef :: v -> EntityDef
- toPersistValues :: PersistBackend m => v -> m [PersistValue]
- fromPersistValues :: PersistBackend m => [PersistValue] -> m v
- getConstraints :: v -> (Int, [(String, [(String, PersistValue)])])
- showField :: Fields v c a -> String
- eqField :: Fields v c a -> Fields v c a -> Bool
- data PersistValue
- class PersistField a where
- persistName :: a -> String
- toPersistValue :: PersistBackend m => a -> m PersistValue
- fromPersistValue :: PersistBackend m => PersistValue -> m a
- dbType :: a -> DbType
- data PersistEntity v => Key v = Key Int64
- data Cond v c
- = And (Cond v c) (Cond v c)
- | Or (Cond v c) (Cond v c)
- | Not (Cond v c)
- | forall a . (HasOrder a, PersistField a) => Lesser (Expr v c a) (Expr v c a)
- | forall a . (HasOrder a, PersistField a) => Greater (Expr v c a) (Expr v c a)
- | forall a . PersistField a => Equals (Expr v c a) (Expr v c a)
- | forall a . PersistField a => NotEquals (Expr v c a) (Expr v c a)
- | KeyIs (Key v)
- data Update v c = forall a . Update (Fields v c a) (Expr v c a)
- (=.) :: (Expression a, TypesCastV v (FuncV a) v, TypesCastC c (FuncC a) c) => Fields v c (FuncA a) -> a -> Update v c
- (&&.) :: (TypesCastV v1 v2 v3, TypesCastC c1 c2 c3) => Cond v1 c1 -> Cond v2 c2 -> Cond v3 c3
- (||.) :: (TypesCastV v1 v2 v3, TypesCastC c1 c2 c3) => Cond v1 c1 -> Cond v2 c2 -> Cond v3 c3
- (==.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a)) => a -> b -> Cond v c
- (/=.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a)) => a -> b -> Cond v c
- (<.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v c
- (<=.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v c
- (>.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v c
- (>=.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v c
- wrapPrim :: Primitive a => a -> Expr Any Any a
- toArith :: Fields v c a -> Arith v c a
- class Expression a where
- class Primitive a where
- toPrim :: a -> PersistValue
- fromPrim :: PersistValue -> a
- class HasOrder a
- class Numeric a
- class NeverNull a
- data Arith v c a
- data Expr v c a where
- data Order v c
- data DbType
- data NamedType
- namedType :: PersistField v => v -> NamedType
- getName :: NamedType -> String
- getType :: NamedType -> DbType
- data EntityDef = EntityDef {
- entityName :: String
- typeParams :: [NamedType]
- constructors :: [ConstructorDef]
- data ConstructorDef = ConstructorDef {
- constrNum :: Int
- constrName :: String
- constrParams :: [(String, NamedType)]
- constrConstrs :: [Constraint]
- class Constructor a where
- phantomConstrName :: a -> String
- phantomConstrNum :: a -> Int
- type Constraint = (String, [String])
- type SingleMigration = Either [String] [(Bool, String)]
- type NamedMigrations = Map String SingleMigration
- type Migration m = StateT NamedMigrations m ()
- class Monad m => PersistBackend m where
- insert :: PersistEntity v => v -> m (Key v)
- insertBy :: PersistEntity v => v -> m (Either (Key v) (Key v))
- replace :: PersistEntity v => Key v -> v -> m ()
- selectEnum :: (PersistEntity v, Constructor c) => Cond v c -> [Order v c] -> Int -> Int -> Enumerator (Key v, v) m a
- selectAllEnum :: PersistEntity v => Enumerator (Key v, v) m a
- select :: (PersistEntity v, Constructor c) => Cond v c -> [Order v c] -> Int -> Int -> m [(Key v, v)]
- selectAll :: PersistEntity v => m [(Key v, v)]
- get :: PersistEntity v => Key v -> m (Maybe v)
- update :: (PersistEntity v, Constructor c) => [Update v c] -> Cond v c -> m ()
- delete :: (PersistEntity v, Constructor c) => Cond v c -> m ()
- deleteByKey :: PersistEntity v => Key v -> m ()
- count :: (PersistEntity v, Constructor c) => Cond v c -> m Int
- countAll :: PersistEntity v => v -> m Int
- migrate :: PersistEntity v => v -> Migration m
- executeRaw :: Bool -> String -> [PersistValue] -> m ()
- queryRaw :: Bool -> String -> [PersistValue] -> (RowPopper m -> m a) -> m a
- insertTuple :: NamedType -> [PersistValue] -> m Int64
- getTuple :: NamedType -> Int64 -> m [PersistValue]
- insertList :: PersistField a => [a] -> m Int64
- getList :: PersistField a => Int64 -> m [a]
- type RowPopper m = m (Maybe [PersistValue])
- newtype Monad m => DbPersist conn m a = DbPersist {
- unDbPersist :: ReaderT conn m a
- runDbPersist :: Monad m => DbPersist conn m a -> conn -> m a
Main types
class PersistField v => PersistEntity v whereSource
Only instances of this class can be persisted in a database
data Fields v :: * -> * -> *Source
This type is used for typesafe manipulation of separate fields of datatype v.
Each constructor in Fields
corresponds to its field in a datatype v.
It is parametrised by constructor phantom type and field value type.
entityDef :: v -> EntityDefSource
Returns a complete description of the type
toPersistValues :: PersistBackend m => v -> m [PersistValue]Source
Marshalls value to a list of PersistValue
ready for insert to a database
fromPersistValues :: PersistBackend m => [PersistValue] -> m vSource
Constructs the value from the list of PersistValue
getConstraints :: v -> (Int, [(String, [(String, PersistValue)])])Source
Returns constructor number and a list of constraint names and corresponding field names with their values
data PersistValue Source
A raw value which can be stored in any backend and can be marshalled to
and from a PersistField
.
class PersistField a whereSource
persistName :: a -> StringSource
Return name of the type. If it is polymorhic, the names of parameter types are separated with "$" symbol
toPersistValue :: PersistBackend m => a -> m PersistValueSource
Convert a value into something which can be stored in a database column. Note that for complex datatypes it may insert them to return identifier
fromPersistValue :: PersistBackend m => PersistValue -> m aSource
Constructs a value from a PersistValue
. For complex datatypes it may query the database
Description of value type
PersistField Bool | |
PersistField Double | |
PersistField Int | |
PersistField Int8 | |
PersistField Int16 | |
PersistField Int32 | |
PersistField Int64 | |
PersistField Word8 | |
PersistField Word16 | |
PersistField Word32 | |
PersistField Word64 | |
PersistField String | |
PersistField ByteString | |
PersistField Text | |
PersistField TimeOfDay | |
PersistField UTCTime | |
PersistField Day | |
PersistField a => PersistField [a] | |
(PersistField a, NeverNull a) => PersistField (Maybe a) | |
PersistEntity a => PersistField (Key a) | |
(PersistField a, PersistField b) => PersistField (a, b) | |
(PersistField a, PersistField b, PersistField c) => PersistField (a, b, c) | |
(PersistField a, PersistField b, PersistField c, PersistField d) => PersistField (a, b, c, d) | |
(PersistField a, PersistField b, PersistField c, PersistField d, PersistField e) => PersistField (a, b, c, d, e) |
data PersistEntity v => Key v Source
A unique identifier of a value stored in a database
PersistEntity v => Show (Key v) | |
PersistEntity a => PersistField (Key a) | |
Expression (Key a) | |
Primitive (Key a) | |
NeverNull (Key a) |
Constructing expressions
The expressions are used in conditions and right part of Update statement. Despite the wordy types of the comparison functions, they are simple to use. Type of the compared polymorphic values like numbers or Nothing must be supplied manually. Example:
StringField ==. "abc" &&. NumberField >. (0 :: Int) ||. MaybeField ==. (Nothing :: Maybe String) ||. MaybeField ==. Just "def"
Represents condition for a query.
And (Cond v c) (Cond v c) | |
Or (Cond v c) (Cond v c) | |
Not (Cond v c) | |
forall a . (HasOrder a, PersistField a) => Lesser (Expr v c a) (Expr v c a) | |
forall a . (HasOrder a, PersistField a) => Greater (Expr v c a) (Expr v c a) | |
forall a . PersistField a => Equals (Expr v c a) (Expr v c a) | |
forall a . PersistField a => NotEquals (Expr v c a) (Expr v c a) | |
KeyIs (Key v) | Lookup will be performed only in table for the specified constructor c. To fetch value by key without constructor limitation use |
(=.) :: (Expression a, TypesCastV v (FuncV a) v, TypesCastC c (FuncC a) c) => Fields v c (FuncA a) -> a -> Update v cSource
Update field
(&&.) :: (TypesCastV v1 v2 v3, TypesCastC c1 c2 c3) => Cond v1 c1 -> Cond v2 c2 -> Cond v3 c3Source
Boolean "and" operator.
(||.) :: (TypesCastV v1 v2 v3, TypesCastC c1 c2 c3) => Cond v1 c1 -> Cond v2 c2 -> Cond v3 c3Source
Boolean "or" operator.
(<.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v cSource
(<=.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v cSource
(>.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v cSource
(>=.) :: (TypeCast a b v c, FuncA a ~ FuncA b, PersistField (FuncA a), HasOrder (FuncA a)) => a -> b -> Cond v cSource
wrapPrim :: Primitive a => a -> Expr Any Any aSource
By default during converting values of certain types to Expr
, the types can be changed. For example,
is transformed into Key
aa
.
It is convenient because the fields usually contain reference to a certain datatype, not its Key
.
But sometimes when automatic transformation gets in the way function wrapPrim
will help. Use it when a field in a datatype has type (Key a)
or Maybe (Key a)
. Example:
data Example = Example {entity1 :: Maybe Smth, entity2 :: Key Smth} Entity1Field ==. Just k &&. Entity2Field ==. wrapPrim k
class Expression a whereSource
Instances of this type can be converted to Expr
Expression Bool | |
Expression Int | |
Expression Int8 | |
Expression Int16 | |
Expression Int32 | |
Expression Int64 | |
Expression Word8 | |
Expression Word16 | |
Expression Word32 | |
Expression Word64 | |
Expression String | |
Expression ByteString | |
Expression Text | |
(Expression a, Primitive a, NeverNull a) => Expression (Maybe a) | |
Expression (Key a) | |
Expression (Expr v c a) | |
PersistEntity v => Expression (Arith v c a) | |
PersistEntity v => Expression (Fields v c a) |
Datatypes which can be converted directly to PersistValue
toPrim :: a -> PersistValueSource
fromPrim :: PersistValue -> aSource
The same goals as for Numeric
. Certain types like String which have order in Haskell may not have it in DB
Types which when converted to PersistValue
are never NULL.
Consider the type Maybe (Maybe a)
. Now Nothing is stored as NULL, so we cannot distinguish between Just Nothing and Nothing which is a problem.
The purpose of this class is to ban the inner Maybe's.
Maybe this class can be removed when support for inner Maybe's appears.
NeverNull Bool | |
NeverNull Double | |
NeverNull Int | |
NeverNull Int64 | |
NeverNull String | |
PersistEntity a => NeverNull a | |
NeverNull ByteString | |
NeverNull Text | |
NeverNull TimeOfDay | |
NeverNull UTCTime | |
NeverNull Day | |
NeverNull [a] | |
NeverNull (Key a) | |
NeverNull (a, b) | |
NeverNull (a, b, c) | |
NeverNull (a, b, c, d) | |
NeverNull (a, b, c, d, e) |
Arithmetic expressions which can include fields and literals
Used to uniformly represent fields, literals and arithmetic expressions.
A value should be convertec to Expr
for usage in expressions
ExprPrim :: Primitive a => a -> Expr v c a | |
ExprField :: PersistEntity v => Fields v c a -> Expr v c a | |
ExprArith :: PersistEntity v => Arith v c a -> Expr v c a | |
ExprPlain :: Primitive a => a -> Expr v c (FuncA a) |
Expression (Expr v c a) |
Defines sort order of a result-set
Type description
A DB data type. Naming attempts to reflect the underlying Haskell datatypes, eg DbString instead of DbVarchar. Different databases may have different translations for these types.
It is used to store type DbType
and persist name of a value
namedType :: PersistField v => v -> NamedTypeSource
Describes an ADT.
EntityDef | |
|
data ConstructorDef Source
Describes an entity constructor
ConstructorDef | |
|
class Constructor a whereSource
Phantom constructors are made instances of this class. This class should be used only by Template Haskell codegen
phantomConstrName :: a -> StringSource
phantomConstrNum :: a -> IntSource
type Constraint = (String, [String])Source
Constraint name and list of the field names that form a unique combination.
Only fields of Primitive
types can be used in a constraint
Migration
type SingleMigration = Either [String] [(Bool, String)]Source
Either error messages or migration queries with safety flags
type NamedMigrations = Map String SingleMigrationSource
Datatype names and corresponding migrations
type Migration m = StateT NamedMigrations m ()Source
Database
class Monad m => PersistBackend m whereSource
insert :: PersistEntity v => v -> m (Key v)Source
Insert a new record to a database and return its Key
insertBy :: PersistEntity v => v -> m (Either (Key v) (Key v))Source
Try to insert a record and return Right newkey. If there is a constraint violation, Left oldkey is returned , where oldkey is an identifier of the record with the same constraint values. Note that if several constraints are violated, a key of an arbitrary matching record is returned.
replace :: PersistEntity v => Key v -> v -> m ()Source
Replace a record with the given key. Result is undefined if the record does not exist.
:: (PersistEntity v, Constructor c) | |
=> Cond v c | |
-> [Order v c] | |
-> Int | limit |
-> Int | offset |
-> Enumerator (Key v, v) m a |
Return a list of all records
selectAllEnum :: PersistEntity v => Enumerator (Key v, v) m aSource
Get all records. Order is undefined
:: (PersistEntity v, Constructor c) | |
=> Cond v c | |
-> [Order v c] | |
-> Int | limit |
-> Int | offset |
-> m [(Key v, v)] |
Return a list of the records satisfying the condition
selectAll :: PersistEntity v => m [(Key v, v)]Source
Return a list of all records. Order is undefined
get :: PersistEntity v => Key v -> m (Maybe v)Source
Fetch an entity from a database
update :: (PersistEntity v, Constructor c) => [Update v c] -> Cond v c -> m ()Source
Update the records satisfying the condition
delete :: (PersistEntity v, Constructor c) => Cond v c -> m ()Source
Remove the records satisfying the condition
deleteByKey :: PersistEntity v => Key v -> m ()Source
Remove the record with given key. No-op if the record does not exist
count :: (PersistEntity v, Constructor c) => Cond v c -> m IntSource
Count total number of records satisfying the condition
countAll :: PersistEntity v => v -> m IntSource
Count total number of records with all constructors
migrate :: PersistEntity v => v -> Migration mSource
Check database schema and create migrations for the entity and the entities it contains
:: Bool | keep in cache |
-> String | query |
-> [PersistValue] | positional parameters |
-> m () |
Execute raw query
:: Bool | keep in cache |
-> String | query |
-> [PersistValue] | positional parameters |
-> (RowPopper m -> m a) | results processing function |
-> m a |
Execute raw query with results
insertTuple :: NamedType -> [PersistValue] -> m Int64Source
getTuple :: NamedType -> Int64 -> m [PersistValue]Source
insertList :: PersistField a => [a] -> m Int64Source
getList :: PersistField a => Int64 -> m [a]Source
type RowPopper m = m (Maybe [PersistValue])Source
newtype Monad m => DbPersist conn m a Source
DbPersist | |
|
MonadTrans (DbPersist conn) | |
Monad m => Monad (DbPersist conn m) | |
Functor m => Functor (DbPersist conn m) | |
Applicative m => Applicative (DbPersist conn m) | |
MonadIO m => MonadIO (DbPersist conn m) | |
MonadControlIO m => MonadControlIO (DbPersist conn m) |
runDbPersist :: Monad m => DbPersist conn m a -> conn -> m aSource