Database.GP.GenericPersistence

Documentation

selectById :: forall a id. (Entity a, Convertible id SqlValue) => Conn -> id -> IO (Maybe a)

This module defines RDBMS Persistence operations for Record Data Types that are instances of Data. I call instances of such a data type Entities.

The Persistence operations are using Haskell generics to provide compile time reflection capabilities. HDBC is used to access the RDBMS.

A function that retrieves an entity from a database. The function takes entity id as parameter. If an entity with the given id exists in the database, it is returned as a Just value. If no such entity exists, Nothing is returned. An error is thrown if there are more than one entity with the given id.

select :: forall a. Entity a => Conn -> WhereClauseExpr -> IO [a]

This function retrieves all entities of type a that match some query criteria. The function takes an HDBC connection and a WhereClauseExpr as parameters. The type a is determined by the context of the function call. The function returns a (possibly empty) list of all matching entities. The WhereClauseExpr is typically constructed using any tiny query dsl based on infix operators.

count :: forall a. Entity a => Conn -> WhereClauseExpr -> IO Int

entitiesFromRows :: forall a. Entity a => Conn -> [[SqlValue]] -> IO [a]

A function that constructs a list of entities from a list of rows. The function takes an HDBC connection and a list of rows as parameters. The type a is determined by the context of the function call. The function returns a list of entities. This can be useful if you want to use your own SQL queries.

sql :: QuasiQuoter

an alias for a simple quasiqouter

persist :: forall a. Entity a => Conn -> a -> IO ()

Deprecated: use upsert instead

A function that persists an entity to a database. The function takes an HDBC connection and an entity as parameters. The entity is either inserted or updated, depending on whether it already exists in the database. The required SQL statements are generated dynamically using Haskell generics and reflection deprecated: use upsert instead

upsert :: forall a. Entity a => Conn -> a -> IO ()

A function that upserts an entity into a database. The function takes an HDBC connection and an entity as parameters. The entity is either inserted or updated, depending on whether it already exists in the database. The required SQL statements are generated dynamically using Haskell generics and reflection

insert :: forall a. Entity a => Conn -> a -> IO a

A function that explicitely inserts an entity into a database.

insertMany :: forall a. Entity a => Conn -> [a] -> IO ()

A function that inserts a list of entities into a database. The function takes an HDBC connection and a list of entities as parameters. The insert-statement is compiled only once and then executed for each entity.

update :: forall a. Entity a => Conn -> a -> IO ()

A function that explicitely updates an entity in a database.

updateMany :: forall a. Entity a => Conn -> [a] -> IO ()

A function that updates a list of entities in a database. The function takes an HDBC connection and a list of entities as parameters. The update-statement is compiled only once and then executed for each entity.

delete :: forall a. Entity a => Conn -> a -> IO ()

A function that deletes an entity from a database. The function takes an HDBC connection and an entity as parameters.

deleteById :: forall a id. (Entity a, Convertible id SqlValue) => Conn -> id -> IO ()

A function that deletes an entity from a database. The function takes an HDBC connection and an entity id as parameters.

deleteMany :: forall a. Entity a => Conn -> [a] -> IO ()

A function that deletes a list of entities from a database. The function takes an HDBC connection and a list of entities as parameters. The delete-statement is compiled only once and then executed for each entity.

deleteManyById :: forall a id. (Entity a, Convertible id SqlValue) => Conn -> [id] -> IO ()

A function that deletes a list of entities from a database. The function takes an HDBC connection and a list of entity ids as parameters.

setupTable :: forall a. Entity a => Conn -> ColumnTypeMapping -> IO ()

set up a table for a given entity type. The table is dropped (if existing) and recreated. The function takes an HDBC connection and a column type mapping as parameters.

defaultSqliteMapping :: ColumnTypeMapping

The default mapping for SQLite databases. This mapping is used when no custom mapping is provided.

defaultPostgresMapping :: ColumnTypeMapping

The default mapping for Postgres databases. This mapping is used when no custom mapping is provided.

data Conn

This module defines a wrapper around an HDBC IConnection. Using this wrapper Conn simplifies the signature of the functions in the GP module. It allows to use any HDBC connection without having to define a new function for each connection type. It also provides additional attributes to the connection, like the database type and the implicit commit flag. These attributes can be used to implement database specific functionality, modify transaction behaviour, etc.

This code has been inspired by the HDBC ConnectionWrapper and some parts have been copied verbatim from the HDBC Database.HDBC.Types module.

This module also defines a ConnectionPool type, which provides basic connection pooling functionality.

A wrapper around an HDBC IConnection.

Constructors

forall conn.IConnection conn => Conn

Fields

• Bool
• conn

  If True, the GenericPersistence functions will commit the transaction after each operation.

Instances

IConnection Conn

manually implement the IConnection type class for the Conn type.

Defined in Database.GP.Conn

Methods

disconnect :: Conn -> IO ()

commit :: Conn -> IO ()

rollback :: Conn -> IO ()

runRaw :: Conn -> String -> IO ()

run :: Conn -> String -> [SqlValue] -> IO Integer

prepare :: Conn -> String -> IO Statement

clone :: Conn -> IO Conn

hdbcDriverName :: Conn -> String

hdbcClientVer :: Conn -> String

proxiedClientName :: Conn -> String

proxiedClientVer :: Conn -> String

dbServerVer :: Conn -> String

dbTransactionSupport :: Conn -> Bool

getTables :: Conn -> IO [String]

describeTable :: Conn -> String -> IO [(String, SqlColDesc)]

connect :: forall conn. IConnection conn => TxHandling -> conn -> Conn

a smart constructor for the Conn type.

data Database

An enumeration of the supported database types.

Constructors

Postgres

SQLite

data TxHandling

Constructors

AutoCommit

ExplicitCommit

type ConnectionPool = Pool Conn

A pool of connections.

createConnPool

Arguments

:: IConnection conn

=> TxHandling

the transaction mode

-> String

the connection string

-> (String -> IO conn)

a function that takes a connection string and returns an IConnection

-> Double

the time (in seconds) to keep idle connections open

-> Int

the maximum number of connections to keep open

-> IO ConnectionPool

the resulting connection pool

Creates a connection pool.

withResource :: Pool a -> (a -> IO r) -> IO r

Take a resource from the pool, perform an action with it and return it to the pool afterwards.

• If the pool has an idle resource available, it is used immediately.
• Otherwise, if the maximum number of resources has not yet been reached, a new resource is created and used.
• If the maximum number of resources has been reached, this function blocks until a resource becomes available.

If the action throws an exception of any type, the resource is destroyed and not returned to the pool.

It probably goes without saying that you should never manually destroy a pooled resource, as doing so will almost certainly cause a subsequent user (who expects the resource to be valid) to throw an exception.

class (Generic a, HasConstructor (Rep a), HasSelectors (Rep a)) => Entity a where

This is the Entity class. It is a type class that is used to define the mapping between a Haskell product type in record notation and a database table. The class has a default implementation for all methods. The default implementation uses the type information to determine a simple 1:1 mapping.

That means that - the type name is used as the table name and the - field names are used as the column names. - A field named 'typeNameID' is used as the primary key field.

The default implementation can be overridden by defining a custom instance for a type.

Please note the following constraints, which apply to all valid Entity type, but that are not explicitely encoded in the type class definition:

• The type must be a product type in record notation.
• The type must have exactly one constructor.
• There must be single primary key field, compound primary keys are not supported.

Minimal complete definition

Nothing

Methods

fromRow :: Conn -> [SqlValue] -> IO a

Converts a database row to a value of type a.

default fromRow :: GFromRow (Rep a) => Conn -> [SqlValue] -> IO a

toRow :: Conn -> a -> IO [SqlValue]

Converts a value of type a to a database row.

default toRow :: GToRow (Rep a) => Conn -> a -> IO [SqlValue]

idField :: String

Returns the name of the primary key field for a type a.

default idField :: String

fieldsToColumns :: [(String, String)]

Returns a list of tuples that map field names to column names for a type a.

default fieldsToColumns :: [(String, String)]

tableName :: String

Returns the name of the table for a type a.

default tableName :: String

autoIncrement :: Bool

Returns True if the primary key field for a type a is autoincremented by the database.

default autoIncrement :: Bool

class GToRow f

Minimal complete definition

gtoRow

Instances

(GToRow a, GToRow b) => GToRow (a :*: b :: k -> Type)

Defined in Database.GP.Entity

Methods

gtoRow :: forall (a0 :: k0). (a :*: b) a0 -> [SqlValue]

Convertible a SqlValue => GToRow (K1 i a :: k -> Type)

Defined in Database.GP.Entity

Methods

gtoRow :: forall (a0 :: k0). K1 i a a0 -> [SqlValue]

GToRow a => GToRow (M1 i c a :: k -> Type)

Defined in Database.GP.Entity

Methods

gtoRow :: forall (a0 :: k0). M1 i c a a0 -> [SqlValue]

class GFromRow f

Minimal complete definition

gfromRow

Instances

(KnownNat (NumFields f), GFromRow f, GFromRow g) => GFromRow (f :*: g :: Type -> Type)

This instance is the most interesting one. It splits the list of SqlValues into two parts, one for the first field and one for the rest. Then it uses the GFromRow instance for the first field to convert the first part of the list and the GFromRow instance for the rest of the fields to convert the second part of the list. Finally, it combines the two results using the :*: constructor. https://stackoverflow.com/questions/75485429/how-to-use-ghc-generics-to-convert-from-product-data-types-to-a-list-of-sqlvalue/75485650#75485650

Defined in Database.GP.Entity

Methods

gfromRow :: forall (a :: k). [SqlValue] -> (f :*: g) a

Convertible SqlValue a => GFromRow (K1 i a :: k -> Type)

Defined in Database.GP.Entity

Methods

gfromRow :: forall (a0 :: k0). [SqlValue] -> K1 i a a0

GFromRow a => GFromRow (M1 i c a :: k -> Type)

Defined in Database.GP.Entity

Methods

gfromRow :: forall (a0 :: k0). [SqlValue] -> M1 i c a a0

columnNameFor :: forall a. Entity a => String -> String

A convenience function: returns the name of the column for a field of a type a.

maybeFieldTypeFor :: forall a. Entity a => String -> Maybe TypeRep

data TypeInfo a

A data type holding meta-data about a type. The Phantom type parameter a ensures type safety for reflective functions that use this type to create type instances.

typeInfo :: forall a. (HasConstructor (Rep a), HasSelectors (Rep a), Generic a) => TypeInfo a

this function is a smart constructor for TypeInfo objects. It takes a value of type a and returns a `TypeInfo a` object. If the type has no named fields, an error is thrown. If the type has more than one constructor, an error is thrown.

data PersistenceException

This is the "safe" version of the module Database.GP.GenericPersistence. It uses Either to return errors.

This module defines RDBMS Persistence operations for Record Data Types that are instances of Data. I call instances of such a data type Entities.

The Persistence operations are using Haskell generics to provide compile time reflection capabilities. HDBC is used to access the RDBMS.

exceptions that may occur during persistence operations

Constructors

EntityNotFound String

DuplicateInsert String

DatabaseError String

NoUniqueKey String

Instances

Exception PersistenceException

Defined in Database.GP.GenericPersistenceSafe

Methods

toException :: PersistenceException -> SomeException

fromException :: SomeException -> Maybe PersistenceException

displayException :: PersistenceException -> String

Show PersistenceException

Defined in Database.GP.GenericPersistenceSafe

Methods

showsPrec :: Int -> PersistenceException -> ShowS

show :: PersistenceException -> String

showList :: [PersistenceException] -> ShowS

Eq PersistenceException

Defined in Database.GP.GenericPersistenceSafe

Methods

(==) :: PersistenceException -> PersistenceException -> Bool

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

data WhereClauseExpr

data Field

field :: String -> Field

(&&.) :: WhereClauseExpr -> WhereClauseExpr -> WhereClauseExpr infixl 3

(||.) :: WhereClauseExpr -> WhereClauseExpr -> WhereClauseExpr infixl 2

(=.) :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

(>.) :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

(<.) :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

(>=.) :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

(<=.) :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

(<>.) :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

like :: Convertible b SqlValue => Field -> b -> WhereClauseExpr infixl 4

between :: (Convertible a1 SqlValue, Convertible a2 SqlValue) => Field -> (a1, a2) -> WhereClauseExpr infixl 4

in' :: Convertible b SqlValue => Field -> [b] -> WhereClauseExpr infixl 4

isNull :: Field -> WhereClauseExpr

not' :: WhereClauseExpr -> WhereClauseExpr

sqlFun :: String -> Field -> Field

allEntries :: WhereClauseExpr

byId :: Convertible a SqlValue => a -> WhereClauseExpr

orderBy :: WhereClauseExpr -> NonEmpty (Field, SortOrder) -> WhereClauseExpr infixl 1

data SortOrder

Constructors

ASC

DESC

Instances

Show SortOrder

Defined in Database.GP.Query

Methods

showsPrec :: Int -> SortOrder -> ShowS

show :: SortOrder -> String

showList :: [SortOrder] -> ShowS

limit :: WhereClauseExpr -> Int -> WhereClauseExpr

limitOffset :: WhereClauseExpr -> (Int, Int) -> WhereClauseExpr

data NonEmpty a

Non-empty (and non-strict) list type.

Since: base-4.9.0.0

Constructors

a :| [a] infixr 5

Instances

Foldable NonEmpty

Since: base-4.9.0.0

Defined in Data.Foldable

Methods

fold :: Monoid m => NonEmpty m -> m

foldMap :: Monoid m => (a -> m) -> NonEmpty a -> m

foldMap' :: Monoid m => (a -> m) -> NonEmpty a -> m

foldr :: (a -> b -> b) -> b -> NonEmpty a -> b

foldr' :: (a -> b -> b) -> b -> NonEmpty a -> b

foldl :: (b -> a -> b) -> b -> NonEmpty a -> b

foldl' :: (b -> a -> b) -> b -> NonEmpty a -> b

foldr1 :: (a -> a -> a) -> NonEmpty a -> a

foldl1 :: (a -> a -> a) -> NonEmpty a -> a

toList :: NonEmpty a -> [a]

null :: NonEmpty a -> Bool

length :: NonEmpty a -> Int

elem :: Eq a => a -> NonEmpty a -> Bool

maximum :: Ord a => NonEmpty a -> a

minimum :: Ord a => NonEmpty a -> a

sum :: Num a => NonEmpty a -> a

product :: Num a => NonEmpty a -> a

Traversable NonEmpty

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> NonEmpty a -> f (NonEmpty b)

sequenceA :: Applicative f => NonEmpty (f a) -> f (NonEmpty a)

mapM :: Monad m => (a -> m b) -> NonEmpty a -> m (NonEmpty b)

sequence :: Monad m => NonEmpty (m a) -> m (NonEmpty a)

Applicative NonEmpty

Since: base-4.9.0.0

Defined in GHC.Base

Methods

pure :: a -> NonEmpty a

(<*>) :: NonEmpty (a -> b) -> NonEmpty a -> NonEmpty b

liftA2 :: (a -> b -> c) -> NonEmpty a -> NonEmpty b -> NonEmpty c

(*>) :: NonEmpty a -> NonEmpty b -> NonEmpty b

(<*) :: NonEmpty a -> NonEmpty b -> NonEmpty a

Functor NonEmpty

Since: base-4.9.0.0

Defined in GHC.Base

Methods

fmap :: (a -> b) -> NonEmpty a -> NonEmpty b

(<$) :: a -> NonEmpty b -> NonEmpty a

Monad NonEmpty

Since: base-4.9.0.0

Defined in GHC.Base

Methods

(>>=) :: NonEmpty a -> (a -> NonEmpty b) -> NonEmpty b

(>>) :: NonEmpty a -> NonEmpty b -> NonEmpty b

return :: a -> NonEmpty a

Generic1 NonEmpty

Defined in GHC.Generics

Associated Types

type Rep1 NonEmpty :: k -> Type

Methods

from1 :: forall (a :: k). NonEmpty a -> Rep1 NonEmpty a

to1 :: forall (a :: k). Rep1 NonEmpty a -> NonEmpty a

Semigroup (NonEmpty a)

Since: base-4.9.0.0

Defined in GHC.Base

Methods

(<>) :: NonEmpty a -> NonEmpty a -> NonEmpty a

sconcat :: NonEmpty (NonEmpty a) -> NonEmpty a

stimes :: Integral b => b -> NonEmpty a -> NonEmpty a

Generic (NonEmpty a)

Defined in GHC.Generics

Associated Types

type Rep (NonEmpty a) :: Type -> Type

Methods

from :: NonEmpty a -> Rep (NonEmpty a) x

to :: Rep (NonEmpty a) x -> NonEmpty a

Read a => Read (NonEmpty a)

Since: base-4.11.0.0

Defined in GHC.Read

Methods

readsPrec :: Int -> ReadS (NonEmpty a)

readList :: ReadS [NonEmpty a]

readPrec :: ReadPrec (NonEmpty a)

readListPrec :: ReadPrec [NonEmpty a]

Show a => Show (NonEmpty a)

Since: base-4.11.0.0

Defined in GHC.Show

Methods

showsPrec :: Int -> NonEmpty a -> ShowS

show :: NonEmpty a -> String

showList :: [NonEmpty a] -> ShowS

Eq a => Eq (NonEmpty a)

Since: base-4.9.0.0

Defined in GHC.Base

Methods

(==) :: NonEmpty a -> NonEmpty a -> Bool

(/=) :: NonEmpty a -> NonEmpty a -> Bool

Ord a => Ord (NonEmpty a)

Since: base-4.9.0.0

Defined in GHC.Base

Methods

compare :: NonEmpty a -> NonEmpty a -> Ordering

(<) :: NonEmpty a -> NonEmpty a -> Bool

(<=) :: NonEmpty a -> NonEmpty a -> Bool

(>) :: NonEmpty a -> NonEmpty a -> Bool

(>=) :: NonEmpty a -> NonEmpty a -> Bool

max :: NonEmpty a -> NonEmpty a -> NonEmpty a

min :: NonEmpty a -> NonEmpty a -> NonEmpty a

type Rep1 NonEmpty

Since: base-4.6.0.0

Defined in GHC.Generics

type Rep1 NonEmpty = D1 ('MetaData "NonEmpty" "GHC.Base" "base" 'False) (C1 ('MetaCons ":|" ('InfixI 'RightAssociative 5) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1 :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec1 List)))

type Rep (NonEmpty a)

Since: base-4.6.0.0

Defined in GHC.Generics

type Rep (NonEmpty a) = D1 ('MetaData "NonEmpty" "GHC.Base" "base" 'False) (C1 ('MetaCons ":|" ('InfixI 'RightAssociative 5) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [a])))