Database.Groundhog

This module exports the most commonly used functions and datatypes.

See http://github.com/lykahb/groundhog/blob/master/examples/.

Core datatypes and functions

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

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)

Defined in Database.Groundhog.Core

Associated Types

type Conn (ReaderT conn m) :: Type

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

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.

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

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

Arguments

:: (PersistBackend m, Conn m ~ conn)

=> Bool

keep in cache

-> String

query

-> [PersistValue]

positional parameters

-> m ()

Execute raw query

queryRaw

Arguments

:: (PersistBackend m, Conn m ~ conn)

=> Bool

keep in cache

-> String

query

-> [PersistValue]

positional parameters

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

data family 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.

Instances

Show (Key v u) => ToJSON (Key v u)

Defined in Database.Groundhog.Instances

Methods

toJSON :: Key v u -> Value

toEncoding :: Key v u -> Encoding

toJSONList :: [Key v u] -> Value

toEncodingList :: [Key v u] -> Encoding

Read (Key v u) => FromJSON (Key v u)

Defined in Database.Groundhog.Instances

Methods

parseJSON :: Value -> Parser (Key v u)

parseJSONList :: Value -> Parser [Key v u]

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

Defined in Database.Groundhog.Instances

type family DefaultKey v

This type is the default key for the entity.

type family AutoKey v

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

data Unique (u :: (* -> *) -> *)

A holder for Unique constraints

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

Defined in Database.Groundhog.Expression

Methods

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

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

Defined in Database.Groundhog.Instances

Methods

fieldChain :: (DbDescriptor db, ProjectionDb (u (UniqueMarker v)) db) => proxy db -> u (UniqueMarker v) -> FieldChain

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

Defined in Database.Groundhog.Instances

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

Defined in Database.Groundhog.Instances

Associated Types

type ProjectionDb (u (UniqueMarker v)) db :: Constraint

type ProjectionRestriction (u (UniqueMarker v)) r :: Constraint

Methods

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

projectionResult :: PersistBackend m => u (UniqueMarker v) -> [PersistValue] -> m (k, [PersistValue])

type ProjectionDb (u (UniqueMarker v)) db

Defined in Database.Groundhog.Instances

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

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

Defined in Database.Groundhog.Instances

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

data BackendSpecific

Key marked with this type can have value for any backend

extractUnique :: (IsUniqueKey uKey, uKey ~ Key v u) => v -> uKey

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

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)

Defined in Database.Groundhog.Expression

Methods

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

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

Defined in Database.Groundhog.Instances

Associated Types

type ProjectionDb (Cond db r) db :: Constraint

type ProjectionRestriction (Cond db r) r :: Constraint

Methods

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

projectionResult :: PersistBackend m => Cond db r -> [PersistValue] -> m (a, [PersistValue])

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

Defined in Database.Groundhog.Core

Associated Types

type HasLimit (Cond db r) :: Type

type HasOffset (Cond db r) :: Type

type HasOrder (Cond db r) :: Type

type HasDistinct (Cond db r) :: Type

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)

Defined in Database.Groundhog.Core

type HasLimit (Cond db r) = HFalse

type HasOffset (Cond db r)

Defined in Database.Groundhog.Core

type HasOffset (Cond db r) = HFalse

type HasOrder (Cond db r)

Defined in Database.Groundhog.Core

type HasOrder (Cond db r) = HFalse

type HasDistinct (Cond db r)

Defined in Database.Groundhog.Core

type HasDistinct (Cond db r) = HFalse

type ProjectionDb (Cond db r) db'

Defined in Database.Groundhog.Instances

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

type ProjectionRestriction (Cond db r) r'

Defined in Database.Groundhog.Instances

type ProjectionRestriction (Cond db r) 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

data family Selector v :: * -> *

Instances

data Selector (a', b') constr

Defined in Database.Groundhog.Instances

data Selector (a', b') constr where

• Tuple2_0Selector :: forall a b constr. Selector (a, b) a
• Tuple2_1Selector :: forall a b constr. Selector (a, b) b

data Selector (a', b', c') constr

Defined in Database.Groundhog.Instances

data Selector (a', b', c') constr where

• Tuple3_0Selector :: forall a b c constr. Selector (a, b, c) a
• Tuple3_1Selector :: forall a b c constr. Selector (a, b, c) b
• Tuple3_2Selector :: forall a b c constr. Selector (a, b, c) c

data Selector (a', b', c', d') constr

Defined in Database.Groundhog.Instances

data Selector (a', b', c', d') constr where

• Tuple4_0Selector :: forall a b c d constr. Selector (a, b, c, d) a
• Tuple4_1Selector :: forall a b c d constr. Selector (a, b, c, d) b
• Tuple4_2Selector :: forall a b c d constr. Selector (a, b, c, d) c
• Tuple4_3Selector :: forall a b c d constr. Selector (a, b, c, d) d

data Selector (a', b', c', d', e') constr

Defined in Database.Groundhog.Instances

data Selector (a', b', c', d', e') constr where

• Tuple5_0Selector :: forall a b c d e constr. Selector (a, b, c, d, e) a
• Tuple5_1Selector :: forall a b c d e constr. Selector (a, b, c, d, e) b
• Tuple5_2Selector :: forall a b c d e constr. Selector (a, b, c, d, e) c
• Tuple5_3Selector :: forall a b c d e constr. Selector (a, b, c, d, e) d
• Tuple5_4Selector :: forall a b c d e constr. Selector (a, b, c, d, e) e

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)

Defined in Database.Groundhog.Expression

Methods

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

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

Defined in Database.Groundhog.Instances

Methods

fieldChain :: (DbDescriptor db, ProjectionDb (AutoKeyField v c) db) => proxy db -> AutoKeyField v c -> FieldChain

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

Defined in Database.Groundhog.Instances

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

Defined in Database.Groundhog.Instances

Associated Types

type ProjectionDb (AutoKeyField v c) db :: Constraint

type ProjectionRestriction (AutoKeyField v c) r :: Constraint

Methods

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

projectionResult :: PersistBackend m => AutoKeyField v c -> [PersistValue] -> m (a, [PersistValue])

type ProjectionDb (AutoKeyField v c) db

Defined in Database.Groundhog.Instances

type ProjectionDb (AutoKeyField v c) db = ()

type ProjectionRestriction (AutoKeyField v c) r

Defined in Database.Groundhog.Instances

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

(~>) :: (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"

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)

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

Deprecated: Use deleteBy instead

Expressions

(=.) :: (Assignable f a', ProjectionDb f db, ProjectionRestriction f r, Expression db r b, Unifiable f b) => f -> b -> Update db r infixr 3

Update field

(&&.) :: Cond db r -> Cond db r -> Cond db r infixr 3

Boolean "and" operator.

(||.) :: Cond db r -> Cond db r -> Cond db r infixr 2

Boolean "or" operator.

(==.) :: (Expression db r a, Expression db r b, Unifiable a b) => a -> b -> Cond db r infix 4

(/=.) :: (Expression db r a, Expression db r b, Unifiable a b) => a -> b -> Cond db r infix 4

(<.) :: (Expression db r a, Expression db r b, Unifiable a b) => a -> b -> Cond db r infix 4

(<=.) :: (Expression db r a, Expression db r b, Unifiable a b) => a -> b -> Cond db r infix 4

(>.) :: (Expression db r a, Expression db r b, Unifiable a b) => a -> b -> Cond db r infix 4

(>=.) :: (Expression db r a, Expression db r b, Unifiable a b) => a -> b -> Cond db r infix 4

isFieldNothing :: (Expression db r f, Projection f (Maybe a), PrimitivePersistField (Maybe a), Unifiable f (Maybe a)) => f -> Cond db r

This function more limited than (==.), but has better type inference. If you want to compare your value to Nothing with (==.) operator, you have to write the types explicitly myExpr ==. (Nothing :: Maybe Int). TODO: restrict db r

liftExpr :: ExpressionOf db r a a' => a -> Expr db r a'

Converts value to Expr. It can help to pass values of different types into functions which expect arguments of the same type, like (+).

toArith :: ExpressionOf db r a a' => a -> Expr db r a'

Deprecated: Please use liftExpr instead

It is kept for compatibility with older Groundhog versions and can be replaced with "liftExpr".

Migration

createMigration :: Monad m => Migration m -> m NamedMigrations

Produce the migrations but not execute them. Fails when an unsafe migration occurs.

executeMigration :: (PersistBackend m, MonadIO m) => NamedMigrations -> m ()

Execute the migrations with printing to stderr. Fails when an unsafe migration occurs.

executeMigrationUnsafe :: (PersistBackend m, MonadIO m) => NamedMigrations -> m ()

Execute migrations. Executes the unsafe migrations without warnings and prints them to stderr

runMigration :: (PersistBackend m, MonadIO m) => Migration m -> m ()

Creates migrations and executes them with printing to stderr. Fails when an unsafe migration occurs. > runMigration m = createMigration m >>= executeMigration

runMigrationUnsafe :: (PersistBackend m, MonadIO m) => Migration m -> m ()

Creates migrations and executes them with printing to stderr. Executes the unsafe migrations without warnings > runMigrationUnsafe m = createMigration m >>= executeMigrationUnsafe

printMigration :: MonadIO m => NamedMigrations -> m ()

Pretty print the migrations