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

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 :: DbDescriptor db => proxy db -> 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

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

Read PersistValue

Show PersistValue

ToJSON PersistValue

FromJSON PersistValue

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.

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

Instances

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 ()

PersistField ByteString

PersistField ByteString

PersistField Text

PersistField UTCTime

PersistField ZonedTime

PersistField TimeOfDay

PersistField Day

PersistField a => PersistField [a]

(PersistField a, NeverNull a) => PersistField (Maybe a)

(PersistField a, PersistField b) => PersistField (a, b)

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

(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)

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.

Methods

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

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

Instances

PrimitivePersistField a => SinglePersistField a

class PersistField a => PurePersistField a where

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

Methods

toPurePersistValues :: DbDescriptor db => proxy db -> a -> [PersistValue] -> [PersistValue]

fromPurePersistValues :: DbDescriptor db => proxy db -> [PersistValue] -> (a, [PersistValue])

Instances

PurePersistField ()

PrimitivePersistField a => PurePersistField a

(PurePersistField a, PurePersistField b) => PurePersistField (a, b)

(PurePersistField a, PurePersistField b, PurePersistField c) => PurePersistField (a, b, c)

(PurePersistField a, PurePersistField b, PurePersistField c, PurePersistField d) => PurePersistField (a, b, c, d)

(PurePersistField a, PurePersistField b, PurePersistField c, PurePersistField d, PurePersistField e) => PurePersistField (a, b, c, d, e)

class PersistField a => PrimitivePersistField a where

Datatypes which can be converted directly to PersistValue. The no-value parameter DbDescriptor db => proxy db allows conversion depend the database details while keeping it pure. A type which has an instance of PrimitivePersistField should be an instance of superclasses SinglePersistField and PurePersistField as well.

Methods

toPrimitivePersistValue :: DbDescriptor db => proxy db -> a -> PersistValue

fromPrimitivePersistValue :: DbDescriptor db => proxy db -> PersistValue -> a

Instances

PrimitivePersistField Bool

PrimitivePersistField Double

PrimitivePersistField Int

PrimitivePersistField Int8

PrimitivePersistField Int16

PrimitivePersistField Int32

PrimitivePersistField Int64

PrimitivePersistField Word8

PrimitivePersistField Word16

PrimitivePersistField Word32

PrimitivePersistField Word64

PrimitivePersistField String

PrimitivePersistField ByteString

PrimitivePersistField ByteString

PrimitivePersistField Text

PrimitivePersistField UTCTime

PrimitivePersistField ZonedTime

PrimitivePersistField TimeOfDay

PrimitivePersistField Day

(PrimitivePersistField a, NeverNull a) => PrimitivePersistField (Maybe a)

(DbDescriptor db, PersistEntity v, PersistField v) => PrimitivePersistField (KeyForBackend db v)

class PersistField v => Embedded v where

Associated Types

data Selector v :: * -> *

Methods

selectorNum :: Selector v a -> Int

Instances

(PersistField a', PersistField b') => Embedded (a', b')

(PersistField a', PersistField b', PersistField c') => Embedded (a', b', c')

(PersistField a', PersistField b', PersistField c', PersistField d') => Embedded (a', b', c', d')

(PersistField a', PersistField b', PersistField c', PersistField d', PersistField e') => Embedded (a', b', c', d', e')

class Projection p a | p -> a where

Any data that can be fetched from a database

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.

Instances

(PersistEntity v, IsUniqueKey k, (~) * k (Key v (Unique u))) => Projection (u (UniqueMarker v)) k

EntityConstr v c => Projection (c (ConstructorMarker v)) v

(EntityConstr v c, (~) * a (AutoKey v)) => Projection (AutoKeyField v c) a

(~) * a Bool => Projection (Cond db r) a

(Projection a1 a1', Projection a2 a2') => Projection (a1, a2) (a1', a2')

PersistField a => Projection (Expr db r a) a

(EntityConstr v c, PersistField a) => Projection (Field v c a) a

(Projection a1 a1', Projection a2 a2', Projection a3 a3') => Projection (a1, a2, a3) (a1', a2', a3')

(EntityConstr v c, PersistField a) => Projection (SubField db v c a) a

(Projection a1 a1', Projection a2 a2', Projection a3 a3', Projection a4 a4') => Projection (a1, a2, a3, a4) (a1', a2', a3', a4')

(Projection a1 a1', Projection a2 a2', Projection a3 a3', Projection a4 a4', Projection a5 a5') => Projection (a1, a2, a3, a4, a5) (a1', a2', a3', a4', a5')

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) = (~) * 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)

Instances

(DbDescriptor db, PersistEntity v, PersistField v) => PrimitivePersistField (KeyForBackend db v)

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

NeverNull (KeyForBackend db v)

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

EntityConstr v c => Projection (c (ConstructorMarker v)) v

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

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))

(PersistEntity v, IsUniqueKey k, (~) * k (Key v (Unique u))) => FieldLike (u (UniqueMarker v)) k

(PersistEntity v, IsUniqueKey k, (~) * k (Key v (Unique u))) => Assignable (u (UniqueMarker v)) k

(PersistEntity v, IsUniqueKey k, (~) * k (Key v (Unique u))) => Projection (u (UniqueMarker v)) k

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

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

Ord ZT

Read ZT

Show ZT

newtype Utf8

Datatype for incremental building SQL queries

Constructors

Utf8 Builder

Instances

Eq Utf8

Read Utf8

Show Utf8

IsString Utf8

Monoid Utf8

StringLike 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)

(~) * a Bool => Projection (Cond db r) a

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

type HasLimit (Cond db r) = HFalse

type HasOffset (Cond db r) = HFalse

type HasOrder (Cond db r) = HFalse

type HasDistinct (Cond db r) = HFalse

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

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

data ExprRelation

Constructors

Eq

Ne

Gt

Lt

Ge

Le

Instances

Show ExprRelation

data Update db r

Constructors

forall f a . (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.

Methods

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

Instances

(PersistEntity v, IsUniqueKey k, (~) * k (Key v (Unique u))) => FieldLike (u (UniqueMarker v)) k

(EntityConstr v c, (~) * a (AutoKey v)) => FieldLike (AutoKeyField v c) a

(EntityConstr v c, PersistField a) => FieldLike (Field v c a) a

(EntityConstr v c, PersistField a) => FieldLike (SubField db v c a) a

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.

Instances

(PersistEntity v, IsUniqueKey k, (~) * k (Key v (Unique u))) => Assignable (u (UniqueMarker v)) k

(EntityConstr v c, (~) * a (AutoKey v)) => Assignable (AutoKeyField v c) a

(EntityConstr v c, PersistField a) => Assignable (Field v c a) a

(EntityConstr v c, PersistField a) => Assignable (SubField db v c a) a

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)

(EntityConstr v c, PersistField a) => FieldLike (SubField db v c a) a

(EntityConstr v c, PersistField a) => Assignable (SubField db v c a) a

(EntityConstr v c, PersistField a) => Projection (SubField db v c a) a

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

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)

(EntityConstr v c, (~) * a (AutoKey v)) => FieldLike (AutoKeyField v c) a

(EntityConstr v c, (~) * a (AutoKey v)) => Assignable (AutoKeyField v c) a

(EntityConstr v c, (~) * a (AutoKey v)) => Projection (AutoKeyField v c) a

type ProjectionDb (AutoKeyField v c) db = ()

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.

Instances

NeverNull Bool

NeverNull Double

NeverNull Int

NeverNull Int8

NeverNull Int16

NeverNull Int32

NeverNull Int64

NeverNull Word8

NeverNull Word16

NeverNull Word32

NeverNull Word64

NeverNull String

NeverNull ByteString

NeverNull ByteString

NeverNull Text

NeverNull UTCTime

NeverNull ZonedTime

NeverNull TimeOfDay

NeverNull Day

NeverNull (KeyForBackend db v)

PrimitivePersistField (Key v u) => NeverNull (Key v u)

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)

(SqlDb db, PersistField a, Enum a) => Enum (Expr db r a)

Eq (Expr db r a)

(FloatingSqlDb db, PersistField a, Floating a) => Floating (Expr db r a)

(SqlDb db, PersistField a, Fractional a) => Fractional (Expr db r a)

(SqlDb db, PurePersistField a, Integral a) => Integral (Expr db r a)

(SqlDb db, PersistField a, Num a) => Num (Expr db r a)

(SqlDb db, PersistField a, Ord a) => Ord (Expr db r a)

(SqlDb db, PersistField a, Real a) => Real (Expr db r a)

Show (Expr db r a)

PersistField a => Projection (Expr db r a) a

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

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

data Order db r

Defines sort order of a result-set

Constructors

forall a f . Projection' f db r a => Asc f

forall a 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.

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

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

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

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

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

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

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)

Show str => Show (DbTypePrimitive' str)

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

Show DbType

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 str, Eq dbType) => Eq (EntityDef' str dbType)

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

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 str, Eq dbType) => Eq (EmbeddedDef' str dbType)

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

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)

Show str => Show (OtherTypeDef' str)

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 str, Eq dbType) => Eq (ConstructorDef' str dbType)

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

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

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.

Methods

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

Instances

(PersistEntity v, EntityConstr' (IsSumType v) c) => EntityConstr v c

class PurePersistField uKey => IsUniqueKey uKey where

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 str, Eq field) => Eq (UniqueDef' str field)

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

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

Ord UniqueType

Show UniqueType

data ReferenceActionType

Constructors

NoAction

Restrict

Cascade

SetNull

SetDefault

Instances

Eq ReferenceActionType

Show ReferenceActionType

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, DbDescriptor (PhantomDb m)) => PersistBackend m where

Associated Types

type PhantomDb m

A token which defines the DB type. For example, different monads working with Sqlite, return may Sqlite type.

Methods

insert :: PersistEntity v => v -> m (AutoKey v)

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

insert_ :: PersistEntity v => 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))) => 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 => 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)) => 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))) => 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 (PhantomDb m) (RestrictionHolder v c)) => opts -> m [v]

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

selectAll :: PersistEntity v => m [(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)) => Key v BackendSpecific -> m (Maybe v)

Fetch an entity from a database

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

Fetch an entity from a database by its unique key

update :: (PersistEntity v, EntityConstr v c) => [Update (PhantomDb m) (RestrictionHolder v c)] -> Cond (PhantomDb m) (RestrictionHolder v c) -> m ()

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

delete :: (PersistEntity v, EntityConstr v c) => Cond (PhantomDb m) (RestrictionHolder v c) -> m ()

Remove the records satisfying the condition

deleteBy :: (PersistEntity v, PrimitivePersistField (Key v BackendSpecific)) => Key v BackendSpecific -> m ()

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

deleteAll :: PersistEntity v => v -> m ()

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

count :: (PersistEntity v, EntityConstr v c) => Cond (PhantomDb m) (RestrictionHolder v c) -> m Int

Count total number of records satisfying the condition

countAll :: PersistEntity v => 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 (PhantomDb m) (RestrictionHolder v c) a, HasSelectOptions opts (PhantomDb m) (RestrictionHolder v c)) => p -> opts -> m [a]

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

migrate :: PersistEntity v => v -> Migration m

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

executeRaw

Arguments

:: Bool

keep in cache

-> String

query

-> [PersistValue]

positional parameters

-> m ()

Execute raw query

queryRaw

Arguments

:: Bool

keep in cache

-> String

query

-> [PersistValue]

positional parameters

-> (RowPopper m -> m a)

results processing function

-> m a

Execute raw query with results

insertList :: PersistField a => [a] -> m Int64

getList :: PersistField a => Int64 -> m [a]

class PrimitivePersistField (AutoKeyType db) => DbDescriptor db where

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 RowPopper m = m (Maybe [PersistValue])

newtype DbPersist conn m a

Constructors

DbPersist

Fields

unDbPersist :: ReaderT conn m a

Instances

MonadBaseControl IO m => MonadBaseControl IO (DbPersist conn m)

MonadBase IO m => MonadBase IO (DbPersist conn m)

MonadError e m => MonadError e (DbPersist conn m)

Monad m => MonadReader conn (DbPersist conn m)

MonadState s m => MonadState s (DbPersist conn m)

MonadWriter w m => MonadWriter w (DbPersist conn m)

MonadTrans (DbPersist conn)

MonadTransControl (DbPersist conn)

Monad m => Monad (DbPersist conn m)

Functor m => Functor (DbPersist conn m)

Applicative m => Applicative (DbPersist conn m)

MonadLogger m => MonadLogger (DbPersist conn m)

MonadIO m => MonadIO (DbPersist conn m)

MonadCont m => MonadCont (DbPersist conn m)

type StT (DbPersist conn) a = StT (ReaderT conn) a

type StM (DbPersist conn m) a = ComposeSt (DbPersist conn) m a

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

Connections and transactions

class ConnectionManager cm conn | cm -> 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.

Methods

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

Extracts the connection from manager and opens the transaction.

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

Extracts the connection.

class ConnectionManager cm conn => SingleConnectionManager cm conn

This connection manager always returns the same connection. This constraint is useful when performing operations which make sense only within one connection, for example, nested savepoints..

class Savepoint conn where

Methods

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

Wraps the passed action into a named savepoint