Database.Groundhog.Core

This module defines the functions and datatypes used throughout the framework. Most of them are for the internal use

Main types

class (PurePersistField (AutoKey v), PurePersistField (DefaultKey v)) => PersistEntity v where

Only instances of this class can be persisted in a database

Minimal complete definition

entityDef, toEntityPersistValues, fromEntityPersistValues, getUniques, entityFieldChain

Associated Types

data Field v :: ((* -> *) -> *) -> * -> *

This type is used for typesafe manipulation of separate fields of datatype v. Each constructor in Field corresponds to its field in a datatype v. It is parametrised by constructor phantom type and field value type.

data Key v :: * -> *

A unique identifier of a value stored in a database. This may be a primary key, a constraint or unique indices. The second parameter is the key description.

type AutoKey v

This type is the default autoincremented key for the entity. If entity does not have such key, AutoKey v = ().

type DefaultKey v

This type is the default key for the entity.

type IsSumType v

It is HFalse for entity with one constructor and HTrue for sum types.

Methods

entityDef :: DbDescriptor db => proxy db -> v -> EntityDef

Returns a complete description of the type

toEntityPersistValues :: PersistBackend m => v -> m ([PersistValue] -> [PersistValue])

Marshalls value to a list of PersistValue ready for insert to a database

fromEntityPersistValues :: PersistBackend m => [PersistValue] -> m (v, [PersistValue])

Constructs the value from the list of PersistValue

getUniques :: v -> (Int, [(String, [PersistValue] -> [PersistValue])])

Returns constructor number and a list of uniques names and corresponding field values

entityFieldChain :: DbDescriptor db => proxy db -> Field v c a -> FieldChain

Is internally used by FieldLike Field instance We could avoid this function if class FieldLike allowed FieldLike Fields Data or FieldLike (Fields Data). However that would require additional extensions in user-space code

data PersistValue

A raw value which can be stored in any backend and can be marshalled to and from a PersistField.

Constructors

PersistString String

PersistText Text

PersistByteString ByteString

PersistInt64 Int64

PersistDouble Double

PersistBool Bool

PersistDay Day

PersistTimeOfDay TimeOfDay

PersistUTCTime UTCTime

PersistZonedTime ZT

PersistNull

PersistCustom Utf8 [PersistValue]

Creating some datatypes may require calling a function, using a special constructor, or other syntax. The string (which can have placeholders) is included into query without escaping. The recursive constructions are not allowed, i.e., [PersistValue] cannot contain PersistCustom values.

Instances

Eq PersistValue

Methods

(==) :: PersistValue -> PersistValue -> Bool

(/=) :: PersistValue -> PersistValue -> Bool

Read PersistValue

Methods

readsPrec :: Int -> ReadS PersistValue

readList :: ReadS [PersistValue]

readPrec :: ReadPrec PersistValue

readListPrec :: ReadPrec [PersistValue]

Show PersistValue

Methods

showsPrec :: Int -> PersistValue -> ShowS

show :: PersistValue -> String

showList :: [PersistValue] -> ShowS

class PersistField a where

Represents everything which can be put into a database. This data can be stored in multiple columns and tables. To get value of those columns we might need to access another table. That is why the result type is monadic.

Minimal complete definition

persistName, toPersistValues, fromPersistValues, dbType

Methods

persistName :: a -> String

Return name of the type. If it is polymorphic, the names of parameter types are separated with delim symbol

toPersistValues :: PersistBackend m => a -> m ([PersistValue] -> [PersistValue])

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

fromPersistValues :: PersistBackend m => [PersistValue] -> m (a, [PersistValue])

Constructs a value from a PersistValue. For complex datatypes it may query the database

dbType :: DbDescriptor db => proxy db -> a -> DbType

Description of value type. It depends on database so that we can have, for example, xml column type in Postgres and varchar type in other databases

class PersistField a => SinglePersistField a where

Represents all datatypes that map into a single column. Getting value for that column might require monadic actions to access other tables.

Minimal complete definition

toSinglePersistValue, fromSinglePersistValue

Methods

toSinglePersistValue :: PersistBackend m => a -> m PersistValue

fromSinglePersistValue :: PersistBackend m => PersistValue -> m a

class PersistField a => PurePersistField a where

Represents all datatypes that map into several columns. Getting values for those columns is pure.

Minimal complete definition

toPurePersistValues, fromPurePersistValues

Methods

toPurePersistValues :: a -> [PersistValue] -> [PersistValue]

fromPurePersistValues :: [PersistValue] -> (a, [PersistValue])

class PersistField a => PrimitivePersistField a where

Datatypes which can be converted directly to PersistValue

Minimal complete definition

toPrimitivePersistValue, fromPrimitivePersistValue

Methods

toPrimitivePersistValue :: a -> PersistValue

fromPrimitivePersistValue :: PersistValue -> a

class PersistField v => Embedded v where

Minimal complete definition

selectorNum

Associated Types

data Selector v :: * -> *

Methods

selectorNum :: Selector v a -> Int

class Projection p a | p -> a where

Any data that can be fetched from a database

Minimal complete definition

projectionExprs, projectionResult

Associated Types

type ProjectionDb p db :: Constraint

type ProjectionRestriction p r :: Constraint

Methods

projectionExprs :: (DbDescriptor db, ProjectionDb p db, ProjectionRestriction p r) => p -> [UntypedExpr db r] -> [UntypedExpr db r]

It returns multiple expressions that can be transformed into values which can be selected. Difflist is used for concatenation efficiency.

projectionResult :: PersistBackend m => p -> [PersistValue] -> m (a, [PersistValue])

It is like fromPersistValues. However, we cannot use it for projections in all cases. For the PersistEntity instances fromPersistValues expects entity id instead of the entity values.

class (Projection p a, ProjectionDb p db, ProjectionRestriction p r) => Projection' p db r a

Instances

(Projection p a, ProjectionDb p db, ProjectionRestriction p r) => Projection' p db r a

data RestrictionHolder v c

Instances

type ProjectionRestriction (u (UniqueMarker v)) (RestrictionHolder v' c)

type ProjectionRestriction (u (UniqueMarker v)) (RestrictionHolder v' c) = (~) * v v'

data Unique u

A holder for Unique constraints

data KeyForBackend db v

It allows to store autogenerated keys of one database in another if they have different datatype.

Constructors

(DbDescriptor db, PersistEntity v) => KeyForBackend (AutoKeyType db)

data BackendSpecific

Key marked with this type can have value for any backend

data ConstructorMarker v a

A phantom datatype to make instance head different c (ConstructorMarker v)

Instances

type ProjectionDb (c (ConstructorMarker v)) db

type ProjectionDb (c (ConstructorMarker v)) db = ()

type ProjectionRestriction (c (ConstructorMarker v)) r

type ProjectionRestriction (c (ConstructorMarker v)) r = (~) * r (RestrictionHolder v c)

data UniqueMarker v a

A phantom datatype to make instance head different u (UniqueMarker v)

Instances

(PersistEntity v, DbDescriptor db, IsUniqueKey k, (~) * k (Key v (Unique u)), (~) * (RestrictionHolder v c) r') => Expression db r' (u (UniqueMarker v))

Methods

toExpr :: u (UniqueMarker v) -> UntypedExpr db r'

type ProjectionDb (u (UniqueMarker v)) db

type ProjectionDb (u (UniqueMarker v)) db = ()

type ProjectionRestriction (u (UniqueMarker v)) (RestrictionHolder v' c)

type ProjectionRestriction (u (UniqueMarker v)) (RestrictionHolder v' c) = (~) * v v'

data HFalse

data HTrue

newtype ZT

Avoid orphan instances.

Constructors

ZT ZonedTime

Instances

Eq ZT

Methods

(==) :: ZT -> ZT -> Bool

(/=) :: ZT -> ZT -> Bool

Ord ZT

Methods

compare :: ZT -> ZT -> Ordering

(<) :: ZT -> ZT -> Bool

(<=) :: ZT -> ZT -> Bool

(>) :: ZT -> ZT -> Bool

(>=) :: ZT -> ZT -> Bool

max :: ZT -> ZT -> ZT

min :: ZT -> ZT -> ZT

Read ZT

Methods

readsPrec :: Int -> ReadS ZT

readList :: ReadS [ZT]

readPrec :: ReadPrec ZT

readListPrec :: ReadPrec [ZT]

Show ZT

Methods

showsPrec :: Int -> ZT -> ShowS

show :: ZT -> String

showList :: [ZT] -> ShowS

newtype Utf8

Datatype for incremental building SQL queries

Constructors

Utf8 Builder

Instances

Eq Utf8

Methods

(==) :: Utf8 -> Utf8 -> Bool

(/=) :: Utf8 -> Utf8 -> Bool

Read Utf8

Methods

readsPrec :: Int -> ReadS Utf8

readList :: ReadS [Utf8]

readPrec :: ReadPrec Utf8

readListPrec :: ReadPrec [Utf8]

Show Utf8

Methods

showsPrec :: Int -> Utf8 -> ShowS

show :: Utf8 -> String

showList :: [Utf8] -> ShowS

StringLike Utf8

Methods

fromChar :: Char -> Utf8

fromUtf8 :: Utf8 -> ByteString

delim :: Char

Constructing expressions

data Cond db r

Represents condition for a query.

Constructors

And (Cond db r) (Cond db r)

Or (Cond db r) (Cond db r)

Not (Cond db r)

Compare ExprRelation (UntypedExpr db r) (UntypedExpr db r)

CondRaw (QueryRaw db r)

CondEmpty

Instances

((~) * db' db, (~) * r' r) => Expression db' r' (Cond db r)

Methods

toExpr :: Cond db r -> UntypedExpr db' r'

(~) * db' db => HasSelectOptions (Cond db r) db' r

Associated Types

type HasLimit (Cond db r) :: *

type HasOffset (Cond db r) :: *

type HasOrder (Cond db r) :: *

type HasDistinct (Cond db r) :: *

Methods

getSelectOptions :: Cond db r -> SelectOptions db' r (HasLimit (Cond db r)) (HasOffset (Cond db r)) (HasOrder (Cond db r)) (HasDistinct (Cond db r))

type HasLimit (Cond db r)

type HasLimit (Cond db r) = HFalse

type HasOffset (Cond db r)

type HasOffset (Cond db r) = HFalse

type HasOrder (Cond db r)

type HasOrder (Cond db r) = HFalse

type HasDistinct (Cond db r)

type HasDistinct (Cond db r) = HFalse

type ProjectionDb (Cond db r) db'

type ProjectionDb (Cond db r) db' = (~) * db db'

type ProjectionRestriction (Cond db r) r'

type ProjectionRestriction (Cond db r) r' = (~) * r r'

data ExprRelation

Constructors

Eq

Ne

Gt

Lt

Ge

Le

Instances

Show ExprRelation

Methods

showsPrec :: Int -> ExprRelation -> ShowS

show :: ExprRelation -> String

showList :: [ExprRelation] -> ShowS

data Update db r

Constructors

(Assignable f a, Projection' f db r a) => Update f (UntypedExpr db r)

(~>) :: (EntityConstr v c, FieldLike f a, DbDescriptor db, Projection' f db (RestrictionHolder v c) a, Embedded a) => f -> Selector a a' -> SubField db v c a' infixl 5

Accesses fields of the embedded datatypes. For example, SomeField ==. ("abc", "def") ||. SomeField ~> Tuple2_0Selector ==. "def"

class Assignable f a => FieldLike f a | f -> a where

This subset of Assignable is for plain database fields.

Minimal complete definition

fieldChain

Methods

fieldChain :: (DbDescriptor db, ProjectionDb f db) => proxy db -> f -> FieldChain

class Projection f a => Assignable f a | f -> a

This subset of Projection instances is for things that behave like fields. Namely, they can occur in condition expressions (for example, Field and SubField) and on the left side of update statements. For example "lower(field)" is a valid Projection, but not Field like because it cannot be on the left side. Datatypes that index PostgreSQL arrays "arr[5]" or access composites "(comp).subfield" are valid instances of Assignable.

newtype SubField db v c a

Constructors

SubField FieldChain

Instances

(EntityConstr v c, DbDescriptor db, PersistField a, (~) * db' db, (~) * (RestrictionHolder v c) r') => Expression db' r' (SubField db v c a)

Methods

toExpr :: SubField db v c a -> UntypedExpr db' r'

type ProjectionDb (SubField db v c a) db'

type ProjectionDb (SubField db v c a) db' = (~) * db db'

type ProjectionRestriction (SubField db v c a) r

type ProjectionRestriction (SubField db v c a) r = (~) * r (RestrictionHolder v c)

data AutoKeyField v c where

It can be used in expressions like a regular field. For example, delete (AutoKeyField ==. k) or delete (AutoKeyField ==. k ||. SomeField ==. "DUPLICATE")

Constructors

AutoKeyField :: AutoKeyField v c

Instances

(EntityConstr v c, DbDescriptor db, (~) * (RestrictionHolder v c) r') => Expression db r' (AutoKeyField v c)

Methods

toExpr :: AutoKeyField v c -> UntypedExpr db r'

type ProjectionDb (AutoKeyField v c) db

type ProjectionDb (AutoKeyField v c) db = ()

type ProjectionRestriction (AutoKeyField v c) r

type ProjectionRestriction (AutoKeyField v c) r = (~) * r (RestrictionHolder v c)

type FieldChain = ((String, DbType), [(String, EmbeddedDef)])

It is used to map field to column names. It can be either a column name for a regular field of non-embedded type or a list of this field and the outer fields in reverse order. Eg, fieldChain $ SomeField ~> Tuple2_0Selector may result in [("val0", DbString), ("some", DbEmbedded False [dbType "", dbType True])].

class NeverNull a

Types which are never NULL when converted to PersistValue. 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.

data UntypedExpr db r where

Used to uniformly represent fields, constants and more complex things, e.g., arithmetic expressions. A value should be converted to UntypedExpr for usage in expressions

Constructors

ExprRaw :: QueryRaw db r -> UntypedExpr db r

ExprField :: FieldChain -> UntypedExpr db r

ExprPure :: forall db r a. PurePersistField a => a -> UntypedExpr db r

ExprCond :: Cond db r -> UntypedExpr db r

newtype Expr db r a

Expr with phantom type helps to keep type safety in complex expressions

Constructors

Expr (UntypedExpr db r)

Instances

(PersistField a, (~) * db' db, (~) * r' r) => Expression db' r' (Expr db r a)

Methods

toExpr :: Expr db r a -> UntypedExpr db' r'

Eq (Expr db r a)

Methods

(==) :: Expr db r a -> Expr db r a -> Bool

(/=) :: Expr db r a -> Expr db r a -> Bool

Show (Expr db r a)

Methods

showsPrec :: Int -> Expr db r a -> ShowS

show :: Expr db r a -> String

showList :: [Expr db r a] -> ShowS

type ProjectionDb (Expr db r a) db'

type ProjectionDb (Expr db r a) db' = (~) * db db'

type ProjectionRestriction (Expr db r a) r'

type ProjectionRestriction (Expr db r a) r' = (~) * r r'

data Order db r

Defines sort order of a result-set

Constructors

Projection' f db r a => Asc f

Projection' f db r a => Desc f

class HasSelectOptions a db r | a -> db r where

This class helps to check that limit, offset, or order clauses are added to condition only once.

Minimal complete definition

getSelectOptions

Associated Types

type HasLimit a

type HasOffset a

type HasOrder a

type HasDistinct a

Methods

getSelectOptions :: a -> SelectOptions db r (HasLimit a) (HasOffset a) (HasOrder a) (HasDistinct a)

Instances

(~) * db' db => HasSelectOptions (Cond db r) db' r

Associated Types

type HasLimit (Cond db r) :: *

type HasOffset (Cond db r) :: *

type HasOrder (Cond db r) :: *

type HasDistinct (Cond db r) :: *

Methods

getSelectOptions :: Cond db r -> SelectOptions db' r (HasLimit (Cond db r)) (HasOffset (Cond db r)) (HasOrder (Cond db r)) (HasDistinct (Cond db r))

(~) * db' db => HasSelectOptions (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) db' r

Associated Types

type HasLimit (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

type HasOffset (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

type HasOrder (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

type HasDistinct (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

Methods

getSelectOptions :: SelectOptions db r hasLimit hasOffset hasOrder hasDistinct -> SelectOptions db' r (HasLimit (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)) (HasOffset (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)) (HasOrder (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)) (HasDistinct (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct))

data SelectOptions db r hasLimit hasOffset hasOrder hasDistinct

Constructors

SelectOptions

Fields

• condOptions :: Cond db r
• limitOptions :: Maybe Int
• offsetOptions :: Maybe Int
• orderOptions :: [Order db r]

  False - no DISTINCT, True - DISTINCT

• distinctOptions :: Bool

  The name of the option and part of the SQL which will be put later

• dbSpecificOptions :: [(String, QueryRaw db r)]

Instances

(~) * db' db => HasSelectOptions (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) db' r

Associated Types

type HasLimit (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

type HasOffset (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

type HasOrder (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

type HasDistinct (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) :: *

Methods

getSelectOptions :: SelectOptions db r hasLimit hasOffset hasOrder hasDistinct -> SelectOptions db' r (HasLimit (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)) (HasOffset (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)) (HasOrder (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)) (HasDistinct (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct))

type HasLimit (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)

type HasLimit (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) = hasLimit

type HasOffset (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)

type HasOffset (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) = hasOffset

type HasOrder (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)

type HasOrder (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) = hasOrder

type HasDistinct (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct)

type HasDistinct (SelectOptions db r hasLimit hasOffset hasOrder hasDistinct) = hasDistinct

limitTo :: (HasSelectOptions a db r, HasLimit a ~ HFalse) => a -> Int -> SelectOptions db r HTrue (HasOffset a) (HasOrder a) (HasDistinct a)

offsetBy :: (HasSelectOptions a db r, HasOffset a ~ HFalse) => a -> Int -> SelectOptions db r (HasLimit a) HTrue (HasOrder a) (HasDistinct a)

orderBy :: (HasSelectOptions a db r, HasOrder a ~ HFalse) => a -> [Order db r] -> SelectOptions db r (HasLimit a) (HasOffset a) HTrue (HasDistinct a)

distinct :: (HasSelectOptions a db r, HasDistinct a ~ HFalse) => a -> SelectOptions db r (HasLimit a) (HasOffset a) (HasOrder a) HTrue

Select DISTINCT rows. select $ distinct CondEmpty

Type description

These types describe the mapping between database schema and datatype. They hold table names, columns, constraints, etc. Some types below are parameterized by string type str and dbType. This is done to make them promotable to kind level.

data DbTypePrimitive' str

A DB data type. Naming attempts to reflect the underlying Haskell datatypes, eg DbString instead of DbVarchar. Different databases may have different representations for these types.

Constructors

DbString

DbInt32

DbInt64

DbReal

DbBool

DbDay

DbTime

DbDayTime

DbDayTimeZoned

DbBlob

ByteString

DbOther (OtherTypeDef' str)

Instances

Eq str => Eq (DbTypePrimitive' str)

Methods

(==) :: DbTypePrimitive' str -> DbTypePrimitive' str -> Bool

(/=) :: DbTypePrimitive' str -> DbTypePrimitive' str -> Bool

Show str => Show (DbTypePrimitive' str)

Methods

showsPrec :: Int -> DbTypePrimitive' str -> ShowS

show :: DbTypePrimitive' str -> String

showList :: [DbTypePrimitive' str] -> ShowS

type DbTypePrimitive = DbTypePrimitive' String

data DbType

Constructors

DbTypePrimitive DbTypePrimitive Bool (Maybe String) (Maybe ParentTableReference)

type, nullable, default value, reference

DbEmbedded EmbeddedDef (Maybe ParentTableReference)

DbList String DbType

List table name and type of its argument

Instances

Eq DbType

Methods

(==) :: DbType -> DbType -> Bool

(/=) :: DbType -> DbType -> Bool

Show DbType

Methods

showsPrec :: Int -> DbType -> ShowS

show :: DbType -> String

showList :: [DbType] -> ShowS

data EntityDef' str dbType

Describes an ADT.

Constructors

EntityDef

Fields

• entityName :: str

  Entity name. entityName (entityDef v) == persistName v

• entitySchema :: Maybe str

  Database schema for the entity table and tables of its constructors

• typeParams :: [dbType]

  Named types of the instantiated polymorphic type parameters

• constructors :: [ConstructorDef' str dbType]

  List of entity constructors definitions

Instances

(Eq dbType, Eq str) => Eq (EntityDef' str dbType)

Methods

(==) :: EntityDef' str dbType -> EntityDef' str dbType -> Bool

(/=) :: EntityDef' str dbType -> EntityDef' str dbType -> Bool

(Show dbType, Show str) => Show (EntityDef' str dbType)

Methods

showsPrec :: Int -> EntityDef' str dbType -> ShowS

show :: EntityDef' str dbType -> String

showList :: [EntityDef' str dbType] -> ShowS

type EntityDef = EntityDef' String DbType

data EmbeddedDef' str dbType

The first argument is a flag which defines if the field names should be concatenated with the outer field name (False) or used as is which provides full control over table column names (True). Value False should be the default value so that a datatype can be embedded without name conflict concern. The second argument list of field names and field types.

Constructors

EmbeddedDef Bool [(str, dbType)]

Instances

(Eq dbType, Eq str) => Eq (EmbeddedDef' str dbType)

Methods

(==) :: EmbeddedDef' str dbType -> EmbeddedDef' str dbType -> Bool

(/=) :: EmbeddedDef' str dbType -> EmbeddedDef' str dbType -> Bool

(Show dbType, Show str) => Show (EmbeddedDef' str dbType)

Methods

showsPrec :: Int -> EmbeddedDef' str dbType -> ShowS

show :: EmbeddedDef' str dbType -> String

showList :: [EmbeddedDef' str dbType] -> ShowS

type EmbeddedDef = EmbeddedDef' String DbType

newtype OtherTypeDef' str

Stores a database type. The list contains two kinds of tokens for the type string. Backend will choose a string representation for DbTypePrimitive's, and the string literals will go to the type as-is. As the final step, these tokens are concatenated. For example, [Left "varchar(50)"] will become a string with max length and [Right DbInt64, Left "[]"] will become integer[] in PostgreSQL.

Constructors

OtherTypeDef [Either str (DbTypePrimitive' str)]

Instances

Eq str => Eq (OtherTypeDef' str)

Methods

(==) :: OtherTypeDef' str -> OtherTypeDef' str -> Bool

(/=) :: OtherTypeDef' str -> OtherTypeDef' str -> Bool

Show str => Show (OtherTypeDef' str)

Methods

showsPrec :: Int -> OtherTypeDef' str -> ShowS

show :: OtherTypeDef' str -> String

showList :: [OtherTypeDef' str] -> ShowS

type OtherTypeDef = OtherTypeDef' String

data ConstructorDef' str dbType

Describes an entity constructor

Constructors

ConstructorDef

Fields

• constrName :: str

  Constructor name

• constrAutoKeyName :: Maybe str

  Autokey name if any

• constrParams :: [(str, dbType)]

  Parameter names with their named type

• constrUniques :: [UniqueDef' str (Either (str, dbType) str)]

  Uniqueness constraints on the constructor fiels

Instances

(Eq dbType, Eq str) => Eq (ConstructorDef' str dbType)

Methods

(==) :: ConstructorDef' str dbType -> ConstructorDef' str dbType -> Bool

(/=) :: ConstructorDef' str dbType -> ConstructorDef' str dbType -> Bool

(Show dbType, Show str) => Show (ConstructorDef' str dbType)

Methods

showsPrec :: Int -> ConstructorDef' str dbType -> ShowS

show :: ConstructorDef' str dbType -> String

showList :: [ConstructorDef' str dbType] -> ShowS

type ConstructorDef = ConstructorDef' String DbType

class Constructor c where

Phantom constructors are made instances of this class. This class should be used only by Template Haskell codegen

Minimal complete definition

phantomConstrNum

Methods

phantomConstrNum :: c (a :: * -> *) -> Int

Returns constructor index which can be used to get ConstructorDef from EntityDef

class PersistEntity v => EntityConstr v c where

This class helps type inference in cases when query does not contain any fields which define the constructor, but the entity has only one. For example, in select $ AutoKeyField ==. k the condition would need type annotation with constructor name only if we select a sum type.

Minimal complete definition

entityConstrNum

Methods

entityConstrNum :: proxy v -> c (a :: * -> *) -> Int

class PurePersistField uKey => IsUniqueKey uKey where

Minimal complete definition

extractUnique, uniqueNum

Methods

extractUnique :: uKey ~ Key v u => v -> uKey

Creates value of unique key using the data extracted from the passed value

uniqueNum :: uKey -> Int

Ordinal number of the unique constraint in the list returned by constrUniques

data UniqueDef' str field

Unique name and list of the fields that form a unique combination. The fields are parametrized to reuse this datatype both with field and DbType and with column name

Constructors

UniqueDef

Fields

• uniqueDefName :: Maybe str
• uniqueDefType :: UniqueType
• uniqueDefFields :: [field]

Instances

(Eq field, Eq str) => Eq (UniqueDef' str field)

Methods

(==) :: UniqueDef' str field -> UniqueDef' str field -> Bool

(/=) :: UniqueDef' str field -> UniqueDef' str field -> Bool

(Show field, Show str) => Show (UniqueDef' str field)

Methods

showsPrec :: Int -> UniqueDef' str field -> ShowS

show :: UniqueDef' str field -> String

showList :: [UniqueDef' str field] -> ShowS

type UniqueDef = UniqueDef' String (Either (String, DbType) String)

Field is either a pair of entity field name and its type or an expression which will be used in query as-is.

data UniqueType

Defines how to treat the unique set of fields for a datatype

Constructors

UniqueConstraint

UniqueIndex

UniquePrimary Bool

is autoincremented

Instances

Eq UniqueType

Methods

(==) :: UniqueType -> UniqueType -> Bool

(/=) :: UniqueType -> UniqueType -> Bool

Ord UniqueType

Methods

compare :: UniqueType -> UniqueType -> Ordering

(<) :: UniqueType -> UniqueType -> Bool

(<=) :: UniqueType -> UniqueType -> Bool

(>) :: UniqueType -> UniqueType -> Bool

(>=) :: UniqueType -> UniqueType -> Bool

max :: UniqueType -> UniqueType -> UniqueType

min :: UniqueType -> UniqueType -> UniqueType

Show UniqueType

Methods

showsPrec :: Int -> UniqueType -> ShowS

show :: UniqueType -> String

showList :: [UniqueType] -> ShowS

data ReferenceActionType

Constructors

NoAction

Restrict

Cascade

SetNull

SetDefault

Instances

Eq ReferenceActionType

Methods

(==) :: ReferenceActionType -> ReferenceActionType -> Bool

(/=) :: ReferenceActionType -> ReferenceActionType -> Bool

Show ReferenceActionType

Methods

showsPrec :: Int -> ReferenceActionType -> ShowS

show :: ReferenceActionType -> String

showList :: [ReferenceActionType] -> ShowS

type ParentTableReference = (Either (EntityDef, Maybe String) ((Maybe String, String), [String]), Maybe ReferenceActionType, Maybe ReferenceActionType)

The reference contains either EntityDef of the parent table and name of the unique constraint. Or for tables not mapped by Groundhog schema name, table name, and list of columns Reference to the autogenerated key of a mapped entity = (Left (entityDef, Nothing), onDelete, onUpdate) Reference to a unique key of a mapped entity = (Left (entityDef, Just uniqueKeyName), onDelete, onUpdate) Reference to a table that is not mapped = (Right ((schema, tableName), columns), onDelete, onUpdate)

Migration

type SingleMigration = Either [String] [(Bool, Int, String)]

Either error messages or migration queries with safety flag and execution order

type NamedMigrations = Map String SingleMigration

Datatype names and corresponding migrations

type Migration m = StateT NamedMigrations m ()

Database

class (Monad m, Applicative m, Functor m, MonadIO m, ConnectionManager (Conn m), PersistBackendConn (Conn m)) => PersistBackend m where

This class helps to shorten the type signatures of user monadic code. If your monad has several connections, e.g., for main and audit databases, create run*Db function runAuditDb :: Action conn a -> m a

Minimal complete definition

getConnection

Associated Types

type Conn m

Methods

getConnection :: m (Conn m)

Instances

(Monad m, Applicative m, Functor m, MonadIO m, PersistBackendConn conn) => PersistBackend (ReaderT * conn m)

Associated Types

type Conn (ReaderT * conn m :: * -> *) :: *

Methods

getConnection :: ReaderT * conn m (Conn (ReaderT * conn m))

class (DbDescriptor conn, ConnectionManager conn) => PersistBackendConn conn where

Minimal complete definition

insert, insert_, insertBy, insertByAll, replace, replaceBy, select, selectStream, selectAll, selectAllStream, get, getBy, update, delete, deleteBy, deleteAll, count, countAll, project, projectStream, migrate, executeRaw, queryRaw, insertList, getList

Methods

insert :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => v -> m (AutoKey v)

Insert a new record to a database and return its autogenerated key or ()

insert_ :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => v -> m ()

Insert a new record to a database. For some backends it may be faster than insert.

insertBy :: (PersistEntity v, IsUniqueKey (Key v (Unique u)), PersistBackend m, Conn m ~ conn) => u (UniqueMarker v) -> v -> m (Either (AutoKey v) (AutoKey v))

Try to insert a record and return Right newkey. If there is a constraint violation for the given constraint, Left oldkey is returned , where oldkey is an identifier of the record with the matching values.

insertByAll :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => v -> m (Either (AutoKey v) (AutoKey v))

Try to insert a record and return Right newkey. If there is a constraint violation for any constraint, Left oldkey is returned , where oldkey is an identifier of the record with the matching values. Note that if several constraints are violated, a key of an arbitrary matching record is returned.

replace :: (PersistEntity v, PrimitivePersistField (Key v BackendSpecific), PersistBackend m, Conn m ~ conn) => Key v BackendSpecific -> v -> m ()

Replace a record with the given autogenerated key. Result is undefined if the record does not exist.

replaceBy :: (PersistEntity v, IsUniqueKey (Key v (Unique u)), PersistBackend m, Conn m ~ conn) => u (UniqueMarker v) -> v -> m ()

Replace a record. The unique key marker defines what unique key of the entity is used.

select :: (PersistEntity v, EntityConstr v c, HasSelectOptions opts conn (RestrictionHolder v c), PersistBackend m, Conn m ~ conn) => opts -> m [v]

Return a list of the records satisfying the condition. Example: select $ (FirstField ==. "abc" &&. SecondField >. "def") `orderBy` [Asc ThirdField] `limitTo` 100

selectStream :: (PersistEntity v, EntityConstr v c, HasSelectOptions opts conn (RestrictionHolder v c), PersistBackend m, Conn m ~ conn) => opts -> m (RowStream v)

Return a list of the records satisfying the condition. Example: select $ (FirstField ==. "abc" &&. SecondField >. "def") `orderBy` [Asc ThirdField] `limitTo` 100

selectAll :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => m [(AutoKey v, v)]

Return a list of all records. Order is undefined. It can be useful for datatypes with multiple constructors.

selectAllStream :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => m (RowStream (AutoKey v, v))

Return a list of all records. Order is undefined. It can be useful for datatypes with multiple constructors.

get :: (PersistEntity v, PrimitivePersistField (Key v BackendSpecific), PersistBackend m, Conn m ~ conn) => Key v BackendSpecific -> m (Maybe v)

Fetch an entity from a database

getBy :: (PersistEntity v, IsUniqueKey (Key v (Unique u)), PersistBackend m, Conn m ~ conn) => Key v (Unique u) -> m (Maybe v)

Fetch an entity from a database by its unique key

update :: (PersistEntity v, EntityConstr v c, PersistBackend m, Conn m ~ conn) => [Update conn (RestrictionHolder v c)] -> Cond conn (RestrictionHolder v c) -> m ()

Update the records satisfying the condition. Example: update [FirstField =. "abc"] $ FirstField ==. "def"

delete :: (PersistEntity v, EntityConstr v c, PersistBackend m, Conn m ~ conn) => Cond conn (RestrictionHolder v c) -> m ()

Remove the records satisfying the condition

deleteBy :: (PersistEntity v, PrimitivePersistField (Key v BackendSpecific), PersistBackend m, Conn m ~ conn) => Key v BackendSpecific -> m ()

Remove the record with given key. No-op if the record does not exist

deleteAll :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => v -> m ()

Remove all records. The entity parameter is used only for type inference.

count :: (PersistEntity v, EntityConstr v c, PersistBackend m, Conn m ~ conn) => Cond conn (RestrictionHolder v c) -> m Int

Count total number of records satisfying the condition

countAll :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => v -> m Int

Count total number of records with all constructors. The entity parameter is used only for type inference

project :: (PersistEntity v, EntityConstr v c, Projection' p conn (RestrictionHolder v c) a, HasSelectOptions opts conn (RestrictionHolder v c), PersistBackend m, Conn m ~ conn) => p -> opts -> m [a]

Fetch projection of some fields. Example: project (SecondField, ThirdField) $ (FirstField ==. "abc" &&. SecondField >. "def") `orderBy` [Asc ThirdField] `offsetBy` 100

projectStream :: (PersistEntity v, EntityConstr v c, Projection' p conn (RestrictionHolder v c) a, HasSelectOptions opts conn (RestrictionHolder v c), PersistBackend m, Conn m ~ conn) => p -> opts -> m (RowStream a)

migrate :: (PersistEntity v, PersistBackend m, Conn m ~ conn) => v -> Migration m

Check database schema and create migrations for the entity and the entities it contains

executeRaw :: (PersistBackend m, Conn m ~ conn) => Bool -> String -> [PersistValue] -> m ()

Execute raw query

queryRaw :: (PersistBackend m, Conn m ~ conn) => Bool -> String -> [PersistValue] -> m (RowStream [PersistValue])

Execute raw query with results

insertList :: (PersistField a, PersistBackend m, Conn m ~ conn) => [a] -> m Int64

getList :: (PersistField a, PersistBackend m, Conn m ~ conn) => Int64 -> m [a]

type Action conn = ReaderT conn IO

type RowStream a = Acquire (IO (Maybe a))

class PrimitivePersistField (AutoKeyType db) => DbDescriptor db where

Minimal complete definition

backendName

Associated Types

type AutoKeyType db

Type of the database default autoincremented key. For example, Sqlite has Int64

type QueryRaw db :: * -> *

Value of this type can be used as a part of a query. For example, it can be RenderS for relational databases, or BSON for MongoDB.

Methods

backendName :: proxy db -> String

Name of backend

type DbPersist = ReaderT

Deprecated: Use PersistBackend constraint instead. If you need to specify a backend, add (PersistBackend m, Conn m ~ Postgresql)

runDbPersist :: Monad m => DbPersist conn m a -> conn -> m a

Deprecated: Use PersistBackend constraint instead. If you need to specify a backend, add (PersistBackend m, Conn m ~ Postgresql)

Connections and transactions

class ExtractConnection cm conn | cm -> conn where

Minimal complete definition

extractConn

Methods

extractConn :: (MonadBaseControl IO m, MonadIO m) => (conn -> m a) -> cm -> m a

Extracts the connection. The connection manager can be a pool or the connection itself

class ConnectionManager conn where

Connection manager provides connection to the passed function handles transations. Manager can be a connection itself, a pool, Snaplet in Snap, foundation datatype in Yesod, etc.

Minimal complete definition

withConn

Methods

withConn :: (MonadBaseControl IO m, MonadIO m) => (conn -> m a) -> conn -> m a

Opens the transaction.

class Savepoint conn where

Minimal complete definition

withConnSavepoint

Methods

withConnSavepoint :: (MonadBaseControl IO m, MonadIO m) => String -> m a -> conn -> m a

Wraps the passed action into a named savepoint

withSavepoint :: (PersistBackend m, MonadBaseControl IO m, MonadIO m, Savepoint (Conn m)) => String -> m a -> m a

It helps to run withConnSavepoint within a monad. Make sure that transaction is open

runDb :: PersistBackend m => Action (Conn m) a -> m a

It helps to run database operations within an application monad.

runDbConn :: (MonadIO m, MonadBaseControl IO m, ConnectionManager conn, ExtractConnection cm conn) => Action conn a -> cm -> m a

Runs action within connection. It can handle a simple connection, a pool of them, etc.

runDb' :: PersistBackend m => Action (Conn m) a -> m a

It helps to run database operations within an application monad. Unlike runDb it does not wrap action in transaction

runDbConn' :: (MonadIO m, MonadBaseControl IO m, ConnectionManager conn, ExtractConnection cm conn) => Action conn a -> cm -> m a

It is similar to runDbConn but runs action without transaction.

flip withConn conn $ \conn -> liftIO $ do
  -- transaction is already opened by withConn at this point
  someIOAction
  runDbConn' (insert_ value) conn